adapty 0.3.0 → 0.4.0

package/README.md

@@ -86,6 +86,131 @@ adapty access-levels create --app UUID [flags]
 adapty access-levels update --app UUID ACCESS_LEVEL_ID [flags]
 ```
 
+### Apple Search Ads
+
+Apple Search Ads commands live under `adapty asa` and talk to the ASA service rather than the Developer
+API. They take **no `--app`**: the scope is the company behind your token. A connected Apple Ads account and
+an active Ads Manager subscription are required — `adapty asa whoami` tells you where you stand.
+
+```sh
+adapty asa whoami                      # company, how access was granted, Apple connection state
+adapty asa connect [--no-wait]         # link an Apple Search Ads account
+adapty asa apps list                   # apps promoted in Apple Search Ads
+adapty asa orgs list                   # Apple Search Ads organizations
+```
+
+Every list takes scope filters, and they narrow the query rather than the printed page — `asa keywords list`
+unfiltered pages through the whole account, while one ad group is a handful of rows, so scope the read:
+
+```sh
+adapty asa campaigns list --app APP_UUID --status PAUSED
+adapty asa ad-groups list --campaign CAMPAIGN_UUID
+adapty asa keywords list --ad-group AD_GROUP_UUID --status ACTIVE
+adapty asa keywords list --ad-group AD_GROUP_UUID --ad-group OTHER_UUID   # repeatable
+adapty asa creatives list --app APP_UUID
+```
+
+`--campaign-group`, `--app`, `--campaign`, `--ad-group` are repeatable and take the UUIDs printed by the
+matching list command; `--search` matches names case-insensitively. Each list accepts only the filters that
+make sense for it: `--ad-group` starts at keywords, negative keywords, search terms and ads, `--status` is
+`ENABLED`/`PAUSED` everywhere except keywords, which are `ACTIVE`/`PAUSED`, and `asa ads list` has no `--app`
+because ads hang off ad groups. An id belonging to another company simply matches nothing.
+
+Campaign structure. These lists return metadata only — numbers come from `asa metrics`, and only
+`asa search-terms list` takes `--date-from` / `--date-to` (default: today):
+
+```sh
+adapty asa campaigns list
+adapty asa campaigns get CAMPAIGN_ID
+adapty asa campaigns create --org UUID --name "Winter push" --adam-id 123456 --country US --daily-budget 50
+adapty asa campaigns update CAMPAIGN_ID [--status PAUSED] [--daily-budget 80] [--country US]
+
+adapty asa ad-groups list
+adapty asa ad-groups get AD_GROUP_ID
+adapty asa ad-groups create --campaign UUID --name "Brand terms" --default-bid 1.20
+adapty asa ad-groups update AD_GROUP_ID [--default-bid 1.50] [--status PAUSED]
+
+adapty asa ads list
+adapty asa ads get AD_ID
+adapty asa ads create --ad-group UUID --creative-id 4321 --name "Summer ad"
+adapty asa ads update AD_ID [--name "..."] [--status PAUSED]
+```
+
+Keywords are always applied as a batch, at most 100 per call, and a partial rejection is reported per item:
+
+```sh
+adapty asa keywords list
+adapty asa keywords add --ad-group UUID --text "running shoes" --text "trail shoes" [--bid 1.20] [--match-type EXACT]
+adapty asa keywords add --ad-group UUID --from-file keywords.txt
+adapty asa keywords update KEYWORD_ID [KEYWORD_ID...] [--bid 2.00] [--status PAUSED]
+
+adapty asa negative-keywords list
+adapty asa negative-keywords add --ad-group UUID --text free
+adapty asa negative-keywords add --campaign UUID [--all-ad-groups] --text free
+
+adapty asa search-terms list [--date-from ... --date-to ...]
+```
+
+Product pages and rule-based automations:
+
+```sh
+adapty asa product-pages list
+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 run AUTOMATION_ID [--dry-run]
+adapty asa automations runs AUTOMATION_ID
+```
+
+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
+1000 rows) when you genuinely need every row; never sum pages client-side:
+
+```sh
+adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31
+adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --order-by spend --page-size 5
+adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --group-by country --page-size 1000
+adapty asa metrics --entity keyword --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --metric roas
+adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric roas --by-days 7 --by-days 90
+adapty asa metrics overview --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 [--period-unit week]
+```
+
+There is no `ltv` metric: lifetime value is a cohort metric read at a renewal window, so `--by-days` is how you
+ask for day-7 or day-90 values — on either route, up to 16 windows per call. `--order-by-day` ranks the rows by
+one of those windows, which is how you get the top campaigns by day-90 ROAS in a single call.
+
+Competitor summary takes 1–5 Apple App Store IDs and covers the last full month across every country — there
+are no period or country flags on purpose. The first call on a cold cache can take tens of seconds:
+
+```sh
+adapty asa competitors summary --app-ids 111111111,2222222
+```
+
+Writes go straight to Apple and take seconds, so every writing command first prints the exact request body and
+asks for a yes. `--yes` skips the question for scripts; in a pipe or under `--json` the command refuses instead
+of waiting for input that will never come. There is no undo — the CLI has no delete.
+
+Every write also carries an idempotency key. The CLI generates one per invocation and retries once on a
+network error, so a request that died on the wire is never applied twice. Pass `--idempotency-key` to pin the
+key yourself: re-running a script with the same key within 24 hours replays the stored result — the CLI prints
+"Already applied earlier — showing the stored result." — instead of creating a second entity. The same key
+with a different body is rejected (`422 cli_idempotency_key_reuse`), and a concurrent duplicate answers
+`409 cli_idempotency_in_progress`.
+
+Analytics is rate limited per company: the metrics routes get 5 calls a minute (at most 2 in any 10 seconds)
+and share a pool of two concurrent queries with the search-terms list — a busy pool answers
+`429 cli_analytics_busy`, an exhausted window `429 cli_rate_limit_exceeded`, both with the exact wait in
+`Retry-After`. The CLI absorbs a single 429 on its own — it waits the announced `Retry-After` (up to 60
+seconds; cool-downs are never waited out) and retries once — so a 429 that reaches you means the retry failed
+too. A burst of 429s puts the token into an escalating cool-down (`cli_cooldown_active`, 5 minutes →
+30 minutes → 3 hours); retries during the pause don't extend it, but the cure is fixing the failing request,
+not waiting out the pause in a loop. An automation run is queued rather than awaited: `run` prints a run ID
+and the outcome shows up in `adapty asa automations runs`.
+
 ### Global Flags
 
 | Flag          | Description                            |
@@ -93,14 +218,18 @@ adapty access-levels update --app UUID ACCESS_LEVEL_ID [flags]
 | `--json`      | Output as JSON                         |
 | `--help`      | Show help                              |
 | `--page`      | Page number (default: 1)               |
-| `--page-size` | Items per page (default: 20, max: 100) |
+| `--page-size` | Items per page (default: 20, max: 100; `asa` commands: default 100, max 1000) |
 
 ## Environment Variables
 
-| Variable         | Description                                                                     |
-| ---------------- | ------------------------------------------------------------------------------- |
-| `ADAPTY_TOKEN`   | Override stored auth token                                                      |
-| `ADAPTY_API_URL` | Override API base URL (default: `https://api-admin.adapty.io/api/v1/developer`) |
+| Variable             | Description                                                                             |
+| -------------------- | --------------------------------------------------------------------------------------- |
+| `ADAPTY_TOKEN`       | Override stored auth token                                                              |
+| `ADAPTY_API_URL`     | Override Developer API base URL (default: `https://api-admin.adapty.io/api/v1/developer`) |
+| `ADAPTY_ASA_API_URL` | Override Apple Search Ads base URL (default: `https://api-asa-admin.adapty.io/api/v1/cli`) |
+
+The two API URLs are independent: pointing `ADAPTY_API_URL` at a staging host leaves `adapty asa` on the ASA
+default, and the other way round.
 
 ## Claude Code Skill
 

package/dist/commands/asa/ad-groups/create.d.ts

@@ -0,0 +1,22 @@
+import { Command } from '@oclif/core';
+import type { AsaAdGroupMutationDTO } from '../../../lib/asa-schemas.js';
+export default class AsaAdGroupsCreate extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'automated-keywords': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        campaign: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'cpa-goal': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'default-bid': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        name: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        status: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'idempotency-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'pricing-model': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'end-time': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'start-time': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        currency: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<AsaAdGroupMutationDTO>;
+}

package/dist/commands/asa/ad-groups/create.js

@@ -0,0 +1,54 @@
+import { Command, Flags } from '@oclif/core';
+import { asaWrite, createAsaClient, noteReplay } from '../../../lib/asa-client.js';
+import { confirmFlags, confirmMutation } from '../../../lib/asa-confirm.js';
+import { currencyFlag, idempotencyFlags, money, moneyFlag, pricingModelFlag, scheduleFlags, startOfDayUtc, todayUtc, } from '../../../lib/asa-flags.js';
+import { isValidUuid } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaAdGroupsCreate extends Command {
+    static description = 'Create an ad group inside a campaign';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa ad-groups create --campaign UUID --name "Brand terms" --default-bid 1.20',
+        '<%= config.bin %> asa ad-groups create --campaign UUID --name "Brand terms" --default-bid 1.20 --start-time 2026-09-01 --pricing-model CPM',
+    ];
+    static flags = {
+        ...currencyFlag,
+        ...scheduleFlags,
+        ...pricingModelFlag,
+        ...confirmFlags,
+        ...idempotencyFlags,
+        'automated-keywords': Flags.boolean({ allowNo: true, description: 'Let Apple add keywords automatically' }),
+        campaign: Flags.string({ description: 'Campaign ID (UUID)', required: true }),
+        'cpa-goal': moneyFlag('CPA goal'),
+        'default-bid': moneyFlag('Default bid', { required: true }),
+        name: Flags.string({ description: 'Ad group name', required: true }),
+        status: Flags.string({ description: 'Initial status', options: ['ENABLED', 'PAUSED'] }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaAdGroupsCreate);
+        if (!isValidUuid(flags.campaign))
+            this.error('Invalid campaign ID format.', { exit: 2 });
+        const body = {
+            automated_keywords_opt_in: flags['automated-keywords'],
+            campaign_id: flags.campaign,
+            cpa_goal: money(flags['cpa-goal'], flags.currency),
+            default_bid_amount: money(flags['default-bid'], flags.currency),
+            end_time: startOfDayUtc(flags['end-time']),
+            name: flags.name,
+            pricing_model: flags['pricing-model'],
+            start_time: startOfDayUtc(flags['start-time'] ?? todayUtc()),
+            status: flags.status,
+        };
+        await confirmMutation(this, { body, method: 'POST', path: '/ad-groups/', summary: `Create ad group ${flags.name}` }, flags.yes);
+        const client = await createAsaClient(this.config);
+        const { replayed, result } = await asaWrite(client, 'post', '/ad-groups', {
+            body,
+            idempotencyKey: flags['idempotency-key'],
+        });
+        noteReplay(replayed, this.log.bind(this));
+        if (result.ad_group && !replayed)
+            this.log('Ad group created!');
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/asa/ad-groups/get.d.ts

@@ -0,0 +1,11 @@
+import { Command } from '@oclif/core';
+import type { AsaAdGroupDTO } from '../../../lib/asa-schemas.js';
+export default class AsaAdGroupsGet extends Command {
+    static args: {
+        ad_group_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    run(): Promise<AsaAdGroupDTO>;
+}

package/dist/commands/asa/ad-groups/get.js

@@ -0,0 +1,21 @@
+import { Args, Command } from '@oclif/core';
+import { createAsaClient } from '../../../lib/asa-client.js';
+import { isValidUuid } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaAdGroupsGet extends Command {
+    static args = {
+        ad_group_id: Args.string({ description: 'Ad group ID (UUID)', required: true }),
+    };
+    static description = 'Show one ad group; read numbers with asa metrics';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa ad-groups get 550e8400-e29b-41d4-a716-446655440000'];
+    async run() {
+        const { args } = await this.parse(AsaAdGroupsGet);
+        if (!isValidUuid(args.ad_group_id))
+            this.error('Invalid ad group ID format.', { exit: 2 });
+        const client = await createAsaClient(this.config);
+        const result = await client.get(`/ad-groups/${args.ad_group_id}`);
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/asa/ad-groups/list.d.ts

@@ -0,0 +1,18 @@
+import { Command } from '@oclif/core';
+import type { AsaAdGroupDTO } from '../../../lib/asa-schemas.js';
+import { type PaginatedResponse } from '../../../lib/flags.js';
+export default class AsaAdGroupsList extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        status: 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>;
+        search: 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-group': import("@oclif/core/interfaces").OptionFlag<string[] | 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>;
+    };
+    run(): Promise<PaginatedResponse<AsaAdGroupDTO>>;
+}

package/dist/commands/asa/ad-groups/list.js

@@ -0,0 +1,24 @@
+import { Command } from '@oclif/core';
+import { createAsaClient } from '../../../lib/asa-client.js';
+import { asaPaginationFlags, campaignScopeFlags, scopeParams, statusFilter } from '../../../lib/asa-flags.js';
+import { paginationParams } from '../../../lib/flags.js';
+import { printList } from '../../../lib/output.js';
+export default class AsaAdGroupsList extends Command {
+    static description = 'List ad groups; read numbers with asa metrics';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa ad-groups list',
+        '<%= config.bin %> asa ad-groups list --campaign CAMPAIGN_UUID',
+    ];
+    static flags = { ...asaPaginationFlags, ...campaignScopeFlags, ...statusFilter(['ENABLED', 'PAUSED']) };
+    async run() {
+        const { flags } = await this.parse(AsaAdGroupsList);
+        const client = await createAsaClient(this.config);
+        const result = await client.get('/ad-groups', {
+            ...paginationParams(flags),
+            ...scopeParams(flags),
+        });
+        printList(result.data, this.log.bind(this), result.meta.pagination);
+        return result;
+    }
+}

package/dist/commands/asa/ad-groups/update.d.ts

@@ -0,0 +1,23 @@
+import { Command } from '@oclif/core';
+import type { AsaAdGroupMutationDTO } from '../../../lib/asa-schemas.js';
+export default class AsaAdGroupsUpdate extends Command {
+    static args: {
+        ad_group_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'automated-keywords': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'cpa-goal': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'default-bid': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        status: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'idempotency-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'end-time': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'start-time': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        currency: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<AsaAdGroupMutationDTO>;
+}

package/dist/commands/asa/ad-groups/update.js

@@ -0,0 +1,62 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { asaWrite, createAsaClient, noteReplay } from '../../../lib/asa-client.js';
+import { confirmFlags, confirmMutation } from '../../../lib/asa-confirm.js';
+import { currencyFlag, idempotencyFlags, money, moneyFlag, scheduleFlags, startOfDayUtc } from '../../../lib/asa-flags.js';
+import { isValidUuid } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaAdGroupsUpdate extends Command {
+    static args = {
+        ad_group_id: Args.string({ description: 'Ad group ID (UUID)', required: true }),
+    };
+    static description = 'Change an ad group: bid, CPA goal, status or schedule';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa ad-groups update UUID --default-bid 1.50',
+        '<%= config.bin %> asa ad-groups update UUID --status PAUSED',
+    ];
+    static flags = {
+        ...currencyFlag,
+        ...scheduleFlags,
+        ...confirmFlags,
+        ...idempotencyFlags,
+        'automated-keywords': Flags.boolean({ allowNo: true, description: 'Let Apple add keywords automatically' }),
+        'cpa-goal': moneyFlag('CPA goal'),
+        'default-bid': moneyFlag('Default bid'),
+        name: Flags.string({ description: 'Ad group name' }),
+        status: Flags.string({ description: 'Ad group status', options: ['ENABLED', 'PAUSED'] }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(AsaAdGroupsUpdate);
+        if (!isValidUuid(args.ad_group_id))
+            this.error('Invalid ad group ID format.', { exit: 2 });
+        const body = {};
+        if (flags.name !== undefined)
+            body.name = flags.name;
+        if (flags.status !== undefined)
+            body.status = flags.status;
+        if (flags['default-bid'] !== undefined)
+            body.default_bid_amount = money(flags['default-bid'], flags.currency);
+        if (flags['cpa-goal'] !== undefined)
+            body.cpa_goal = money(flags['cpa-goal'], flags.currency);
+        if (flags['automated-keywords'] !== undefined)
+            body.automated_keywords_opt_in = flags['automated-keywords'];
+        if (flags['start-time'] !== undefined)
+            body.start_time = startOfDayUtc(flags['start-time']);
+        if (flags['end-time'] !== undefined)
+            body.end_time = startOfDayUtc(flags['end-time']);
+        if (Object.keys(body).length === 0) {
+            this.error('Nothing to change. Pass at least one field, e.g. --status PAUSED.', { exit: 2 });
+        }
+        await confirmMutation(this, { body, method: 'PUT', path: `/ad-groups/${args.ad_group_id}/`, summary: 'Update ad group' }, flags.yes);
+        const client = await createAsaClient(this.config);
+        const { replayed, result } = await asaWrite(client, 'put', `/ad-groups/${args.ad_group_id}`, {
+            body,
+            idempotencyKey: flags['idempotency-key'],
+        });
+        noteReplay(replayed, this.log.bind(this));
+        if (result.ad_group && !replayed)
+            this.log('Ad group updated!');
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

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

@@ -0,0 +1,16 @@
+import { Command } from '@oclif/core';
+import type { AsaAdMutationDTO } from '../../../lib/asa-schemas.js';
+export default class AsaAdsCreate extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'ad-group': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'creative-id': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        name: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        status: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'idempotency-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<AsaAdMutationDTO>;
+}

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

@@ -0,0 +1,41 @@
+import { Command, Flags } from '@oclif/core';
+import { asaWrite, createAsaClient, noteReplay } from '../../../lib/asa-client.js';
+import { confirmFlags, confirmMutation } from '../../../lib/asa-confirm.js';
+import { idempotencyFlags } from '../../../lib/asa-flags.js';
+import { isValidUuid } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaAdsCreate extends Command {
+    static description = 'Create an ad from a creative in an ad group';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa ads create --ad-group UUID --creative-id 4321 --name "Summer ad"'];
+    static flags = {
+        ...confirmFlags,
+        ...idempotencyFlags,
+        'ad-group': Flags.string({ description: 'Ad group ID (UUID) — the campaign is resolved from it', required: true }),
+        'creative-id': Flags.integer({ description: 'Apple creative ID from a product page or the default set', required: true }),
+        name: Flags.string({ description: 'Ad name', required: true }),
+        status: Flags.string({ description: 'Initial status', options: ['ENABLED', 'PAUSED'] }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaAdsCreate);
+        if (!isValidUuid(flags['ad-group']))
+            this.error('Invalid ad group ID format.', { exit: 2 });
+        const body = {
+            ad_group_id: flags['ad-group'],
+            creative_id: flags['creative-id'],
+            name: flags.name,
+            ...(flags.status === undefined ? {} : { status: flags.status }),
+        };
+        await confirmMutation(this, { body, method: 'POST', path: '/ads/', summary: `Create ad ${flags.name}` }, flags.yes);
+        const client = await createAsaClient(this.config);
+        const { replayed, result } = await asaWrite(client, 'post', '/ads', {
+            body,
+            idempotencyKey: flags['idempotency-key'],
+        });
+        noteReplay(replayed, this.log.bind(this));
+        if (result.ad && !replayed)
+            this.log('Ad created!');
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/asa/ads/get.d.ts

@@ -0,0 +1,11 @@
+import { Command } from '@oclif/core';
+import type { AsaAdDTO } from '../../../lib/asa-schemas.js';
+export default class AsaAdsGet extends Command {
+    static args: {
+        ad_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    run(): Promise<AsaAdDTO>;
+}

package/dist/commands/asa/ads/get.js

@@ -0,0 +1,21 @@
+import { Args, Command } from '@oclif/core';
+import { createAsaClient } from '../../../lib/asa-client.js';
+import { isValidUuid } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaAdsGet extends Command {
+    static args = {
+        ad_id: Args.string({ description: 'Ad ID (UUID)', required: true }),
+    };
+    static description = 'Show one ad and its serving state';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa ads get 550e8400-e29b-41d4-a716-446655440000'];
+    async run() {
+        const { args } = await this.parse(AsaAdsGet);
+        if (!isValidUuid(args.ad_id))
+            this.error('Invalid ad ID format.', { exit: 2 });
+        const client = await createAsaClient(this.config);
+        const result = await client.get(`/ads/${args.ad_id}`);
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/asa/ads/list.d.ts

@@ -0,0 +1,18 @@
+import { Command } from '@oclif/core';
+import type { AsaAdDTO } from '../../../lib/asa-schemas.js';
+import { type PaginatedResponse } from '../../../lib/flags.js';
+export default class AsaAdsList extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        status: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        search: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'ad-group': 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>;
+        'campaign-group': import("@oclif/core/interfaces").OptionFlag<string[] | 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>;
+    };
+    run(): Promise<PaginatedResponse<AsaAdDTO>>;
+}

package/dist/commands/asa/ads/list.js

@@ -0,0 +1,24 @@
+import { Command } from '@oclif/core';
+import { createAsaClient } from '../../../lib/asa-client.js';
+import { adScopeFlags, asaPaginationFlags, scopeParams, statusFilter } from '../../../lib/asa-flags.js';
+import { paginationParams } from '../../../lib/flags.js';
+import { printList } from '../../../lib/output.js';
+export default class AsaAdsList extends Command {
+    static description = 'List ads; serving_state_reasons explains why an enabled ad is not running';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa ads list',
+        '<%= config.bin %> asa ads list --ad-group AD_GROUP_UUID --status ENABLED',
+    ];
+    static flags = { ...asaPaginationFlags, ...adScopeFlags, ...statusFilter(['ENABLED', 'PAUSED']) };
+    async run() {
+        const { flags } = await this.parse(AsaAdsList);
+        const client = await createAsaClient(this.config);
+        const result = await client.get('/ads', {
+            ...paginationParams(flags),
+            ...scopeParams(flags),
+        });
+        printList(result.data, this.log.bind(this), result.meta.pagination);
+        return result;
+    }
+}

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

@@ -0,0 +1,17 @@
+import { Command } from '@oclif/core';
+import type { AsaAdMutationDTO } from '../../../lib/asa-schemas.js';
+export default class AsaAdsUpdate extends Command {
+    static args: {
+        ad_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        status: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'idempotency-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<AsaAdMutationDTO>;
+}

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

@@ -0,0 +1,44 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { asaWrite, createAsaClient, noteReplay } from '../../../lib/asa-client.js';
+import { confirmFlags, confirmMutation } from '../../../lib/asa-confirm.js';
+import { idempotencyFlags } from '../../../lib/asa-flags.js';
+import { isValidUuid } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaAdsUpdate extends Command {
+    static args = {
+        ad_id: Args.string({ description: 'Ad ID (UUID)', required: true }),
+    };
+    static description = 'Rename an ad or pause it; the creative and ad group are fixed at creation';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa ads update UUID --status PAUSED'];
+    static flags = {
+        ...confirmFlags,
+        ...idempotencyFlags,
+        name: Flags.string({ description: 'Ad name' }),
+        status: Flags.string({ description: 'Ad status', options: ['ENABLED', 'PAUSED'] }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(AsaAdsUpdate);
+        if (!isValidUuid(args.ad_id))
+            this.error('Invalid ad ID format.', { exit: 2 });
+        const body = {};
+        if (flags.name !== undefined)
+            body.name = flags.name;
+        if (flags.status !== undefined)
+            body.status = flags.status;
+        if (Object.keys(body).length === 0) {
+            this.error('Nothing to change. Pass --name or --status.', { exit: 2 });
+        }
+        await confirmMutation(this, { body, method: 'PUT', path: `/ads/${args.ad_id}/`, summary: 'Update ad' }, flags.yes);
+        const client = await createAsaClient(this.config);
+        const { replayed, result } = await asaWrite(client, 'put', `/ads/${args.ad_id}`, {
+            body,
+            idempotencyKey: flags['idempotency-key'],
+        });
+        noteReplay(replayed, this.log.bind(this));
+        if (result.ad && !replayed)
+            this.log('Ad updated!');
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/asa/apps/list.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+import type { AsaAppDTO } from '../../../lib/asa-schemas.js';
+import { type PaginatedResponse } from '../../../lib/flags.js';
+export default class AsaAppsList extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        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>;
+    };
+    run(): Promise<PaginatedResponse<AsaAppDTO>>;
+}

package/dist/commands/asa/apps/list.js

@@ -0,0 +1,18 @@
+import { Command } from '@oclif/core';
+import { createAsaClient } from '../../../lib/asa-client.js';
+import { asaPaginationFlags } from '../../../lib/asa-flags.js';
+import { paginationParams } from '../../../lib/flags.js';
+import { printList } from '../../../lib/output.js';
+export default class AsaAppsList extends Command {
+    static description = 'List the apps promoted by this company in Apple Search Ads';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa apps list', '<%= config.bin %> asa apps list --page 2 --page-size 50'];
+    static flags = { ...asaPaginationFlags };
+    async run() {
+        const { flags } = await this.parse(AsaAppsList);
+        const client = await createAsaClient(this.config);
+        const result = await client.get('/apps', paginationParams(flags));
+        printList(result.data, this.log.bind(this), result.meta.pagination);
+        return result;
+    }
+}