release: explicit metrics (ASA-794) and add-as-keyword target ad groups (ASA-799)

[adressop6789-max]

Release branch combining the two open feature PRs for a single merge into main, plus a patch version bump.

Supersedes #22 and #23 — both carry the same commits as this branch, so close them without merging once this lands, or main gets each commit twice.

	Branch	Commits
#22	feature/ASA-794-explicit-metrics	d91200f, f78c5e9
#23	feature/ASA-799-automation-target-ad-groups	ca8c303, 7bc17a5, f5b636f

ASA-794 — explicit metrics and scope flags

asa metrics no longer defaults to every metric: --metric is now required, because every metric named is computed over the whole entity set. subscribers and paid_subscribers — and arppu / arpas, which derive from them — count unique profiles per entity and cost roughly seventeen times the rest, so they are refused unless --campaign or --ad-group scopes the call. The new --app / --campaign / --ad-group scope flags are also the cheapest way to make any metrics call fast, since cost follows the number of entities aggregated rather than the page size. docs/agent/asa-metrics.md documents the guard for every entity.

ASA-799 — target ad groups for the add-as-keyword action

A customer created 43 automation rules through asa automations create --file rule.json; every one came out as "Add as keyword (EXACT) to 0 ad groups". Their stored params were the add-as-negative-keyword shape ({"target_type": ..., "ids": [...]}) applied to an add-as-keyword-to action. Server-side params is a pydantic union with no discriminator: it matched the foreign shape, kept targets.ids, and silently dropped cpt_bid, match_type, negate and skip_enable_duplicate_keywords. The target ad group was correct all along — its id just landed in targets.ids instead of targets.internal_ids. Every call answered 200.

The shape was copied off a neighbouring add-as-negative-keyword rule of the same company, where those exact params are valid. There was nothing to check against: the rule.json schema was documented nowhere.

So this adds flags that assemble a correct body without hand-written JSON — --target-ad-group (repeatable), --match-type, --cpt-bid-type, --cpt-bid, --negate / --no-negate, --skip-enable-duplicates, --pause-original — on both create and update. Which flags apply follows the rule's operate_with, and a mismatch exits 2 instead of being silently mis-resolved. --cpt-bid-type and --match-type have no default here or in the API, so the CLI demands them rather than guessing at a spend and a reach decision. On update an action flag becomes a read-modify-write that rebuilds params from scratch and writes the whole actions list back, which is what repairs the rules already created. The schema now lives in the README, docs/agent/asa-management.md, skills/adapty-cli/references/cli-commands.md and the agent playbook, which gains a harvester recipe, a repair recipe, and this bug in "what the failed sessions did wrong".

Server-side validation (422 on a wrong params shape) is a separate change in asa-analytics and is not a dependency.

Version

0.8.2 → 0.8.3. No tag created — that belongs on main at release time via npm version.

Merge

Both branches merged into a branch cut from origin/main, --no-ff. No conflicts: ASA-794 and ASA-799 both touch src/lib/asa-flags.ts and test/commands/asa-writes.test.ts, but in different places, so the auto-merge is textual only. Verified as an exact union — the diff of this branch against feature/ASA-794-explicit-metrics contains only ASA-799's files, and against feature/ASA-799-automation-target-ad-groups only ASA-794's.

Both features confirmed live in the combined build: asa metrics without --metric fails with Missing required flag metric, and all six action flags show up on asa automations update --help.

pnpm build               ✓
mocha                    192 passing, 0 failing
npx eslint src test bin  0 errors (1 pre-existing warning in auth/login.ts)
pnpm check:agent-docs    ✓ 37 commands

pnpm test exits 1 overall on my machine, but not from the tests: its posttest runs pnpm lint, and eslint takes its ignores from .gitignore only, so it walks into a local .claude/worktrees/ git worktree and lints its built dist/. Unrelated to this branch — happy to add .claude/ to .gitignore separately if CI trips on it.

[adressop6789-max]

Superseded by #25 — same tree, rebuilt on a cleanly named branch.