adapty 0.3.0 → 0.5.0

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

@@ -0,0 +1,64 @@
+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, reportBulkOutcome } from '../../../lib/asa-flags.js';
+import { isValidUuid } from '../../../lib/flags.js';
+export default class AsaKeywordsUpdate extends Command {
+    static args = {
+        keyword_id: Args.string({ description: 'Keyword ID (UUID), repeatable as extra arguments', required: true }),
+    };
+    static description = 'Change bid, status, text or match type of keywords';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa keywords update UUID --bid 2.00',
+        '<%= config.bin %> asa keywords update UUID_A UUID_B --status PAUSED',
+    ];
+    static flags = {
+        ...currencyFlag,
+        ...confirmFlags,
+        ...idempotencyFlags,
+        bid: moneyFlag('Bid'),
+        'match-type': Flags.string({ description: 'Match type', options: ['BROAD', 'EXACT'] }),
+        status: Flags.string({ description: 'Keyword status', options: ['ACTIVE', 'PAUSED'] }),
+        text: Flags.string({ description: 'Keyword text (only meaningful for a single keyword)' }),
+    };
+    static strict = false;
+    async run() {
+        const { argv, flags } = await this.parse(AsaKeywordsUpdate);
+        const keywordIds = argv;
+        for (const id of keywordIds) {
+            if (!isValidUuid(id))
+                this.error(`Invalid keyword ID format: ${id}`, { exit: 2 });
+        }
+        const change = {};
+        if (flags.bid !== undefined)
+            change.bid_amount = money(flags.bid, flags.currency);
+        if (flags.status !== undefined)
+            change.status = flags.status;
+        if (flags['match-type'] !== undefined)
+            change.match_type = flags['match-type'];
+        if (flags.text !== undefined)
+            change.text = flags.text;
+        if (Object.keys(change).length === 0) {
+            this.error('Nothing to change. Pass at least one field, e.g. --bid 2.00.', { exit: 2 });
+        }
+        if (flags.text !== undefined && keywordIds.length > 1) {
+            this.error('--text would give every keyword the same text. Update them one at a time.', { exit: 2 });
+        }
+        const body = { keywords: keywordIds.map((id) => ({ internal_id: id, ...change })) };
+        await confirmMutation(this, { body, method: 'PUT', path: '/keywords/', summary: `Update ${keywordIds.length} keyword(s)` }, flags.yes);
+        const client = await createAsaClient(this.config);
+        const { replayed, result } = await asaWrite(client, 'put', '/keywords', {
+            body,
+            idempotencyKey: flags['idempotency-key'],
+        });
+        noteReplay(replayed, this.log.bind(this));
+        reportBulkOutcome({
+            applied: result.keywords,
+            errors: result.errors,
+            isValidationFailure: result.is_validation_failure,
+            kind: 'keywords',
+        }, this.log.bind(this));
+        return result;
+    }
+}

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

@@ -0,0 +1,21 @@
+import { Command } from '@oclif/core';
+import { type PaginatedResponse } from '../../../lib/flags.js';
+export default class AsaMetrics extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'date-from': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        '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>;
+        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>;
+        '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>;
+    };
+    run(): Promise<PaginatedResponse<Record<string, unknown>>>;
+}

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

@@ -0,0 +1,68 @@
+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 { paginationParams } from '../../../lib/flags.js';
+import { printList } from '../../../lib/output.js';
+export default class AsaMetrics extends Command {
+    static description = `Query metrics for any level of the account over a date range
+
+One row per entity, already aggregated server-side and sorted by --order-by, so a top-N question is one
+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 coarsest --group-by period: 90 days for
+day or no period grouping, 180 by week, 365 by month and coarser — widen the window by coarsening the
+grouping, not by splitting into more calls. Budget: 5 metrics calls per minute, at most 2 per 10 seconds.`;
+    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 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',
+    ];
+    static flags = {
+        ...asaPaginationFlags,
+        ...byDaysFlag,
+        '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 }),
+        'group-by': Flags.string({
+            description: 'Break the rows down by a dimension, repeatable',
+            multiple: true,
+            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',
+            multiple: true,
+        }),
+        order: Flags.string({ default: 'desc', description: 'Sort direction', options: ['asc', 'desc'] }),
+        'order-by': Flags.string({
+            description: 'Metric or field to sort by; cohort metrics rank via their gross_/proceeds_/net_ names',
+        }),
+        'order-by-day': Flags.integer({
+            description: 'Rank by a cohort metric at this renewal window; must be one of the --by-days values',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaMetrics);
+        if (flags['by-days'] && flags['by-days'].length > MAX_BY_DAYS) {
+            this.error(`At most ${MAX_BY_DAYS} renewal windows per call, got ${flags['by-days'].length}.`, { exit: 2 });
+        }
+        const client = await createAsaClient(this.config);
+        const { result } = await asaWrite(client, 'post', '/metrics', {
+            body: {
+                date_from: flags['date-from'],
+                date_to: flags['date-to'],
+                entity: flags.entity,
+                order: flags.order,
+                ...(flags.metric === undefined ? {} : { metrics: flags.metric }),
+                ...(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'] }),
+                ...(flags['order-by-day'] === undefined ? {} : { order_by_day: flags['order-by-day'] }),
+            },
+            params: paginationParams(flags),
+        });
+        printList(result.data, this.log.bind(this), result.meta?.pagination);
+        return result;
+    }
+}

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

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+export default class AsaMetricsOverview extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'date-from': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        '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>;
+        metric: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'period-unit': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'by-days': import("@oclif/core/interfaces").OptionFlag<number[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<Record<string, unknown>>;
+}

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

@@ -0,0 +1,51 @@
+import { Command, Flags } from '@oclif/core';
+import { asaWrite, createAsaClient } from '../../../lib/asa-client.js';
+import { ASA_METRIC_ENTITIES, byDaysFlag, MAX_BY_DAYS } from '../../../lib/asa-flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaMetricsOverview extends Command {
+    static description = `Totals for a period, optionally split into day, week or month buckets
+
+The one-call answer to "how much did I spend / earn overall" and to any single-period trend question:
+totals for the whole entity level plus a per-period series, no pagination, no client-side summing. The
+date window is capped by --period-unit: 90 days at day, 180 by week, 365 by month and coarser. Shares
+the 5-per-minute metrics budget with asa metrics.`;
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa metrics overview --entity campaign --date-from 2026-07-01 --date-to 2026-07-31',
+        '<%= config.bin %> asa metrics overview --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --period-unit WEEK',
+    ];
+    static flags = {
+        ...byDaysFlag,
+        '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 }),
+        metric: Flags.string({
+            description: 'Metric name, repeatable; cohort roots only here (revenue, roas, arpu), not their gross_/proceeds_/net_ variants; omit for every metric',
+            multiple: true,
+        }),
+        'period-unit': Flags.string({
+            default: 'day',
+            description: 'Bucket size',
+            options: ['day', 'month', 'quarter', 'week', 'year'],
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaMetricsOverview);
+        if (flags['by-days'] && flags['by-days'].length > MAX_BY_DAYS) {
+            this.error(`At most ${MAX_BY_DAYS} renewal windows per call, got ${flags['by-days'].length}.`, { exit: 2 });
+        }
+        const client = await createAsaClient(this.config);
+        const { result } = await asaWrite(client, 'post', '/metrics/overview', {
+            body: {
+                date_from: flags['date-from'],
+                date_to: flags['date-to'],
+                entity: flags.entity,
+                period_unit: flags['period-unit'],
+                ...(flags.metric === undefined ? {} : { metrics: flags.metric }),
+                ...(flags['by-days'] === undefined ? {} : { by_days: flags['by-days'] }),
+            },
+        });
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/asa/negative-keywords/add.d.ts

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

package/dist/commands/asa/negative-keywords/add.js

@@ -0,0 +1,70 @@
+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, MAX_BULK_ITEMS, reportBulkOutcome } from '../../../lib/asa-flags.js';
+import { isValidUuid } from '../../../lib/flags.js';
+export default class AsaNegativeKeywordsAdd extends Command {
+    static description = 'Add negative keywords to an ad group or across a campaign';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa negative-keywords add --ad-group UUID --text "free"',
+        '<%= config.bin %> asa negative-keywords add --campaign UUID --text "free" --text "cheap"',
+        '<%= config.bin %> asa negative-keywords add --campaign UUID --all-ad-groups --text "free"',
+    ];
+    static flags = {
+        ...confirmFlags,
+        ...idempotencyFlags,
+        'ad-group': Flags.string({ description: 'Ad group ID (UUID) — the campaign is resolved from it', exclusive: ['campaign'] }),
+        'all-ad-groups': Flags.boolean({
+            dependsOn: ['campaign'],
+            description: 'Apply to every ad group of the campaign instead of the campaign itself',
+        }),
+        campaign: Flags.string({ description: 'Campaign ID (UUID)', exclusive: ['ad-group'] }),
+        'match-type': Flags.string({ default: 'EXACT', description: 'Match type', options: ['BROAD', 'EXACT'] }),
+        status: Flags.string({ default: 'ACTIVE', description: 'Keyword status', options: ['ACTIVE', 'PAUSED'] }),
+        text: Flags.string({ description: 'Keyword text, repeatable', multiple: true, required: true }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaNegativeKeywordsAdd);
+        const target = flags['ad-group'] ?? flags.campaign;
+        if (!target)
+            this.error('Pass either --ad-group or --campaign.', { exit: 2 });
+        if (!isValidUuid(target))
+            this.error('Invalid ID format.', { exit: 2 });
+        if (flags.text.length > MAX_BULK_ITEMS) {
+            this.error(`A single call takes at most ${MAX_BULK_ITEMS} keywords, got ${flags.text.length}.`, { exit: 2 });
+        }
+        const scope = flags['ad-group'] ? 'AD_GROUP' : flags['all-ad-groups'] ? 'ALL_CAMPAIGN_AD_GROUPS' : 'CAMPAIGN';
+        const parent = flags['ad-group'] ? { ad_group_id: flags['ad-group'] } : { campaign_id: flags.campaign };
+        const body = {
+            negative_keywords: flags.text.map((text) => ({
+                ...parent,
+                match_type: flags['match-type'],
+                status: flags.status,
+                text,
+            })),
+            scope,
+        };
+        await confirmMutation(this, {
+            body,
+            method: 'POST',
+            path: '/negative-keywords/',
+            summary: scope === 'ALL_CAMPAIGN_AD_GROUPS'
+                ? `Add ${flags.text.length} negative keyword(s) to every ad group of the campaign`
+                : `Add ${flags.text.length} negative keyword(s) in ${scope} scope`,
+        }, flags.yes);
+        const client = await createAsaClient(this.config);
+        const { replayed, result } = await asaWrite(client, 'post', '/negative-keywords', {
+            body,
+            idempotencyKey: flags['idempotency-key'],
+        });
+        noteReplay(replayed, this.log.bind(this));
+        reportBulkOutcome({
+            applied: result.negative_keywords,
+            errors: result.errors,
+            isValidationFailure: result.is_validation_failure,
+            kind: 'negative keywords',
+        }, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/asa/negative-keywords/list.d.ts

@@ -0,0 +1,19 @@
+import { Command } from '@oclif/core';
+import type { AsaNegativeKeywordDTO } from '../../../lib/asa-schemas.js';
+import { type PaginatedResponse } from '../../../lib/flags.js';
+export default class AsaNegativeKeywordsList extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'campaign-level-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        '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>;
+        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<AsaNegativeKeywordDTO>>;
+}

package/dist/commands/asa/negative-keywords/list.js

@@ -0,0 +1,29 @@
+import { Command, Flags } from '@oclif/core';
+import { createAsaClient } from '../../../lib/asa-client.js';
+import { adGroupScopeFlags, asaPaginationFlags, scopeParams } from '../../../lib/asa-flags.js';
+import { paginationParams } from '../../../lib/flags.js';
+import { printList } from '../../../lib/output.js';
+export default class AsaNegativeKeywordsList extends Command {
+    static description = 'List negative keywords; ad_group_id is empty for campaign-level ones';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa negative-keywords list',
+        '<%= config.bin %> asa negative-keywords list --campaign CAMPAIGN_UUID',
+    ];
+    static flags = {
+        ...asaPaginationFlags,
+        ...adGroupScopeFlags,
+        'campaign-level-only': Flags.boolean({ description: 'Keep only campaign-level rows (ad_group_id is null)' }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaNegativeKeywordsList);
+        const client = await createAsaClient(this.config);
+        const result = await client.get('/negative-keywords', {
+            ...paginationParams(flags),
+            ...scopeParams(flags),
+            ...(flags['campaign-level-only'] ? { campaign_level_only: 'true' } : {}),
+        });
+        printList(result.data, this.log.bind(this), result.meta.pagination);
+        return result;
+    }
+}

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

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+import type { AsaCampaignGroupDTO } from '../../../lib/asa-schemas.js';
+import { type PaginatedResponse } from '../../../lib/flags.js';
+export default class AsaOrgsList 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<AsaCampaignGroupDTO>>;
+}

package/dist/commands/asa/orgs/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 AsaOrgsList extends Command {
+    static description = 'List the Apple Search Ads organizations this company can spend from';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa orgs list'];
+    static flags = { ...asaPaginationFlags };
+    async run() {
+        const { flags } = await this.parse(AsaOrgsList);
+        const client = await createAsaClient(this.config);
+        const result = await client.get('/campaign-groups', paginationParams(flags));
+        printList(result.data, this.log.bind(this), result.meta.pagination);
+        return result;
+    }
+}

package/dist/commands/asa/product-pages/list.d.ts

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

package/dist/commands/asa/product-pages/list.js

@@ -0,0 +1,24 @@
+import { Command } from '@oclif/core';
+import { createAsaClient } from '../../../lib/asa-client.js';
+import { asaPaginationFlags, assetScopeFlags, scopeParams } from '../../../lib/asa-flags.js';
+import { paginationParams } from '../../../lib/flags.js';
+import { printList } from '../../../lib/output.js';
+export default class AsaProductPagesList extends Command {
+    static description = 'List custom product pages (read-only; authoring stays in App Store Connect)';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa product-pages list',
+        '<%= config.bin %> asa product-pages list --app APP_UUID',
+    ];
+    static flags = { ...asaPaginationFlags, ...assetScopeFlags };
+    async run() {
+        const { flags } = await this.parse(AsaProductPagesList);
+        const client = await createAsaClient(this.config);
+        const result = await client.get('/product-pages', {
+            ...paginationParams(flags),
+            ...scopeParams(flags),
+        });
+        printList(result.data, this.log.bind(this), result.meta.pagination);
+        return result;
+    }
+}

package/dist/commands/asa/product-pages/sync.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+import type { AsaProductPageSyncDTO } from '../../../lib/asa-schemas.js';
+export default class AsaProductPagesSync extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'adam-id': import("@oclif/core/interfaces").OptionFlag<number | 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<AsaProductPageSyncDTO>;
+}

package/dist/commands/asa/product-pages/sync.js

@@ -0,0 +1,28 @@
+import { Command, Flags } from '@oclif/core';
+import { asaWrite, createAsaClient } from '../../../lib/asa-client.js';
+import { confirmFlags, confirmMutation } from '../../../lib/asa-confirm.js';
+import { idempotencyFlags } from '../../../lib/asa-flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaProductPagesSync extends Command {
+    static description = 'Refresh custom product pages from Apple';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa product-pages sync', '<%= config.bin %> asa product-pages sync --adam-id 123456'];
+    static flags = {
+        ...confirmFlags,
+        ...idempotencyFlags,
+        'adam-id': Flags.integer({ description: 'Limit the refresh to one app; omit to cover every app' }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaProductPagesSync);
+        const body = { ...(flags['adam-id'] === undefined ? {} : { adam_id: flags['adam-id'] }) };
+        await confirmMutation(this, { body, method: 'POST', path: '/product-pages/sync/', summary: 'Queue a product page refresh from Apple' }, flags.yes);
+        const client = await createAsaClient(this.config);
+        const { result } = await asaWrite(client, 'post', '/product-pages/sync', {
+            body,
+            idempotencyKey: flags['idempotency-key'],
+        });
+        this.log(result.replayed ? 'Already running; nothing new was queued.' : 'Sync queued.');
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/asa/search-terms/list.d.ts

@@ -0,0 +1,20 @@
+import { Command } from '@oclif/core';
+import type { AsaSearchTermDTO } from '../../../lib/asa-schemas.js';
+import { type PaginatedResponse } from '../../../lib/flags.js';
+export default class AsaSearchTermsList extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        '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>;
+        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>;
+        'date-from': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'date-to': 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<AsaSearchTermDTO>>;
+}

package/dist/commands/asa/search-terms/list.js

@@ -0,0 +1,25 @@
+import { Command } from '@oclif/core';
+import { createAsaClient } from '../../../lib/asa-client.js';
+import { adGroupScopeFlags, asaPaginationFlags, periodFlags, periodParams, scopeParams } from '../../../lib/asa-flags.js';
+import { paginationParams } from '../../../lib/flags.js';
+import { printList } from '../../../lib/output.js';
+export default class AsaSearchTermsList extends Command {
+    static description = 'List the search terms your ads matched, with their metrics';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa search-terms list --date-from 2026-07-01 --date-to 2026-07-31',
+        '<%= config.bin %> asa search-terms list --ad-group AD_GROUP_UUID',
+    ];
+    static flags = { ...asaPaginationFlags, ...periodFlags, ...adGroupScopeFlags };
+    async run() {
+        const { flags } = await this.parse(AsaSearchTermsList);
+        const client = await createAsaClient(this.config);
+        const result = await client.get('/search-terms', {
+            ...paginationParams(flags),
+            ...periodParams(flags),
+            ...scopeParams(flags),
+        });
+        printList(result.data, this.log.bind(this), result.meta.pagination);
+        return result;
+    }
+}

package/dist/commands/asa/whoami.d.ts

@@ -0,0 +1,8 @@
+import { Command } from '@oclif/core';
+import type { AsaMeDTO } from '../../lib/asa-schemas.js';
+export default class AsaWhoami extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    run(): Promise<AsaMeDTO>;
+}

package/dist/commands/asa/whoami.js

@@ -0,0 +1,22 @@
+import { Command } from '@oclif/core';
+import { createAsaClient } from '../../lib/asa-client.js';
+import { printResponse } from '../../lib/output.js';
+export default class AsaWhoami extends Command {
+    static description = 'Show which company the token unlocks and whether Apple Ads is connected';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa whoami'];
+    async run() {
+        await this.parse(AsaWhoami);
+        const client = await createAsaClient(this.config);
+        const result = await client.get('/me');
+        printResponse(result, this.log.bind(this));
+        if (result.apple_credentials_status !== 'active') {
+            this.log('\nApple Ads is not connected. Run `adapty asa connect` to link an account.');
+        }
+        if (result.access_source === 'none') {
+            this.log('\nNo active Ads Manager subscription for this company: connecting an account works, but every');
+            this.log('data command answers 402 until the subscription is in place.');
+        }
+        return result;
+    }
+}

package/dist/lib/api-client.d.ts

@@ -1,15 +1,28 @@
+import { type ApiErrorFormat } from './errors.js';
+export type QueryParams = Record<string, string | string[] | undefined>;
+export interface RequestOptions {
+    headers?: Record<string, string>;
+    onResponse?: (headers: Headers) => void;
+}
 export interface ApiClientOptions {
     baseUrl?: string;
+    defaultBaseUrl?: string;
+    errorFormat?: ApiErrorFormat;
     token?: null | string;
+    urlEnvVar?: string;
     userAgent?: string;
 }
 export declare class ApiClient {
     private baseUrl;
+    private errorFormat;
     private token;
     private userAgent;
     constructor(opts?: ApiClientOptions);
-    get<T = unknown>(path: string, params?: Record<string, string>): Promise<T>;
-    post<T = unknown>(path: string, body?: unknown): Promise<T>;
-    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    get<T = unknown>(path: string, params?: QueryParams): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, params?: QueryParams, opts?: RequestOptions): Promise<T>;
+    postForm<T = unknown>(path: string, form: FormData, params?: QueryParams, opts?: RequestOptions): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown, params?: QueryParams, opts?: RequestOptions): Promise<T>;
+    private buildUrl;
+    private isRetryableRateLimit;
     private request;
 }