datafast-analytics

通过 DataFast API 查询 DataFast 网站分析和访客数据，以获取指标、时间序列、实时统计数据、故障、访客详细信息和目标/付款管理。

# 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.

---

## 中文说明

# DataFast Analytics Skill

使用此技能调用 DataFast API 并为用户汇总结果。

## 快速工作流程

1. 确认请求类型（overview、timeseries、realtime、breakdown、visitor、goals/payments 创建/删除）。
2. 收集所需输入：
   - 日期范围：`startAt` 和 `endAt` 同时提供或都不提供（overview/timeseries 支持范围）。
   - `timezone`、`fields`、`interval`、`limit`、`offset` 以及任何 `filter_*` 参数。
3. 使用 `Authorization: Bearer $DATAFAST_API_KEY` 和 `Content-Type: application/json` 构建 HTTP 请求。
4. 用 `curl` 执行并解析 JSON。
5. 用表格加一段简短叙述（总计 + 关键要点）汇总结果。如相关，附上分页信息。

## 设置

1. 从 DataFast 获取你的 API 密钥（以 `df_` 开头）。
2. 存储它：
```bash
mkdir -p ~/.config/datafast
echo "df_your_key_here" > ~/.config/datafast/api_key
```

## 认证

所有请求都需要：
```bash
DATAFAST_API_KEY=$(cat ~/.config/datafast/api_key)
curl ... \
  -H "Authorization: Bearer $DATAFAST_API_KEY" \
  -H "Content-Type: application/json"
```

如果用户尚未设置 API 密钥，请要求他们按照上面的设置步骤操作。

## Base URL

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

## 参考文档

使用 `{baseDir}/references/datafast-api-docs.md` 中的完整 API 参考，了解端点详情、响应字段和示例。

## 端点指引

### Overview
- `GET /analytics/overview`
- 可选：`startAt`、`endAt`、`timezone`、`fields`。

### Time Series
- `GET /analytics/timeseries`
- 典型参数：`fields`、`interval`（hour/day/week/month）、`startAt`、`endAt`、`timezone`、`limit`、`offset`。
- 接受 `filter_*` 查询参数用于细分。
- **注意：** `fields` 为必填（例如 `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
- 创建目标：`POST /goals`
- 删除目标：`DELETE /goals`（至少需要一个过滤器或时间范围；确认范围）

### Payments
- 创建支付：`POST /payments`
- 删除支付：`DELETE /payments`（确认范围）

## 破坏性操作

对于 `DELETE /goals` 或 `DELETE /payments`：
- 在执行前，始终用清晰的自然语言确认确切的过滤器和时间范围。
- 如果用户要求删除"全部时间"的数据，请要求明确确认。
- 回显将被调用的最终 URL（不含 API 密钥）。

## 过滤器语法

使用 `filter_*` 参数进行细分（例如 `filter_referrer=is:X`）。

**重要：** 过滤器值必须与 breakdown 端点的确切名称匹配。例如，X/Twitter 存储为 "X"（不是 "x.com" 或 "twitter.com"）。如有疑问，先查询 breakdown：
```bash
curl ... "/analytics/referrers?limit=20"
```
然后在你的过滤器中使用确切的 `referrer` 值。

## 命令模式示例

### 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"
```

## 输出预期

- 提供简短摘要和一个扁平的结果表格。
- 在存在时包含总计和转化/收入指标。
- 对于 time series，包含顶层总计以及所选范围内的首/末时间戳。
- 如果存在分页，报告 `limit`、`offset` 和 `total`，并询问用户是否需要下一页。