wb-26: adapty analytics, the analytics of an app from the Developer API

[kenaku]

feat: adapty analytics, the analytics of an app from the Developer API. Spec: adaptyteam/headless-workbench#26.

Summary

A new topic adapty analytics reads the analytics of one app as the dashboard shows them, with the same developer token as the rest of the CLI: one login reads every app the token can access. All commands are read-only and take --app.

Command	Required	Optional
analytics catalog	--app
analytics values	--app, --dimension
analytics chart	--app, --chart, --date-from, --date-to	--compare-from/--compare-to, --group-by, --filter (repeatable), --granularity, --revenue-basis (money charts), --timezone, --csv
analytics conversion	--app, --conversion, --date-from, --date-to	--compare-from/--compare-to, --group-by, --filter, --granularity, --timezone, --csv
analytics funnel	--app, --date-from, --date-to	--group-by, --filter, --timezone, --csv
analytics retention	--app, --date-from, --date-to	--group-by, --filter, --use-trial, --timezone, --csv
analytics ltv	--app, --date-from, --date-to	--group-by, --filter, --revenue-basis, --period-type, --renewal-days, --timezone, --csv
analytics cohort	--app, --date-from, --date-to	--filter, --granularity, --revenue-basis, --period-type, --renewal-days, --timezone, --csv

Names and flags follow the attribution commands. Only chart and conversion take a compared period.

src/
├── commands/analytics/*.ts          # one-line re-exports (8)
├── cli/commands/analytics/*.ts      # flags, local checks, output choice
├── cli/views/analytics/             # human table (human.ts) and CSV (segments.ts), made from the answer
├── cli/input/{filter,period}.ts     # value splitting and day range, shared with attribution
├── sdk/adapty/analytics/            # resource on the Developer API, query rules
└── sdk/core/dates.ts                # date rule, shared with attribution

Outputs. Every data command answers in one shape: data.value (the number of the period), data.segments with the total first (key null), then one segment per group, and meta.query (the query that ran, with defaults and the time zone).

• default: a short table for a human: a heading (what the answer is, the period, the time zone, the filters), then one row per group, total first, with the main numbers of the command and one column per point; money has 2 decimals; null prints as —; a compared period has its own table; an empty window prints No data for this period. and the summary;
• --json: the API answer unchanged;
• --csv: a table the CLI makes from that answer: one row per group, total first; a compared period in compare.* columns on the same row; --csv with --json is refused.

The CSV reads its fields from the answer, so a field the API adds later shows without a CLI change. Where the table leaves fields out, one line under it says that --json and --csv give every field.

The CLI keeps no list of chart or conversion names: which names exist is the server's knowledge (docs/architecture.md). analytics catalog lists them, and the API refuses an unknown name.

Group keys. A group key is the raw value that the API gives for the group. It is not promised to be a --filter value (a funnel group key is its title and can repeat; every group stays in the output, matched by position). Take filter values from analytics values. The total is found only by is_total, never by a null key. Details: docs/agent/analytics.md.

Exit codes.

Exit	When
0	success
2	bad input, nothing sent: app UUID, dates (shape, real day, order), compare with both ends, --renewal-days without --period-type days (whole days, ascending, once), --filter without =, --csv with --json. The message names the flag.
3	no token: "Not authenticated. Run adapty auth login."; also a 403 (no access to the app)
4	a server refusal, with the API error code (unknown chart, conversion, grouping, filter key or time zone, --revenue-basis on a chart that is not about money; 429 with retry_after_seconds in --json; a success that is not the API envelope: malformed_response)

Also: the date rule, the day-range flag factory and the dimension=value splitting are now shared in src/cli/input/ and src/sdk/core/; each product keeps its own --filter parser (attribution behavior unchanged, its tests pass); docs (docs/agent/analytics.md, the skill, cli-commands.md, README, architecture), check-agent-docs for the new topic; version 0.10.0.

Evidence

• Before: adapty analytics does not exist.
• After: test/commands/analytics.test.ts and test/sdk/adapty/analytics/*.test.ts:

flags -> request body, per command
each exit-2 rule -> exit 2, message names the flag, fetch called 0 times
--csv: header + one row per group, total first; compare.* columns; empty window: header only, "No data" on stderr
human table: heading, one row per group, total first, money at 2 decimals, — for null; "No data for this period." with the summary
no token -> exit 3 with the login hint; server refusal -> exit 4 with the code; 429 -> exit 4 with the wait

pnpm build, pnpm check:agent-docs and pnpm test (with lint) pass: 805 tests.

Verification

The commands were run against the backend change on a test stand: the catalog, an empty window (No data for this period.), --json / --csv / human output for each data command, the local refusals and the exit codes. Results: see the evidence bundle in the spec issue adaptyteam/headless-workbench#26.

The last two commits (no drill-down, a group key is the raw backend value; every group kept when a key repeats in one period) were run on the stand: the checks for the catalog, empty windows, the three outputs, local refusals and exit codes pass, and a wrong chart or conversion name exits 4 with the API code.

Merge Danger

Door: two-way in code, one-way after a release

New commands only; attribution behavior is unchanged. Once 0.10.0 is published, the command names, flags, CSV columns and exit codes are a public interface that agents and scripts use.

Blast Radius: small

New topic. The shared input code touches the attribution report flags (same behavior, tests updated).

Owners: CODEOWNERS gives the new analytics paths to the default owners @mlnchk @gshteynardt. package.json and skills/adapty-cli/references/cli-commands.md have no owner.

Order: release after the Developer API analytics routes are live; until then the commands get 404.

Open points for the reviewer

• A 403 exits 3, not 4. The CLI maps every HTTP 403 to exit 3 (existing mapping for all commands), so a token without access to the app exits 3 like a missing token. The existing mapping is kept and documented; the spec now says so (decision 11).
• A wrong chart or conversion name costs one API call. The server refuses it with exit 4 and names the field; a new name in the API needs no CLI release.
• A bad --timezone is not checked locally: the API refuses it (exit 4).
• API numbers of cohort and LTV can differ in the last decimal digits between identical calls (backend float sums).