feat: attribution topic (report, metrics, dimensions, values)

[seifer]

What

A new adapty attribution topic. It reads Attribution analytics for an app, the same data as the Attribution dashboard, so customers and their agents can query it from the terminal.

Command	What it does
attribution metrics	Metric catalog (name, unit, family, whether it is spend-based, ratio denominator) plus the request limits
attribution dimensions	Dimensions: groupable/filterable, identity, date granularities
attribution values	The values a dimension takes for an app over a period, i.e. what --filter can use
attribution report	Metrics over a period for one app, grouped by dimensions, with totals

Built on the migrated stack, the same way asa is: src/sdk/attribution → src/cli/base/attribution → src/cli/commands/attribution, with one-line shims in src/commands.

It talks to https://api-ua.adapty.io/api/v1/cli with the existing developer session. ADAPTY_ATTRIBUTION_API_URL overrides the URL.

Contract points agents rely on

• null means not computable, never zero. The human view prints —. Apple Search Ads has no spend source in Attribution, so its spend-based values are null, as are totals ratios once any row lacks spend.
• Usage errors exit 2 in both human and --json mode, API errors exit 4, network errors exit 5, auth errors exit 3.
• A 429 or 503 carries retry_after_seconds in the --json error.
• report and values are sent once and never retried.
• Catalog reads retry once. A long server Retry-After surfaces as an error immediately instead of a silent sleep.
• Agent docs are in docs/agent/attribution.md and the skill references. check-agent-docs now also covers the attribution commands.

Backend

The Attribution backend /api/v1/cli has been in production since 2026-09-24. A follow-up backend MR drops two meta hints (max_valid_day, spend_channels) that this CLI no longer reads, so the order of the two releases doesn't matter.

Verification

• pnpm install --frozen-lockfile, pnpm build, pnpm check:agent-docs, pnpm test (442 passing, eslint clean) and tsc --noEmit, on the branch rebased onto main.
• Smoke-tested against production with a real session:
  • metrics, dimensions, values, and report by channel, weekly, with predictions, and with an ASA-only filter;
  • error paths: unknown metric (exit 4), window too wide (exit 4), --group-by date without --granularity (exit 2 before any request), malformed --filter under --json (exit 2), and an app the token cannot read (exit 4, attribution_app_not_found).

Release

package.json is bumped to 0.8.8. Per onPushToMain.yml + onTag.yml, merging creates the v0.8.8 tag and GitHub release, publishes to npm as latest, and dispatches the doc sync to apple-ads-cli. Drop the chore: bump version to 0.8.8 commit to merge without releasing.

🤖 Generated with Claude Code