# Site Data Integration

## When to use

Use this skill whenever a task requires reading web analytics for a site (visitors, pageviews, traffic sources, heatmaps, realtime activity, goals, funnels, or uptime), or when a site record itself needs to be created, updated, listed, or removed in Site Data. Typical triggers: a report asking for traffic trends, a request to check whether a site is currently up, a request to register a new site for tracking, or a downstream agent needing a site's `api_key`/`domain_key` before it can push events.

## Tools

- `http-get` — read-only calls (list/fetch sites, overview, breakdown, heatmap, confetti, realtime, goals, funnels, uptime)
- `http-post` — create a new site
- `http-request` — update (PATCH) or delete (DELETE) an existing site
- `write-file` — stage large result sets (breakdowns, confetti data, incident lists) instead of inlining them
- `send-message` — escalate to a human on auth failure, missing Integration, or ambiguous site identity

## Playbook

1. Resolve which site you are working with. Call `http-get` on `/api/v1/sites` to list all sites owned by the authenticated user and match by name or domain. If the site does not exist yet and the task calls for tracking a new domain, call `http-post` on `/api/v1/sites` to create it (or return the existing one matching that domain) — capture the returned `id`, `api_key`, and `domain_key`.
2. To confirm or refresh details for a known site, call `http-get` on `/api/v1/sites/:id`.
3. For a traffic summary (visitors, pageviews, sessions) over a period, call `http-get` on `/api/v1/sites/:id/overview`, passing the requested period as query parameters.
4. For a breakdown by dimension (source, page, device, etc.), call `http-get` on `/api/v1/sites/:id/breakdown` with the dimension and period as query parameters.
5. For click/scroll heatmap data, first call `http-get` on `/api/v1/sites/:id/heatmap/pages` to see which pages have data, then call `http-get` on `/api/v1/sites/:id/heatmap` for the chosen page. For individual click events, use `http-get` on `/api/v1/sites/:id/confetti`.
6. For live visitor activity, call `http-get` on `/api/v1/sites/:site_id/stats/realtime`.
7. For conversion tracking, call `http-get` on `/api/v1/sites/:site_id/stats/goals` for goals or `/api/v1/sites/:site_id/stats/funnels` for funnel stats.
8. For availability monitoring, call `http-get` on `/api/v1/sites/:site_id/stats/uptime` for the current status summary, and `/api/v1/sites/:site_id/stats/uptime/incidents` for the incident history.
9. To rename a site, change its domain, or update its timezone, use `http-request` with PATCH against `/api/v1/sites/:id`.
10. To decommission a site, use `http-request` with DELETE against `/api/v1/sites/:id`. Confirm this is intended before deleting — it is destructive.
11. When any response set is large (long breakdown tables, confetti event dumps, multi-day incident logs), use `write-file` to stage the raw payload before summarizing it, rather than pasting it inline.

## Failure modes

- 401 or 403 on any call: stop immediately, do not retry, and use `send-message` to notify a human, naming "Site Data" as the app and stating that the integration's credentials need the `sites` read/write scope re-checked.
- No Integration row configured for Site Data in the org: use `send-message` to ask a human to add one before proceeding — do not fabricate a base URL or API key.
- Ambiguous or missing site identity (name/domain doesn't match any listed site): re-list sites with `http-get` on `/api/v1/sites` and, if still unresolved, use `send-message` to ask a human to confirm which site is intended rather than guessing an `id`.
- Empty or zeroed analytics response: treat as a valid "no traffic in period" result, not an error — do not retry the same call repeatedly.

## Done when

The requested site data has been fetched, summarized, or staged via `write-file`, or the requested site record has been created, updated, or deleted and its confirmation (id, api_key/domain_key, or deletion acknowledgment) has been reported back.