# Analyga Integration

This project uses Analyga for analytics — stats, events, funnels, network rollups and server-side ingest — via the `tga` CLI. You (the agent) drive it yourself. It fired the events; it reads its own numbers back.

## Setup (one-time)

```bash
npm install -g analyga
tga login --key YOUR_API_KEY
```

Config lives in `.analyga/config.json` and is auto-loaded. No account yet? Create one with no card and no admin in the loop:

```bash
tga signup --slug my-app --name "My App" --username you --password YOUR_PASSWORD
```

No CLI (Claude Web, Raycast, other web agents)? Use the remote MCP server instead, same API key:
URL: `https://mcp.analyga.com/sse` (Authorization: Bearer YOUR_API_KEY)

## Every session: load the schema FIRST

```bash
tga agent-schema --json
```

Returns the authoritative JSON of EVERY command, flag, type and error code. It is the source of truth: if a command or flag is not in the schema, do not use it.

## Identity check

Run `tga whoami` to confirm WHICH tenant you are about to write to before any ingest. It reports which credential won (flag, env, or project config), and — for a `tga_` tenant key — the tenant and key scope. On a multi-tenant platform, a wrong tenant means writing another company's data.

## Reads vs writes

Querying stats, events, funnels and network rollups is READ-ONLY. Emitting events (`tga send`), minting/revoking ingest keys, and checkout are WRITES. Every command takes `--json`.

## Operating rhythm

- QUERY: `tga stats <websiteId> --from 7d` and `tga events <websiteId> --from 24h` return aggregates, not raw rows — branch on the numbers, do not render a dashboard.
- FUNNELS: define once, run anytime — `tga funnel define <websiteId> --name signup --steps "a,b,c"` then `tga funnel run <funnelId> --from 30d`. Prefer event NAMES over URLs so steps work across web, CLI and MCP.
- NETWORK: `tga network <teamId> --from 7d` rolls up every site in a team. It returns two visitor numbers on purpose: `visitorsSumOfSites` is NOT deduplicated across sites; `identifiedVisitors` is. Never report the first as "unique visitors".
- INGEST: `tga send <websiteId> --name <event> --id <stable-user-id>`. ALWAYS pass `--id` with a stable per-user identifier from your auth context — without it, agent traffic sharing a user-agent and egress IP collapses into a single visitor, and it cannot be backfilled.
- A discarded event still answers HTTP 200. This CLI treats a bot-dropped event as a HARD FAILURE with a hint, so you never believe a dropped event succeeded. Check landings with `tga ingest health <websiteId> --from 1h`.
- KEYS: server-side ingest uses a SEPARATE per-website key. Mint with `tga ingest-key create <websiteId>` (shown once; regenerating rotates it), revoke with `tga ingest-key revoke <websiteId>`. It can only ever write that one site's traffic.

## Billing (agents never touch cards)

`tga billing checkout --plan <id>` returns a Stripe Checkout URL to hand to a human who completes payment. The tenant is pinned server-side from your key. The free plan is not purchasable, and internal sister-stack tenants are never billed.

Rule of thumb: load the schema, confirm the tenant, pass `--id` on every send, and verify events landed instead of trusting a 200.