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 /analytic...

# DataFast Analytics OpenClaw Skill

Query DataFast website analytics and visitor data from OpenClaw. This skill wraps the DataFast API and summarizes results for common analytics questions (overview, time series, realtime, breakdowns, visitors, goals, and payments).

## Requirements

- OpenClaw installed
- A DataFast API key (get yours from [datafa.st](https://datafa.st))

## Installation

Clone or copy the skill into your OpenClaw workspace:

```bash
git clone https://github.com/bennyqp/datafast-analytics-openclaw-skill.git ~/.openclaw/workspace/skills/datafast-analytics
```

OpenClaw loads skills from `<workspace>/skills` with highest precedence.

## Configure API Key

Store your API key in a config file:

```bash
mkdir -p ~/.config/datafast
echo "df_your_api_key_here" > ~/.config/datafast/api_key
```

The skill reads the key from `~/.config/datafast/api_key` on each request.

## Usage

Ask OpenClaw analytics questions such as:

- "Show visitors and revenue for the last 30 days."
- "Visitors from X in the last 24 hours."
- "Realtime active visitors right now."
- "Top pages by visitors."
- "Create a custom goal for a visitor."

## What It Calls

Base URL: `https://datafa.st/api/v1/`

Common endpoints:

- `GET /analytics/overview`
- `GET /analytics/timeseries`
- `GET /analytics/realtime`
- `GET /analytics/realtime/map`
- `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`
- `GET /visitors/{datafast_visitor_id}`
- `POST /goals`
- `DELETE /goals`
- `POST /payments`
- `DELETE /payments`

## Filters and Time Ranges

Use `startAt` and `endAt` together for time windows. For segmentation, use `filter_*` parameters supported by the DataFast API (example: `filter_referrer=is:x.com`). See the full API docs in `references/d...