adapty 0.8.4-beta.1 → 0.8.4

package/README.md

@@ -199,12 +199,142 @@ adapty asa product-pages sync [--adam-id 123456]
 
 adapty asa automations list
 adapty asa automations get AUTOMATION_ID
-adapty asa automations create --file rule.json [--run-now]
-adapty asa automations update AUTOMATION_ID [--stop] [--start] [--name "..."] [--file rule.json]
+adapty asa automations create --file rule.json [--run-now] [--target-ad-group UUID ...]
+adapty asa automations update AUTOMATION_ID [--stop] [--start] [--name "..."] [--file rule.json] [--target-ad-group UUID ...]
 adapty asa automations run AUTOMATION_ID [--dry-run]
 adapty asa automations runs AUTOMATION_ID
 ```
 
+A rule file carries the whole rule: `name`, `status` (1 active, 0 stopped), `operate_with` (what the
+rule iterates over), `apply_to` (where it looks), exactly one condition, exactly one action and a
+`run_frequency`. The API stores one action and one condition per rule and rejects anything else.
+
+| Field           | Shape                                                                                       |
+| --------------- | ------------------------------------------------------------------------------------------- |
+| `operate_with`  | `search-term`, `targeting-keyword`, `campaign`, `ad-group`                                   |
+| `apply_to[]`    | `{"internal_id": UUID, "type": "campaign-group" \| "app" \| "campaign" \| "ad-group" \| "targeting-keywords"}` |
+| `conditions[0]` | `{"operator": ..., "args": number, "operand": {...}}`, or `{"operator": "and" \| "or", "args": [condition, ...]}` |
+| `operator`      | `eq`, `neq`, `gt`, `gte`, `lt`, `lte` for a leaf; `and`, `or` to nest                        |
+| `operand.field` | a metric name in dashboard nomenclature — the same vocabulary `asa metrics --metric` takes    |
+| `date_range_type` | `today`, `yesterday`, `last_1_d`, `last_3_d`, `last_7_d`, `last_14_d`, `last_28_d`, `last_30_d`, `last_60_d`, `last_90_d`, `custom` |
+| `run_frequency` | `{"type": "daily", "hour": 8}`, `{"type": "hour", "value": 24, "start_time": 8}`, `{"type": "weekly", "weekdays": ["monday"], "hour": 8}`, `{"type": "monthly", "days": [1], "hour": 8}`, `{"type": "once", "date_time": "2026-10-01T09:00:00Z"}` — `hour` and `start_time` are UTC |
+
+The `add-as-keyword-to` action promotes what the rule found into a keyword in one or more target ad
+groups. Its `params` differ by `operate_with`, and the API picks the variant by shape without a
+discriminator: a key that belongs to another variant makes it silently choose that variant and drop
+the rest, which is how a rule ends up as "Add as keyword to 0 ad groups". `negate` and
+`skip_enable_duplicate_keywords` exist only on a `search-term` rule, `pause_in_original_ad_group`
+only on a `targeting-keyword` one, and `targets` holds `internal_ids` — never `ids`.
+
+A full `search-term` rule — every term with 10+ taps over the last week becomes an exact keyword in
+the target ad group at the term's own CPT, and is negated in the ad group it came from:
+
+```json
+{
+  "name": "Search term harvester",
+  "status": 1,
+  "operate_with": "search-term",
+  "apply_to": [{"internal_id": "CAMPAIGN_UUID", "type": "campaign"}],
+  "conditions": [
+    {
+      "operator": "gte",
+      "args": 10,
+      "operand": {
+        "field": "taps",
+        "field_type": "base_field",
+        "date_range_type": "last_7_d",
+        "date_range_size": 0,
+        "date_range_offset": 0,
+        "by_days": null
+      }
+    }
+  ],
+  "actions": [
+    {
+      "type": "add-as-keyword-to",
+      "params": {
+        "targets": {"type": "ad-group", "internal_ids": ["AD_GROUP_UUID"]},
+        "cpt_bid": {"type": "search_term_current_cpt", "value": null},
+        "match_type": "EXACT",
+        "negate": {"enabled": true, "type": "ad-group"},
+        "skip_enable_duplicate_keywords": false
+      }
+    }
+  ],
+  "run_frequency": {"type": "daily", "hour": 8}
+}
+```
+
+The same action on a `targeting-keyword` rule — a broad keyword that has earned installs graduates
+into the exact ad group at its current bid and is paused where it was:
+
+```json
+{
+  "name": "Graduate broad keywords to exact",
+  "status": 1,
+  "operate_with": "targeting-keyword",
+  "apply_to": [{"internal_id": "SOURCE_AD_GROUP_UUID", "type": "ad-group"}],
+  "conditions": [
+    {
+      "operator": "gte",
+      "args": 3,
+      "operand": {
+        "field": "total_installs",
+        "field_type": "base_field",
+        "date_range_type": "last_14_d",
+        "date_range_size": 0,
+        "date_range_offset": 0,
+        "by_days": null
+      }
+    }
+  ],
+  "actions": [
+    {
+      "type": "add-as-keyword-to",
+      "params": {
+        "targets": {"type": "ad-group", "internal_ids": ["EXACT_AD_GROUP_UUID"]},
+        "cpt_bid": {"type": "keyword_current_bid", "value": null},
+        "match_type": "EXACT",
+        "pause_in_original_ad_group": true
+      }
+    }
+  ],
+  "run_frequency": {"type": "daily", "hour": 8}
+}
+```
+
+Rather than hand-writing that `params` block, pass the action flags — they fill in or override
+`actions[0].params` in the file, and the CLI refuses a rule the API would have quietly accepted and
+broken:
+
+```sh
+adapty asa automations create --file rule.json --target-ad-group AD_GROUP_UUID \
+  --match-type EXACT --cpt-bid-type search_term_current_cpt --negate ad-group
+adapty asa automations create --file rule.json --target-ad-group AD_GROUP_UUID \
+  --match-type BROAD --cpt-bid-type set_to --cpt-bid 1.50 --no-negate --skip-enable-duplicates
+adapty asa automations update AUTOMATION_ID --target-ad-group AD_GROUP_UUID \
+  --match-type EXACT --cpt-bid-type search_term_current_cpt
+```
+
+| Flag                       | Where it lands                                                        |
+| -------------------------- | --------------------------------------------------------------------- |
+| `--target-ad-group`        | `targets.internal_ids`, repeatable; a rule without one does nothing    |
+| `--match-type`             | `match_type`: `BROAD` or `EXACT`                                      |
+| `--cpt-bid-type`           | `cpt_bid.type`: `ad_group_default_bid`, `set_to`, `search_term_current_cpt`, `keyword_current_bid` |
+| `--cpt-bid`                | `cpt_bid.value`: the bid itself with `set_to` (required), a percent markup on the entity's own bid with `search_term_current_cpt` / `keyword_current_bid`, rejected with `ad_group_default_bid` |
+| `--negate` / `--no-negate` | `negate` (search-term rules): `ad-group` or `campaign`, or off        |
+| `--skip-enable-duplicates` | `skip_enable_duplicate_keywords` (search-term rules)                  |
+| `--pause-original`         | `pause_in_original_ad_group` (targeting-keyword rules)                |
+
+`--cpt-bid-type` and `--match-type` have no defaults, here or in the API: a bid and a match type are
+a spend decision and a reach decision, so when `params` are built from scratch the CLI asks for them
+instead of guessing. On `update`, an action flag turns the call into a read-modify-write — the rule
+is read, `actions[0].params` is rebuilt and the whole `actions` list is written back, since the API
+replaces it wholesale. That also repairs a rule whose stored `params` carry the wrong shape: only
+the keys that fit are kept, the strays are dropped, and anything missing has to come from a flag. A
+dashboard edit made between the read and the write is overwritten.
+
+
 Metrics take an entity level, a period and an optional metric selection. Rows come back one per entity,
 aggregated and sorted server-side, so a top-N or a breakdown is a single call — use `--order-by` with a small
 `--page-size` for rankings, `metrics overview` for account totals and time series, and one big page (up to

package/dist/commands/asa/automations/create.d.ts

@@ -9,8 +9,17 @@ export default class AsaAutomationsCreate extends Command {
         'run-now': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'idempotency-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'cpt-bid': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'cpt-bid-type': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'match-type': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        negate: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'no-negate': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'pause-original': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'skip-enable-duplicates': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'target-ad-group': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<AsaAutomationMutationDTO>;
+    private applyActionFlags;
     private readRule;
     private readStdin;
 }

package/dist/commands/asa/automations/create.js

@@ -1,17 +1,21 @@
 import { Command, Flags } from '@oclif/core';
 import { readFile } from 'node:fs/promises';
 import { asaWrite, createAsaClient, noteReplay } from '../../../lib/asa-client.js';
-import { idempotencyFlags } from '../../../lib/asa-flags.js';
+import { addKeywordActionFlags, idempotencyFlags } from '../../../lib/asa-flags.js';
+import { hasAddKeywordActionFlags, rebuildAddKeywordAction, requireSingleAction, } from '../../../lib/asa-keyword-action.js';
 import { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
 import { printResponse } from '../../../lib/output.js';
 export default class AsaAutomationsCreate extends Command {
-    static description = 'Create an automation rule from a JSON rule file';
+    static description = 'Create an automation rule from a JSON rule file. The add-as-keyword action flags fill in or override actions[0].params, so the bid, the match type and the target ad groups need no hand-written JSON.';
     static enableJsonFlag = true;
     static examples = [
         '<%= config.bin %> asa automations create --file rule.json',
         '<%= config.bin %> asa automations create --file rule.json --run-now',
+        '<%= config.bin %> asa automations create --file rule.json --target-ad-group AD_GROUP_ID --match-type EXACT --cpt-bid-type search_term_current_cpt',
+        '<%= config.bin %> asa automations create --file rule.json --target-ad-group AD_GROUP_ID --match-type EXACT --cpt-bid-type set_to --cpt-bid 1.50 --negate ad-group',
     ];
     static flags = {
+        ...addKeywordActionFlags,
         ...confirmFlags,
         ...idempotencyFlags,
         file: Flags.string({ description: 'JSON file with the rule body, or - to read stdin', required: true }),
@@ -22,6 +26,7 @@ export default class AsaAutomationsCreate extends Command {
         const body = await this.readRule(flags.file);
         if (flags['run-now'])
             body.run_immediately = true;
+        this.applyActionFlags(body, flags);
         const summary = flags['run-now'] ? 'Create automation rule and run it immediately' : 'Create automation rule';
         await confirmMutation(this, { body, method: 'POST', path: '/automations/', summary }, flags.yes);
         const client = await createAsaClient(this.config);
@@ -36,6 +41,17 @@ export default class AsaAutomationsCreate extends Command {
         printResponse(result, this.log.bind(this));
         return result;
     }
+    applyActionFlags(body, flags) {
+        try {
+            requireSingleAction(body.actions);
+            if (!hasAddKeywordActionFlags(flags))
+                return;
+            body.actions = rebuildAddKeywordAction(body.actions, body.operate_with, flags);
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : String(error), { exit: 2 });
+        }
+    }
     async readRule(path) {
         let raw;
         try {

package/dist/commands/asa/automations/update.d.ts

@@ -14,8 +14,17 @@ export default class AsaAutomationsUpdate extends Command {
         stop: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'idempotency-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'cpt-bid': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'cpt-bid-type': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'match-type': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        negate: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'no-negate': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'pause-original': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'skip-enable-duplicates': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'target-ad-group': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<AsaAutomationMutationDTO>;
     private readRule;
     private readStdin;
+    private rebuildAction;
 }

package/dist/commands/asa/automations/update.js

@@ -1,7 +1,8 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { readFile } from 'node:fs/promises';
 import { asaWrite, createAsaClient, noteReplay } from '../../../lib/asa-client.js';
-import { idempotencyFlags } from '../../../lib/asa-flags.js';
+import { addKeywordActionFlags, idempotencyFlags } from '../../../lib/asa-flags.js';
+import { hasAddKeywordActionFlags, rebuildAddKeywordAction, } from '../../../lib/asa-keyword-action.js';
 import { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
 import { isValidUuid } from '../../../lib/flags.js';
 import { printResponse } from '../../../lib/output.js';
@@ -9,13 +10,15 @@ export default class AsaAutomationsUpdate extends Command {
     static args = {
         automation_id: Args.string({ description: 'Automation rule ID (UUID)', required: true }),
     };
-    static description = 'Change an automation rule: stop it, rename it, or replace parts of the rule';
+    static description = 'Change an automation rule: stop it, rename it, or replace parts of the rule. An add-as-keyword action flag turns the call into a read-modify-write: the rule is read, actions[0].params is rebuilt from the flags and the whole actions list is written back — an edit someone makes in the dashboard in between is overwritten. This is also the way to repair a rule whose stored params carry the wrong shape.';
     static enableJsonFlag = true;
     static examples = [
         '<%= config.bin %> asa automations update UUID --stop',
         '<%= config.bin %> asa automations update UUID --file rule.json',
+        '<%= config.bin %> asa automations update UUID --target-ad-group AD_GROUP_ID --match-type EXACT --cpt-bid-type search_term_current_cpt',
     ];
     static flags = {
+        ...addKeywordActionFlags,
         ...confirmFlags,
         ...idempotencyFlags,
         file: Flags.string({ description: 'JSON file with the parts to change, or - to read stdin' }),
@@ -34,14 +37,17 @@ export default class AsaAutomationsUpdate extends Command {
             body.status = 1;
         if (flags.stop)
             body.status = 0;
-        if (Object.keys(body).length === 0) {
-            this.error('Nothing to change. Pass --stop, --start, --name or --file.', { exit: 2 });
+        const actionFlags = hasAddKeywordActionFlags(flags);
+        if (Object.keys(body).length === 0 && !actionFlags) {
+            this.error('Nothing to change. Pass --stop, --start, --name, --file or an action flag.', { exit: 2 });
         }
         if ('internal_id' in body) {
             this.error('Remove internal_id from the file: the rule ID comes from the command line.', { exit: 2 });
         }
-        await confirmMutation(this, { body, method: 'PUT', path: `/automations/${args.automation_id}/`, summary: 'Update automation rule' }, flags.yes);
         const client = await createAsaClient(this.config);
+        if (actionFlags)
+            await this.rebuildAction(client, args.automation_id, body, flags);
+        await confirmMutation(this, { body, method: 'PUT', path: `/automations/${args.automation_id}/`, summary: 'Update automation rule' }, flags.yes);
         const { replayed, result } = await asaWrite(client, 'put', `/automations/${args.automation_id}`, { body, idempotencyKey: flags['idempotency-key'] });
         noteReplay(replayed, this.log.bind(this));
         if (result.automation && !replayed)
@@ -70,4 +76,14 @@ export default class AsaAutomationsUpdate extends Command {
             chunks.push(chunk);
         return Buffer.concat(chunks).toString('utf8');
     }
+    // Read-modify-write: the API replaces `actions` wholesale, so the whole list has to be sent back.
+    async rebuildAction(client, automationId, body, flags) {
+        const rule = await client.get(`/automations/${automationId}`);
+        try {
+            body.actions = rebuildAddKeywordAction(body.actions ?? rule.actions, body.operate_with ?? rule.operate_with, flags);
+        }
+        catch (error) {
+            this.error(error instanceof Error ? error.message : String(error), { exit: 2 });
+        }
+    }
 }

package/dist/commands/asa/metrics/index.d.ts

@@ -9,10 +9,13 @@ export default class AsaMetrics extends Command {
         'date-to': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         entity: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'group-by': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        metric: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        metric: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
         order: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'order-by': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'order-by-day': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'ad-group': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        app: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        campaign: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'by-days': import("@oclif/core/interfaces").OptionFlag<number[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         page: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         'page-size': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/asa/metrics/index.js

@@ -1,6 +1,6 @@
 import { Command, Flags } from '@oclif/core';
 import { asaWrite, createAsaClient } from '../../../lib/asa-client.js';
-import { ASA_GROUP_BY_DIMENSIONS, ASA_METRIC_ENTITIES, asaPaginationFlags, byDaysFlag, MAX_BY_DAYS } from '../../../lib/asa-flags.js';
+import { ASA_GROUP_BY_DIMENSIONS, ASA_METRIC_ENTITIES, asaPaginationFlags, byDaysFlag, MAX_BY_DAYS, metricsScopeBody, metricsScopeFlags, } from '../../../lib/asa-flags.js';
 import { paginationParams } from '../../../lib/flags.js';
 import { printList } from '../../../lib/output.js';
 export default class AsaMetrics extends Command {
@@ -10,21 +10,29 @@ One row per entity, already aggregated server-side and sorted by --order-by, so
 call with --order-by and --page-size N — never sum pages yourself. Account-level totals are one call to
 asa metrics overview instead. The date window is capped by the finest --group-by period: 28 days when
 day is grouped, 90 with no period grouping, 180 by week, 365 by month and coarser — widen the window by
-coarsening the grouping, not by splitting into more calls. Each page is also capped at 20000 breakdown
+coarsening the grouping, not by splitting into more calls. Each page is also capped at 5000 breakdown
 rows (entities × countries × periods); over it the call fails with 422 cli_response_too_large — coarsen
 the grouping, narrow the window, or reduce page[size]. Budget: 5 metrics calls per minute, at most
-2 per 10 seconds, one at a time.`;
+2 per 10 seconds, one at a time.
+
+--metric is required and every metric named is computed over the whole entity set, so ask for the
+columns you actually read. subscribers and paid_subscribers (and arppu / arpas, which derive from them)
+count unique profiles per entity and cost roughly seventeen times the rest; whatever the --entity, they
+are refused unless --campaign or --ad-group scopes the call. Those scope flags are also the cheapest way
+to make any call fast, since cost follows the number of entities aggregated, not the page size.`;
     static enableJsonFlag = true;
     static examples = [
-        '<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31',
-        '<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --order-by spend --page-size 5',
-        '<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --group-by country --page-size 1000',
+        '<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --metric adapty_installs',
+        '<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --order-by spend --page-size 5',
+        '<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --group-by country --page-size 1000',
         '<%= config.bin %> asa metrics --entity keyword --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --metric roas',
         '<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric roas --by-days 7 --by-days 90',
+        '<%= config.bin %> asa metrics --entity keyword --date-from 2026-07-01 --date-to 2026-07-31 --metric arpas --campaign 0f0e...',
     ];
     static flags = {
         ...asaPaginationFlags,
         ...byDaysFlag,
+        ...metricsScopeFlags,
         'date-from': Flags.string({ description: 'Start of the period (YYYY-MM-DD)', required: true }),
         'date-to': Flags.string({ description: 'End of the period (YYYY-MM-DD)', required: true }),
         entity: Flags.string({ description: 'What to report on', options: ASA_METRIC_ENTITIES, required: true }),
@@ -34,8 +42,9 @@ the grouping, narrow the window, or reduce page[size]. Budget: 5 metrics calls p
             options: ASA_GROUP_BY_DIMENSIONS,
         }),
         metric: Flags.string({
-            description: 'Metric name (dashboard nomenclature, e.g. spend, taps, gross_roas), repeatable; omit for every metric; a wrong name fails listing all valid ones',
+            description: 'Metric name (dashboard nomenclature, e.g. spend, taps, gross_roas), repeatable and required; every metric asked for is computed over the whole entity set, so list only what you read; a wrong name fails listing all valid ones',
             multiple: true,
+            required: true,
         }),
         order: Flags.string({ default: 'desc', description: 'Sort direction', options: ['asc', 'desc'] }),
         'order-by': Flags.string({
@@ -56,8 +65,9 @@ the grouping, narrow the window, or reduce page[size]. Budget: 5 metrics calls p
                 date_from: flags['date-from'],
                 date_to: flags['date-to'],
                 entity: flags.entity,
+                metrics: flags.metric,
                 order: flags.order,
-                ...(flags.metric === undefined ? {} : { metrics: flags.metric }),
+                ...metricsScopeBody(flags),
                 ...(flags['by-days'] === undefined ? {} : { by_days: flags['by-days'] }),
                 ...(flags['group-by'] === undefined ? {} : { group_by: flags['group-by'] }),
                 ...(flags['order-by'] === undefined ? {} : { order_by: flags['order-by'] }),

package/dist/lib/asa-flags.d.ts

@@ -44,6 +44,20 @@ export declare const adScopeFlags: {
     campaign: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
     'campaign-group': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
 };
+export declare const metricsScopeFlags: {
+    'ad-group': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    app: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    campaign: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare function metricsScopeBody(flags: {
+    'ad-group'?: string[];
+    app?: string[];
+    campaign?: string[];
+}): {
+    campaign_id?: string[] | undefined;
+    app_id?: string[] | undefined;
+    ad_group_id?: string[] | undefined;
+};
 export declare const statusFilter: (options: string[]) => {
     status: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
 };
@@ -75,6 +89,16 @@ export declare function moneyFlag(description: string, opts?: {
 export declare const currencyFlag: {
     currency: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
 };
+export declare const addKeywordActionFlags: {
+    'cpt-bid': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'cpt-bid-type': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'match-type': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    negate: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'no-negate': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    'pause-original': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    'skip-enable-duplicates': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    'target-ad-group': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
 export declare const idempotencyFlags: {
     'idempotency-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
 };

package/dist/lib/asa-flags.js

@@ -1,4 +1,5 @@
 import { Flags } from '@oclif/core';
+import { CPT_BID_TYPES, KEYWORD_MATCH_TYPES, NEGATE_TYPES } from './asa-keyword-action.js';
 import { describeListedError } from './errors.js';
 import { isValidUuid } from './flags.js';
 const DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
@@ -63,6 +64,18 @@ export const adScopeFlags = {
     'campaign-group': idFilter('campaign group'),
     ...searchFilter,
 };
+export const metricsScopeFlags = {
+    'ad-group': idFilter('ad group'),
+    app: idFilter('app'),
+    campaign: idFilter('campaign'),
+};
+export function metricsScopeBody(flags) {
+    return {
+        ...(flags['ad-group'] === undefined ? {} : { ad_group_id: flags['ad-group'] }),
+        ...(flags.app === undefined ? {} : { app_id: flags.app }),
+        ...(flags.campaign === undefined ? {} : { campaign_id: flags.campaign }),
+    };
+}
 export const statusFilter = (options) => ({
     status: Flags.string({ description: 'Keep only rows in this state', options }),
 });
@@ -116,6 +129,47 @@ export function moneyFlag(description, opts = {}) {
 export const currencyFlag = {
     currency: Flags.string({ default: 'USD', description: 'Currency code for the amounts in this call' }),
 };
+// Params of the add-as-keyword-to action, shared by `automations create` and `automations update`.
+// The API picks the params variant by shape, so which of these apply depends on the rule's
+// operate_with: --negate/--no-negate/--skip-enable-duplicates are search-term only,
+// --pause-original is targeting-keyword only. See lib/asa-keyword-action.ts.
+export const addKeywordActionFlags = {
+    'cpt-bid': Flags.string({
+        description: 'cpt_bid.value: the bid itself with --cpt-bid-type set_to, or a percent markup on the entity bid with ' +
+            'search_term_current_cpt / keyword_current_bid; not accepted with ad_group_default_bid',
+        parse: parseMoney,
+    }),
+    'cpt-bid-type': Flags.string({
+        description: 'Where the bid of the created keyword comes from; the API has no default',
+        options: CPT_BID_TYPES,
+    }),
+    'match-type': Flags.string({
+        description: 'Match type of the created keyword; the API has no default',
+        options: KEYWORD_MATCH_TYPES,
+    }),
+    negate: Flags.string({
+        description: 'Also add the search term as a negative keyword at this level (search-term rules)',
+        exclusive: ['no-negate'],
+        options: NEGATE_TYPES,
+    }),
+    'no-negate': Flags.boolean({
+        description: 'Leave no negative keyword behind (search-term rules)',
+        exclusive: ['negate'],
+    }),
+    'pause-original': Flags.boolean({
+        allowNo: true,
+        description: 'Pause the source keyword in its own ad group (targeting-keyword rules)',
+    }),
+    'skip-enable-duplicates': Flags.boolean({
+        allowNo: true,
+        description: 'Skip a keyword that already exists in the target ad group instead of enabling it (search-term rules)',
+    }),
+    'target-ad-group': Flags.string({
+        description: 'Ad group the keyword is added to (UUID), repeatable; a rule without one does nothing',
+        multiple: true,
+        parse: parseId,
+    }),
+};
 export const idempotencyFlags = {
     'idempotency-key': Flags.string({
         description: 'Idempotency key for this write; re-running with the same key replays the stored result instead of applying twice',

package/dist/lib/asa-keyword-action.d.ts

@@ -0,0 +1,18 @@
+export declare const ADD_AS_KEYWORD_ACTION = "add-as-keyword-to";
+export declare const CPT_BID_TYPES: string[];
+export declare const KEYWORD_MATCH_TYPES: string[];
+export declare const NEGATE_TYPES: string[];
+export interface AddKeywordActionFlags {
+    'cpt-bid'?: string;
+    'cpt-bid-type'?: string;
+    'match-type'?: string;
+    negate?: string;
+    'no-negate'?: boolean;
+    'pause-original'?: boolean;
+    'skip-enable-duplicates'?: boolean;
+    'target-ad-group'?: string[];
+}
+export declare function hasAddKeywordActionFlags(flags: AddKeywordActionFlags): boolean;
+export declare function buildAddKeywordParams(operateWith: unknown, stored: unknown, flags: AddKeywordActionFlags): Record<string, unknown>;
+export declare function requireSingleAction(actions: unknown): Record<string, unknown>;
+export declare function rebuildAddKeywordAction(actions: unknown, operateWith: unknown, flags: AddKeywordActionFlags): Record<string, unknown>[];

package/dist/lib/asa-keyword-action.js

@@ -0,0 +1,160 @@
+import { isValidUuid } from './flags.js';
+export const ADD_AS_KEYWORD_ACTION = 'add-as-keyword-to';
+export const CPT_BID_TYPES = ['ad_group_default_bid', 'keyword_current_bid', 'search_term_current_cpt', 'set_to'];
+export const KEYWORD_MATCH_TYPES = ['BROAD', 'EXACT'];
+export const NEGATE_TYPES = ['ad-group', 'campaign'];
+const SEARCH_TERM = 'search-term';
+const TARGETING_KEYWORD = 'targeting-keyword';
+const BID_TYPE_IGNORING_VALUE = 'ad_group_default_bid';
+const BID_TYPES_READING_MARKUP = new Set(['keyword_current_bid', 'search_term_current_cpt']);
+// KeywordMatchType also carries AUTO. --match-type never offers it — an automation creates a
+// keyword, and AUTO is not something a keyword can be — but a rule that already stores AUTO keeps
+// it rather than being pushed onto another match type by an edit that never mentioned match types.
+const STORED_MATCH_TYPES = new Set(['AUTO', ...KEYWORD_MATCH_TYPES]);
+const SHARED_FLAGS = ['target-ad-group', 'match-type', 'cpt-bid-type', 'cpt-bid'];
+const SEARCH_TERM_FLAGS = ['negate', 'no-negate', 'skip-enable-duplicates'];
+const TARGETING_KEYWORD_FLAGS = ['pause-original'];
+const ALL_FLAGS = [...SHARED_FLAGS, ...SEARCH_TERM_FLAGS, ...TARGETING_KEYWORD_FLAGS];
+const MISSING_REASONS = {
+    'cpt-bid': 'the bid to set, required by --cpt-bid-type set_to',
+    'cpt-bid-type': 'where the bid of the new keyword comes from; the API has no default',
+    'match-type': 'BROAD or EXACT; the API has no default',
+    'target-ad-group': 'the ad groups the keyword is added to; a rule with none does nothing',
+};
+function dashed(name) {
+    return `--${name}`;
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : {};
+}
+function isFlagSet(flags, name) {
+    const value = flags[name];
+    if (value === undefined)
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    // --no-negate has no negated form of its own, so only a true means it was passed.
+    return name === 'no-negate' ? value === true : true;
+}
+export function hasAddKeywordActionFlags(flags) {
+    return ALL_FLAGS.some((name) => isFlagSet(flags, name));
+}
+// Params are rebuilt, not patched: a rule may store the add-as-negative-keyword shape
+// ({target_type, ids}) under an add-as-keyword-to action, and the API picks the params variant by
+// shape without a discriminator — so every stray key silently changes which action gets run.
+// Only what fits the expected shape is carried over; the rest has to come from the flags.
+function storedInternalIds(params) {
+    const ids = asRecord(params.targets).internal_ids;
+    return Array.isArray(ids) ? ids.filter((id) => typeof id === 'string' && isValidUuid(id)) : [];
+}
+function storedMatchType(params) {
+    const matchType = params.match_type;
+    return typeof matchType === 'string' && STORED_MATCH_TYPES.has(matchType) ? matchType : undefined;
+}
+function storedCptBidType(params) {
+    const { type } = asRecord(params.cpt_bid);
+    return typeof type === 'string' && CPT_BID_TYPES.includes(type) ? type : undefined;
+}
+function storedCptBidValue(params) {
+    const { value } = asRecord(params.cpt_bid);
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function storedBoolean(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+function storedNegate(params) {
+    const { enabled, type } = asRecord(params.negate);
+    if (typeof enabled !== 'boolean')
+        return undefined;
+    if (type === null || type === undefined)
+        return { enabled, type: null };
+    return typeof type === 'string' && NEGATE_TYPES.includes(type) ? { enabled, type } : undefined;
+}
+function resolveNegate(flags, params) {
+    if (flags.negate !== undefined)
+        return { enabled: true, type: flags.negate };
+    if (flags['no-negate'] === true)
+        return { enabled: false, type: null };
+    return storedNegate(params) ?? { enabled: false, type: null };
+}
+function resolveCptBidValue(cptBidType, bid, params) {
+    if (cptBidType === 'set_to')
+        return bid === undefined ? storedCptBidValue(params) : Number(bid);
+    if (cptBidType !== undefined && BID_TYPES_READING_MARKUP.has(cptBidType)) {
+        return bid === undefined ? (storedCptBidValue(params) ?? null) : Number(bid);
+    }
+    return null;
+}
+function isSearchTermRule(operateWith) {
+    if (operateWith === SEARCH_TERM)
+        return true;
+    if (operateWith === TARGETING_KEYWORD)
+        return false;
+    const shown = typeof operateWith === 'string' && operateWith.length > 0 ? `"${operateWith}"` : 'missing';
+    throw new Error(`${ADD_AS_KEYWORD_ACTION} runs on a "${SEARCH_TERM}" or "${TARGETING_KEYWORD}" rule only; this rule's operate_with is ${shown}.`);
+}
+function rejectForeignFlags(searchTerm, flags) {
+    const foreign = (searchTerm ? TARGETING_KEYWORD_FLAGS : SEARCH_TERM_FLAGS).filter((name) => isFlagSet(flags, name));
+    if (foreign.length === 0)
+        return;
+    const applicable = [...SHARED_FLAGS, ...(searchTerm ? SEARCH_TERM_FLAGS : TARGETING_KEYWORD_FLAGS)];
+    throw new Error(`${foreign.map((name) => dashed(name)).join(', ')} ${foreign.length === 1 ? 'has' : 'have'} no place in the params of an ` +
+        `operate_with "${searchTerm ? SEARCH_TERM : TARGETING_KEYWORD}" rule, and the API drops params it cannot ` +
+        `place. Applicable action flags: ${applicable.map((name) => dashed(name)).join(', ')}.`);
+}
+function missingFlagsError(missing) {
+    const lines = missing.map((name) => `  ${dashed(name)} — ${MISSING_REASONS[name]}`);
+    return new Error(`The ${ADD_AS_KEYWORD_ACTION} params are incomplete. Pass:\n${lines.join('\n')}`);
+}
+export function buildAddKeywordParams(operateWith, stored, flags) {
+    const searchTerm = isSearchTermRule(operateWith);
+    rejectForeignFlags(searchTerm, flags);
+    const params = asRecord(stored);
+    const missing = [];
+    const internalIds = flags['target-ad-group'] ?? storedInternalIds(params);
+    if (internalIds.length === 0)
+        missing.push('target-ad-group');
+    const matchType = flags['match-type'] ?? storedMatchType(params);
+    if (matchType === undefined)
+        missing.push('match-type');
+    const cptBidType = flags['cpt-bid-type'] ?? storedCptBidType(params);
+    if (cptBidType === undefined)
+        missing.push('cpt-bid-type');
+    const bid = flags['cpt-bid'];
+    if (bid !== undefined && cptBidType === BID_TYPE_IGNORING_VALUE) {
+        throw new Error(`--cpt-bid has no meaning with --cpt-bid-type ${BID_TYPE_IGNORING_VALUE}; that type copies the target ad group's default bid.`);
+    }
+    const cptBidValue = resolveCptBidValue(cptBidType, bid, params);
+    if (cptBidValue === undefined)
+        missing.push('cpt-bid');
+    if (missing.length > 0)
+        throw missingFlagsError(missing);
+    const built = {
+        cpt_bid: { type: cptBidType, value: cptBidValue ?? null },
+        match_type: matchType,
+        targets: { internal_ids: internalIds, type: 'ad-group' },
+    };
+    if (searchTerm) {
+        built.negate = resolveNegate(flags, params);
+        built.skip_enable_duplicate_keywords =
+            flags['skip-enable-duplicates'] ?? storedBoolean(params.skip_enable_duplicate_keywords) ?? false;
+    }
+    else {
+        built.pause_in_original_ad_group =
+            flags['pause-original'] ?? storedBoolean(params.pause_in_original_ad_group) ?? false;
+    }
+    return built;
+}
+export function requireSingleAction(actions) {
+    if (!Array.isArray(actions) || actions.length !== 1) {
+        throw new Error('A rule needs exactly one action: the API stores one action and one condition per rule.');
+    }
+    return asRecord(actions[0]);
+}
+export function rebuildAddKeywordAction(actions, operateWith, flags) {
+    const action = requireSingleAction(actions);
+    if (action.type !== ADD_AS_KEYWORD_ACTION) {
+        throw new Error(`The action flags only apply to an ${ADD_AS_KEYWORD_ACTION} action; this rule's action is "${String(action.type)}".`);
+    }
+    return [{ ...action, params: buildAddKeywordParams(operateWith, action.params, flags) }];
+}

package/dist/lib/errors.js

@@ -2,7 +2,8 @@ export function describeListedError(error) {
     const code = error.error_code ?? error.apple_error_code ?? error.validation_error_code ?? undefined;
     const reason = error.message ?? error.apple_error_message ?? error.validation_error_message ?? code ?? 'rejected';
     const position = error.input_ref === null || error.input_ref === undefined ? '' : ` (item ${error.input_ref + 1})`;
-    return { code, text: `${reason}${position}` };
+    const field = error.field_name ? `${error.field_name}: ` : '';
+    return { code, text: `${field}${reason}${position}` };
 }
 export class ApiError extends Error {
     statusCode;

package/oclif.manifest.json

@@ -2198,56 +2198,6 @@
         "update.js"
       ]
     },
-    "asa:apps:list": {
-      "aliases": [],
-      "args": {},
-      "description": "List the apps promoted by this company in Apple Search Ads",
-      "examples": [
-        "<%= config.bin %> asa apps list",
-        "<%= config.bin %> asa apps list --page 2 --page-size 50"
-      ],
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "page": {
-          "description": "Page number",
-          "name": "page",
-          "default": 1,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "page-size": {
-          "description": "Items per page (max 1000); prefer one big page over a pagination loop",
-          "name": "page-size",
-          "default": 100,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "asa:apps:list",
-      "pluginAlias": "adapty",
-      "pluginName": "adapty",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": true,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "asa",
-        "apps",
-        "list.js"
-      ]
-    },
     "asa:ads:create": {
       "aliases": [],
       "args": {},
@@ -2529,13 +2479,65 @@
         "update.js"
       ]
     },
+    "asa:apps:list": {
+      "aliases": [],
+      "args": {},
+      "description": "List the apps promoted by this company in Apple Search Ads",
+      "examples": [
+        "<%= config.bin %> asa apps list",
+        "<%= config.bin %> asa apps list --page 2 --page-size 50"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "page": {
+          "description": "Page number",
+          "name": "page",
+          "default": 1,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "page-size": {
+          "description": "Items per page (max 1000); prefer one big page over a pagination loop",
+          "name": "page-size",
+          "default": 100,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "asa:apps:list",
+      "pluginAlias": "adapty",
+      "pluginName": "adapty",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "asa",
+        "apps",
+        "list.js"
+      ]
+    },
     "asa:automations:create": {
       "aliases": [],
       "args": {},
-      "description": "Create an automation rule from a JSON rule file",
+      "description": "Create an automation rule from a JSON rule file. The add-as-keyword action flags fill in or override actions[0].params, so the bid, the match type and the target ad groups need no hand-written JSON.",
       "examples": [
         "<%= config.bin %> asa automations create --file rule.json",
-        "<%= config.bin %> asa automations create --file rule.json --run-now"
+        "<%= config.bin %> asa automations create --file rule.json --run-now",
+        "<%= config.bin %> asa automations create --file rule.json --target-ad-group AD_GROUP_ID --match-type EXACT --cpt-bid-type search_term_current_cpt",
+        "<%= config.bin %> asa automations create --file rule.json --target-ad-group AD_GROUP_ID --match-type EXACT --cpt-bid-type set_to --cpt-bid 1.50 --negate ad-group"
       ],
       "flags": {
         "json": {
@@ -2545,6 +2547,79 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "cpt-bid": {
+          "description": "cpt_bid.value: the bid itself with --cpt-bid-type set_to, or a percent markup on the entity bid with search_term_current_cpt / keyword_current_bid; not accepted with ad_group_default_bid",
+          "name": "cpt-bid",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "cpt-bid-type": {
+          "description": "Where the bid of the created keyword comes from; the API has no default",
+          "name": "cpt-bid-type",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "ad_group_default_bid",
+            "keyword_current_bid",
+            "search_term_current_cpt",
+            "set_to"
+          ],
+          "type": "option"
+        },
+        "match-type": {
+          "description": "Match type of the created keyword; the API has no default",
+          "name": "match-type",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "BROAD",
+            "EXACT"
+          ],
+          "type": "option"
+        },
+        "negate": {
+          "description": "Also add the search term as a negative keyword at this level (search-term rules)",
+          "exclusive": [
+            "no-negate"
+          ],
+          "name": "negate",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "ad-group",
+            "campaign"
+          ],
+          "type": "option"
+        },
+        "no-negate": {
+          "description": "Leave no negative keyword behind (search-term rules)",
+          "exclusive": [
+            "negate"
+          ],
+          "name": "no-negate",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "pause-original": {
+          "description": "Pause the source keyword in its own ad group (targeting-keyword rules)",
+          "name": "pause-original",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "skip-enable-duplicates": {
+          "description": "Skip a keyword that already exists in the target ad group instead of enabling it (search-term rules)",
+          "name": "skip-enable-duplicates",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "target-ad-group": {
+          "description": "Ad group the keyword is added to (UUID), repeatable; a rule without one does nothing",
+          "name": "target-ad-group",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
         "yes": {
           "char": "y",
           "description": "Apply without asking; required when the output is piped or --json is used",
@@ -2803,10 +2878,11 @@
           "required": true
         }
       },
-      "description": "Change an automation rule: stop it, rename it, or replace parts of the rule",
+      "description": "Change an automation rule: stop it, rename it, or replace parts of the rule. An add-as-keyword action flag turns the call into a read-modify-write: the rule is read, actions[0].params is rebuilt from the flags and the whole actions list is written back — an edit someone makes in the dashboard in between is overwritten. This is also the way to repair a rule whose stored params carry the wrong shape.",
       "examples": [
         "<%= config.bin %> asa automations update UUID --stop",
-        "<%= config.bin %> asa automations update UUID --file rule.json"
+        "<%= config.bin %> asa automations update UUID --file rule.json",
+        "<%= config.bin %> asa automations update UUID --target-ad-group AD_GROUP_ID --match-type EXACT --cpt-bid-type search_term_current_cpt"
       ],
       "flags": {
         "json": {
@@ -2816,6 +2892,79 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "cpt-bid": {
+          "description": "cpt_bid.value: the bid itself with --cpt-bid-type set_to, or a percent markup on the entity bid with search_term_current_cpt / keyword_current_bid; not accepted with ad_group_default_bid",
+          "name": "cpt-bid",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "cpt-bid-type": {
+          "description": "Where the bid of the created keyword comes from; the API has no default",
+          "name": "cpt-bid-type",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "ad_group_default_bid",
+            "keyword_current_bid",
+            "search_term_current_cpt",
+            "set_to"
+          ],
+          "type": "option"
+        },
+        "match-type": {
+          "description": "Match type of the created keyword; the API has no default",
+          "name": "match-type",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "BROAD",
+            "EXACT"
+          ],
+          "type": "option"
+        },
+        "negate": {
+          "description": "Also add the search term as a negative keyword at this level (search-term rules)",
+          "exclusive": [
+            "no-negate"
+          ],
+          "name": "negate",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "ad-group",
+            "campaign"
+          ],
+          "type": "option"
+        },
+        "no-negate": {
+          "description": "Leave no negative keyword behind (search-term rules)",
+          "exclusive": [
+            "negate"
+          ],
+          "name": "no-negate",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "pause-original": {
+          "description": "Pause the source keyword in its own ad group (targeting-keyword rules)",
+          "name": "pause-original",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "skip-enable-duplicates": {
+          "description": "Skip a keyword that already exists in the target ad group instead of enabling it (search-term rules)",
+          "name": "skip-enable-duplicates",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "target-ad-group": {
+          "description": "Ad group the keyword is added to (UUID), repeatable; a rule without one does nothing",
+          "name": "target-ad-group",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
         "yes": {
           "char": "y",
           "description": "Apply without asking; required when the output is piped or --json is used",
@@ -2880,47 +3029,6 @@
         "update.js"
       ]
     },
-    "asa:competitors:summary": {
-      "aliases": [],
-      "args": {},
-      "description": "Competitor summary for up to five App Store apps; the server covers the last full month and every country",
-      "examples": [
-        "<%= config.bin %> asa competitors summary --app-ids 1668337467,6503873027"
-      ],
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "app-ids": {
-          "description": "Apple App Store IDs (adam_id), comma-separated, 1-5 values",
-          "name": "app-ids",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "asa:competitors:summary",
-      "pluginAlias": "adapty",
-      "pluginName": "adapty",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": true,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "asa",
-        "competitors",
-        "summary.js"
-      ]
-    },
     "asa:campaigns:bulk-create": {
       "aliases": [],
       "args": {},
@@ -3639,6 +3747,47 @@
         "update.js"
       ]
     },
+    "asa:competitors:summary": {
+      "aliases": [],
+      "args": {},
+      "description": "Competitor summary for up to five App Store apps; the server covers the last full month and every country",
+      "examples": [
+        "<%= config.bin %> asa competitors summary --app-ids 1668337467,6503873027"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "app-ids": {
+          "description": "Apple App Store IDs (adam_id), comma-separated, 1-5 values",
+          "name": "app-ids",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "asa:competitors:summary",
+      "pluginAlias": "adapty",
+      "pluginName": "adapty",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "asa",
+        "competitors",
+        "summary.js"
+      ]
+    },
     "asa:creatives:list": {
       "aliases": [],
       "args": {},
@@ -4009,13 +4158,14 @@
     "asa:metrics": {
       "aliases": [],
       "args": {},
-      "description": "Query metrics for any level of the account over a date range\n\nOne row per entity, already aggregated server-side and sorted by --order-by, so a top-N question is one\ncall with --order-by and --page-size N — never sum pages yourself. Account-level totals are one call to\nasa metrics overview instead. The date window is capped by the finest --group-by period: 28 days when\nday is grouped, 90 with no period grouping, 180 by week, 365 by month and coarser — widen the window by\ncoarsening the grouping, not by splitting into more calls. Each page is also capped at 20000 breakdown\nrows (entities × countries × periods); over it the call fails with 422 cli_response_too_large — coarsen\nthe grouping, narrow the window, or reduce page[size]. Budget: 5 metrics calls per minute, at most\n2 per 10 seconds, one at a time.",
+      "description": "Query metrics for any level of the account over a date range\n\nOne row per entity, already aggregated server-side and sorted by --order-by, so a top-N question is one\ncall with --order-by and --page-size N — never sum pages yourself. Account-level totals are one call to\nasa metrics overview instead. The date window is capped by the finest --group-by period: 28 days when\nday is grouped, 90 with no period grouping, 180 by week, 365 by month and coarser — widen the window by\ncoarsening the grouping, not by splitting into more calls. Each page is also capped at 5000 breakdown\nrows (entities × countries × periods); over it the call fails with 422 cli_response_too_large — coarsen\nthe grouping, narrow the window, or reduce page[size]. Budget: 5 metrics calls per minute, at most\n2 per 10 seconds, one at a time.\n\n--metric is required and every metric named is computed over the whole entity set, so ask for the\ncolumns you actually read. subscribers and paid_subscribers (and arppu / arpas, which derive from them)\ncount unique profiles per entity and cost roughly seventeen times the rest; whatever the --entity, they\nare refused unless --campaign or --ad-group scopes the call. Those scope flags are also the cheapest way\nto make any call fast, since cost follows the number of entities aggregated, not the page size.",
       "examples": [
-        "<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31",
-        "<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --order-by spend --page-size 5",
-        "<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --group-by country --page-size 1000",
+        "<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --metric adapty_installs",
+        "<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --order-by spend --page-size 5",
+        "<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --group-by country --page-size 1000",
         "<%= config.bin %> asa metrics --entity keyword --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --metric roas",
-        "<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric roas --by-days 7 --by-days 90"
+        "<%= config.bin %> asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric roas --by-days 7 --by-days 90",
+        "<%= config.bin %> asa metrics --entity keyword --date-from 2026-07-01 --date-to 2026-07-31 --metric arpas --campaign 0f0e..."
       ],
       "flags": {
         "json": {
@@ -4048,6 +4198,27 @@
           "multiple": true,
           "type": "option"
         },
+        "ad-group": {
+          "description": "Keep only rows in this ad group; repeatable",
+          "name": "ad-group",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "app": {
+          "description": "Keep only rows in this app; repeatable",
+          "name": "app",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "campaign": {
+          "description": "Keep only rows in this campaign; repeatable",
+          "name": "campaign",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
         "date-from": {
           "description": "Start of the period (YYYY-MM-DD)",
           "name": "date-from",
@@ -4094,8 +4265,9 @@
           "type": "option"
         },
         "metric": {
-          "description": "Metric name (dashboard nomenclature, e.g. spend, taps, gross_roas), repeatable; omit for every metric; a wrong name fails listing all valid ones",
+          "description": "Metric name (dashboard nomenclature, e.g. spend, taps, gross_roas), repeatable and required; every metric asked for is computed over the whole entity set, so list only what you read; a wrong name fails listing all valid ones",
           "name": "metric",
+          "required": true,
           "hasDynamicHelp": false,
           "multiple": true,
           "type": "option"
@@ -5009,5 +5181,5 @@
       ]
     }
   },
-  "version": "0.8.4-beta.1"
+  "version": "0.8.4"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "adapty",
   "description": "Adapty command line interface",
-  "version": "0.8.4-beta.1",
+  "version": "0.8.4",
   "author": "Adapty team <support@adapty.io>",
   "bin": {
     "adapty": "./bin/run.js"