datafast-analytics

# DataFast Analytics Skill Use this skill to call the DataFast API and summarize results for the user. ## Quick Workflow 1. Confirm the request type (overview, timeseries, realtime, breakdown, visitor, goals/payments create/delete). 2. Gather required inputs: - Date range: `startAt` and `endAt` together or neither (overview/timeseries support ranges). - `timezone`, `fields`, `interval`, `limit`, `offset`, and any `filter_*` parameters. 3. Build the HTTP request with `Authorization: Bearer $DATAFAST_API_KEY` and `Content-Type: application/json`. 4. Execute with `curl` and parse JSON. 5. Summarize results in a table plus a short narrative (totals + key takeaways). Include pagination info if relevant. ## Setup 1. Get your API key from DataFast (starts with `df_`). 2. Store it: ```bash mkdir -p ~/.config/datafast echo "df_your_key_here" > ~/.config/datafast/api_key ``` ## Authentication All requests need: ```bash DATAFAST_API_KEY=$(cat ~/.config/datafast/api_key) curl ... \ -H "Authorization: Bearer $DATAFAST_API_KEY" \ -H "Content-Type: application/json" ``` If the user hasn't set up the API key, ask them to follow the setup steps above. ## Base URL `https://datafa.st/api/v1/` ## Reference Docs Use the full API reference at `{baseDir}/references/datafast-api-docs.md` for endpoint details, response fields, and examples. ## Endpoint Guidance ### Overview - `GET /analytics/overview` - Optional: `startAt`, `endAt`, `timezone`, `fields`. ### Time Series - `GET /analytics/timeseries` - Typical params: `fields`, `interval` (hour/day/week/month), `startAt`, `endAt`, `timezone`, `limit`, `offset`. - Accepts `filter_*` query params for segmentation. - **Note:** `fields` is required (e.g., `fields=visitors,sessions`). ### Realtime - `GET /analytics/realtime` - `GET /analytics/realtime/map` ### Breakdowns - `GET /analytics/devices` - `GET /analytics/pages` - `GET /analytics/campaigns` - `GET /analytics/goals` - `GET /analytics/referrers` - `GET /analytics/countries` - `GET /analytics/regions` - `GET /analytics/cities` - `GET /analytics/browsers` - `GET /analytics/operating-systems` - `GET /analytics/hostnames` ### Visitor Details - `GET /visitors/{datafast_visitor_id}` ### Goals - Create goal: `POST /goals` - Delete goals: `DELETE /goals` (requires at least one filter or time range; confirm scope) ### Payments - Create payment: `POST /payments` - Delete payments: `DELETE /payments` (confirm scope) ## Destructive Actions For `DELETE /goals` or `DELETE /payments`: - Always confirm exact filters and time range in plain English before executing. - If user asks for "all time" deletion, ask for explicit confirmation. - Echo the final URL that will be called (without the API key). ## Filter Syntax Use `filter_*` params for segmentation (e.g., `filter_referrer=is:X`). **Important:** Filter values must match the exact names from breakdown endpoints. For example, X/Twitter is stored as "X" (not "x.com" or "twitter.com"). When in doubt, query the breakdown first: ```bash curl ... "/analytics/referrers?limit=20" ``` Then use the exact `referrer` value in your filter. ## Example Command Patterns ### GET ```bash DATAFAST_API_KEY=$(cat ~/.config/datafast/api_key) curl -sS "https://datafa.st/api/v1/analytics/overview?startAt=2024-01-01&endAt=2024-01-31&timezone=UTC" \ -H "Authorization: Bearer $DATAFAST_API_KEY" \ -H "Content-Type: application/json" ``` ### POST ```bash DATAFAST_API_KEY=$(cat ~/.config/datafast/api_key) curl -sS "https://datafa.st/api/v1/goals" \ -H "Authorization: Bearer $DATAFAST_API_KEY" \ -H "Content-Type: application/json" \ -d '{"datafast_visitor_id":"...","name":"newsletter_signup","metadata":{"email":"..."}}' ``` ### DELETE ```bash DATAFAST_API_KEY=$(cat ~/.config/datafast/api_key) curl -sS -X DELETE "https://datafa.st/api/v1/goals?name=signup&startAt=2023-01-01T00:00:00Z&endAt=2023-01-31T23:59:59Z" \ -H "Authorization: Bearer $DATAFAST_API_KEY" ``` ## Output Expectations - Provide a short summary and a flat table of results. - Include totals and conversion/revenue metrics when present. - For time series, include the top-level totals and the first/last timestamps in the selected range. - If pagination exists, report `limit`, `offset`, and `total`, and ask if the user wants the next page.