adapty 0.4.0 → 0.5.0

package/README.md

@@ -136,6 +136,28 @@ adapty asa ads create --ad-group UUID --creative-id 4321 --name "Summer ad"
 adapty asa ads update AD_ID [--name "..."] [--status PAUSED]
 ```
 
+Bulk structure creation submits a whole tree — campaigns with nested ad groups, keywords, negative keywords
+and ads — in one call. The input is a JSON structure (the natural path for an AI agent: generate it, pipe it
+in), or a native Apple Ads template converted server-side. The whole payload is validated before anything is
+created — a rejection lists every bad node; on acceptance the command polls progress and prints the final
+report (`success` / `partial` / `failed`, with per-object failures):
+
+```sh
+adapty asa campaigns bulk-create --file structure.json          # JSON structure, waits and reports
+cat structure.json | adapty asa campaigns bulk-create --file -  # same, from stdin
+adapty asa campaigns bulk-create --file structure.json --no-wait
+adapty asa campaigns bulk-create --from-file Campaign_And_Adgroup_Template.xlsx --org-id 1234567
+adapty asa campaigns bulk-create --from-file keywords_template.csv --org-id 1234567 --preview
+adapty asa campaigns bulk-status OPERATION_ID
+```
+
+The structure is `{campaign_group_id | campaign_group_internal_id, campaigns: [...]}` where each campaign
+node either creates (`payload`) or addresses an existing campaign by id (an *anchor*, optionally carrying
+`update_payload`), and nests `ad_groups` with `keywords`, `negative_keywords` and `ads` the same way.
+`--from-file` takes the native Apple Ads templates and needs `--org-id` (the Apple org id from
+`asa orgs list`); `--preview` prints the converted request without creating anything. Conversion issues are
+reported with their sheet, row and column.
+
 Keywords are always applied as a batch, at most 100 per call, and a partial rejection is reported per item:
 
 ```sh

package/dist/commands/asa/campaigns/bulk-create.d.ts

@@ -0,0 +1,25 @@
+import { Command } from '@oclif/core';
+import type { AsaBulkOperationStateDTO } from '../../../lib/asa-schemas.js';
+export default class AsaCampaignsBulkCreate extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'from-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'org-id': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'poll-interval': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        preview: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        wait: 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>;
+    };
+    run(): Promise<AsaBulkOperationStateDTO | Record<string, unknown>>;
+    private convertTemplate;
+    private countStructure;
+    private formatIssue;
+    private readStructure;
+    private report;
+    private waitForCompletion;
+}

package/dist/commands/asa/campaigns/bulk-create.js

@@ -0,0 +1,177 @@
+import { Command, Flags } from '@oclif/core';
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+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 { printResponse } from '../../../lib/output.js';
+const TERMINAL_STATUSES = new Set(['failed', 'partial', 'success']);
+export default class AsaCampaignsBulkCreate extends Command {
+    static description = 'Create a whole campaign structure (campaigns → ad groups → keywords/negative keywords/ads) in one bulk operation';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa campaigns bulk-create --file structure.json',
+        'cat structure.json | <%= config.bin %> asa campaigns bulk-create --file -',
+        '<%= config.bin %> asa campaigns bulk-create --from-file Campaign_And_Adgroup_Template.xlsx --org-id 1234567',
+        '<%= config.bin %> asa campaigns bulk-create --from-file keywords_template.csv --org-id 1234567 --preview',
+    ];
+    static flags = {
+        ...confirmFlags,
+        ...idempotencyFlags,
+        file: Flags.string({
+            description: 'JSON file with the campaign structure (the POST /bulk-operations/ body); use "-" for stdin',
+            exactlyOne: ['file', 'from-file'],
+        }),
+        'from-file': Flags.string({
+            description: 'Apple Ads bulk template (Campaign_And_Adgroup_Template.xlsx or keywords .csv) to convert and submit',
+        }),
+        'org-id': Flags.integer({
+            description: 'Apple org id (campaign_group_id) the converted template will target; required with --from-file',
+        }),
+        'poll-interval': Flags.integer({ default: 5, description: 'Seconds between progress polls' }),
+        preview: Flags.boolean({
+            description: 'With --from-file: print the converted request and stop, nothing is created',
+        }),
+        timeout: Flags.integer({ default: 900, description: 'Max seconds to wait for the operation to finish' }),
+        wait: Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Poll the operation until it finishes; --no-wait returns the operation id immediately',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaCampaignsBulkCreate);
+        const client = await createAsaClient(this.config);
+        const body = flags['from-file'] ? await this.convertTemplate(client, flags) : await this.readStructure(flags.file);
+        if (flags.preview) {
+            this.log(JSON.stringify(body, null, 2));
+            return body;
+        }
+        const counts = this.countStructure(body);
+        const summary = `Bulk-create: ${counts.campaigns} campaign node(s), ${counts.adGroups} ad group(s), ` +
+            `${counts.keywords} keyword(s), ${counts.negativeKeywords} negative keyword(s), ${counts.ads} ad(s)`;
+        await confirmMutation(this, { body, method: 'POST', path: '/bulk-operations/', summary }, flags.yes);
+        const { replayed, result } = await asaWrite(client, 'post', '/bulk-operations', {
+            body,
+            idempotencyKey: flags['idempotency-key'],
+        });
+        noteReplay(replayed, this.log.bind(this));
+        this.log(`Operation accepted: ${result.operation_id}`);
+        if (!flags.wait) {
+            this.log(`Check progress with: adapty asa campaigns bulk-status ${result.operation_id}`);
+            return { operation_id: result.operation_id };
+        }
+        const state = await this.waitForCompletion(client, result.operation_id, flags['poll-interval'], flags.timeout);
+        this.report(state);
+        return state;
+    }
+    async convertTemplate(client, flags) {
+        if (flags['org-id'] === undefined)
+            this.error('--org-id is required with --from-file.', { exit: 2 });
+        const path = flags['from-file'];
+        let content;
+        try {
+            content = await readFile(path);
+        }
+        catch {
+            this.error(`Cannot read file: ${path}`, { exit: 2 });
+        }
+        const form = new FormData();
+        form.append('file', new Blob([new Uint8Array(content)]), basename(path));
+        form.append('campaign_group_id', String(flags['org-id']));
+        const result = await client.postForm('/bulk-operations/convert', form);
+        for (const warning of result.warnings)
+            this.warn(this.formatIssue(warning));
+        if (result.errors.length > 0 || result.request === null) {
+            for (const issue of result.errors)
+                this.log(this.formatIssue(issue));
+            this.error(`Template conversion failed with ${result.errors.length} error(s); nothing was created.`, { exit: 2 });
+        }
+        return result.request;
+    }
+    countStructure(body) {
+        const counts = { adGroups: 0, ads: 0, campaigns: 0, keywords: 0, negativeKeywords: 0 };
+        const campaigns = Array.isArray(body.campaigns) ? body.campaigns : [];
+        counts.campaigns = campaigns.length;
+        for (const campaign of campaigns) {
+            if (typeof campaign !== 'object' || campaign === null)
+                continue;
+            const campaignNode = campaign;
+            counts.negativeKeywords += Array.isArray(campaignNode.negative_keywords) ? campaignNode.negative_keywords.length : 0;
+            const adGroups = Array.isArray(campaignNode.ad_groups) ? campaignNode.ad_groups : [];
+            counts.adGroups += adGroups.length;
+            for (const adGroup of adGroups) {
+                if (typeof adGroup !== 'object' || adGroup === null)
+                    continue;
+                const adGroupNode = adGroup;
+                counts.keywords += Array.isArray(adGroupNode.keywords) ? adGroupNode.keywords.length : 0;
+                counts.negativeKeywords += Array.isArray(adGroupNode.negative_keywords) ? adGroupNode.negative_keywords.length : 0;
+                counts.ads += Array.isArray(adGroupNode.ads) ? adGroupNode.ads.length : 0;
+            }
+        }
+        return counts;
+    }
+    formatIssue(issue) {
+        const place = [issue.sheet, issue.row === null ? undefined : `row ${issue.row}`, issue.column ?? undefined]
+            .filter(Boolean)
+            .join(', ');
+        return place ? `${place}: ${issue.message}` : issue.message;
+    }
+    async readStructure(source) {
+        let raw;
+        if (source === '-') {
+            const chunks = [];
+            for await (const chunk of process.stdin)
+                chunks.push(chunk);
+            raw = Buffer.concat(chunks).toString('utf8');
+        }
+        else {
+            try {
+                raw = await readFile(source, 'utf8');
+            }
+            catch {
+                this.error(`Cannot read file: ${source}`, { exit: 2 });
+            }
+        }
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            this.error('The structure is not valid JSON.', { exit: 2 });
+        }
+    }
+    report(state) {
+        const { counts } = state;
+        this.log(`Finished: ${state.status} — ${counts.applied}/${counts.total} applied, ${counts.failed} failed`);
+        const failedObjects = state.objects.filter((object) => object.status === 'failed');
+        for (const object of failedObjects) {
+            printResponse(object, this.log.bind(this));
+            this.log('---');
+        }
+        if (state.status === 'failed')
+            this.error('Bulk operation failed.', { exit: 1 });
+        if (state.status === 'partial')
+            this.warn('Some objects were not created — see the failures above.');
+    }
+    async waitForCompletion(client, operationId, pollIntervalSeconds, timeoutSeconds) {
+        const startedAt = Date.now();
+        let lastProgress = '';
+        for (;;) {
+            const state = await client.get(`/bulk-operations/${operationId}`);
+            const progress = `${state.status}: ${state.counts.applied}/${state.counts.total} applied, ${state.counts.failed} failed`;
+            if (progress !== lastProgress) {
+                this.log(progress);
+                lastProgress = progress;
+            }
+            if (TERMINAL_STATUSES.has(state.status))
+                return state;
+            if ((Date.now() - startedAt) / 1000 >= timeoutSeconds) {
+                this.warn(`Still ${state.status} after ${timeoutSeconds}s — check later with: adapty asa campaigns bulk-status ${operationId}`);
+                return state;
+            }
+            await new Promise((resolve) => {
+                setTimeout(resolve, pollIntervalSeconds * 1000);
+            });
+        }
+    }
+}

package/dist/commands/asa/campaigns/bulk-status.d.ts

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import type { AsaBulkOperationStateDTO } from '../../../lib/asa-schemas.js';
+export default class AsaCampaignsBulkStatus extends Command {
+    static args: {
+        'operation-id': import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    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<AsaBulkOperationStateDTO>;
+}

package/dist/commands/asa/campaigns/bulk-status.js

@@ -0,0 +1,26 @@
+import { Args, Command } from '@oclif/core';
+import { createAsaClient } from '../../../lib/asa-client.js';
+import { asaPaginationFlags } from '../../../lib/asa-flags.js';
+import { isValidUuid, paginationParams } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaCampaignsBulkStatus extends Command {
+    static args = {
+        'operation-id': Args.string({ description: 'Bulk operation ID returned by bulk-create', required: true }),
+    };
+    static description = 'Progress board of one bulk operation: counts, pipelines and the per-object log';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa campaigns bulk-status 660e8400-e29b-41d4-a716-446655440001'];
+    static flags = {
+        ...asaPaginationFlags,
+    };
+    async run() {
+        const { args, flags } = await this.parse(AsaCampaignsBulkStatus);
+        const operationId = args['operation-id'];
+        if (!isValidUuid(operationId))
+            this.error('Invalid operation ID format.', { exit: 2 });
+        const client = await createAsaClient(this.config);
+        const state = await client.get(`/bulk-operations/${operationId}`, paginationParams(flags));
+        printResponse(state, this.log.bind(this));
+        return state;
+    }
+}

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

@@ -20,6 +20,7 @@ export declare class ApiClient {
     constructor(opts?: ApiClientOptions);
     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;

package/dist/lib/api-client.js

@@ -29,6 +29,9 @@ export class ApiClient {
             method: 'POST',
         }, opts);
     }
+    async postForm(path, form, params, opts) {
+        return this.request(this.buildUrl(path, params), { body: form, method: 'POST' }, opts);
+    }
     async put(path, body, params, opts) {
         return this.request(this.buildUrl(path, params), {
             body: body ? JSON.stringify(body) : undefined,
@@ -60,7 +63,7 @@ export class ApiClient {
         const headers = {
             'User-Agent': this.userAgent,
         };
-        if (init.body) {
+        if (init.body && !(init.body instanceof FormData)) {
             headers['Content-Type'] = 'application/json';
         }
         if (this.token) {

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

@@ -285,3 +285,43 @@ export interface AsaNegativeKeywordMutationDTO {
 export interface AsaAutomationMutationDTO {
     automation: AsaAutomationDTO | null;
 }
+export type AsaBulkOperationStatus = 'failed' | 'partial' | 'pending' | 'running' | 'success';
+export interface AsaBulkOperationAcceptedDTO {
+    operation_id: string;
+}
+export interface AsaBulkOperationCountsDTO {
+    applied: number;
+    failed: number;
+    pending: number;
+    total: number;
+}
+export interface AsaBulkOperationObjectDTO {
+    apple_error_code: null | string;
+    apple_error_message: null | string;
+    entity_kind: string;
+    external_id: null | number;
+    item_ref: string;
+    status: string;
+    step_type: string;
+}
+export interface AsaBulkOperationStateDTO {
+    counts: AsaBulkOperationCountsDTO;
+    created_at: string;
+    finished_at: null | string;
+    objects: AsaBulkOperationObjectDTO[];
+    operation_id: string;
+    pipelines: Record<string, unknown>[];
+    started_at: null | string;
+    status: AsaBulkOperationStatus;
+}
+export interface AsaTemplateIssueDTO {
+    column: null | string;
+    message: string;
+    row: null | number;
+    sheet: null | string;
+}
+export interface AsaBulkConvertResultDTO {
+    errors: AsaTemplateIssueDTO[];
+    request: null | Record<string, unknown>;
+    warnings: AsaTemplateIssueDTO[];
+}

package/oclif.manifest.json

@@ -2612,6 +2612,160 @@
         "update.js"
       ]
     },
+    "asa:campaigns:bulk-create": {
+      "aliases": [],
+      "args": {},
+      "description": "Create a whole campaign structure (campaigns → ad groups → keywords/negative keywords/ads) in one bulk operation",
+      "examples": [
+        "<%= config.bin %> asa campaigns bulk-create --file structure.json",
+        "cat structure.json | <%= config.bin %> asa campaigns bulk-create --file -",
+        "<%= config.bin %> asa campaigns bulk-create --from-file Campaign_And_Adgroup_Template.xlsx --org-id 1234567",
+        "<%= config.bin %> asa campaigns bulk-create --from-file keywords_template.csv --org-id 1234567 --preview"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Apply without asking; required when the output is piped or --json is used",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "idempotency-key": {
+          "description": "Idempotency key for this write; re-running with the same key replays the stored result instead of applying twice",
+          "name": "idempotency-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "file": {
+          "description": "JSON file with the campaign structure (the POST /bulk-operations/ body); use \"-\" for stdin",
+          "name": "file",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "from-file": {
+          "description": "Apple Ads bulk template (Campaign_And_Adgroup_Template.xlsx or keywords .csv) to convert and submit",
+          "name": "from-file",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "org-id": {
+          "description": "Apple org id (campaign_group_id) the converted template will target; required with --from-file",
+          "name": "org-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "poll-interval": {
+          "description": "Seconds between progress polls",
+          "name": "poll-interval",
+          "default": 5,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "preview": {
+          "description": "With --from-file: print the converted request and stop, nothing is created",
+          "name": "preview",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "timeout": {
+          "description": "Max seconds to wait for the operation to finish",
+          "name": "timeout",
+          "default": 900,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "wait": {
+          "description": "Poll the operation until it finishes; --no-wait returns the operation id immediately",
+          "name": "wait",
+          "allowNo": true,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "asa:campaigns:bulk-create",
+      "pluginAlias": "adapty",
+      "pluginName": "adapty",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "asa",
+        "campaigns",
+        "bulk-create.js"
+      ]
+    },
+    "asa:campaigns:bulk-status": {
+      "aliases": [],
+      "args": {
+        "operation-id": {
+          "description": "Bulk operation ID returned by bulk-create",
+          "name": "operation-id",
+          "required": true
+        }
+      },
+      "description": "Progress board of one bulk operation: counts, pipelines and the per-object log",
+      "examples": [
+        "<%= config.bin %> asa campaigns bulk-status 660e8400-e29b-41d4-a716-446655440001"
+      ],
+      "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:campaigns:bulk-status",
+      "pluginAlias": "adapty",
+      "pluginName": "adapty",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "asa",
+        "campaigns",
+        "bulk-status.js"
+      ]
+    },
     "asa:campaigns:create": {
       "aliases": [],
       "args": {},
@@ -3906,13 +4060,13 @@
         "list.js"
       ]
     },
-    "asa:search-terms:list": {
+    "asa:product-pages:list": {
       "aliases": [],
       "args": {},
-      "description": "List the search terms your ads matched, with their metrics",
+      "description": "List custom product pages (read-only; authoring stays in App Store Connect)",
       "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"
+        "<%= config.bin %> asa product-pages list",
+        "<%= config.bin %> asa product-pages list --app APP_UUID"
       ],
       "flags": {
         "json": {
@@ -3938,20 +4092,6 @@
           "multiple": false,
           "type": "option"
         },
-        "date-from": {
-          "description": "Start of the reporting period (YYYY-MM-DD), defaults to today",
-          "name": "date-from",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "date-to": {
-          "description": "End of the reporting period (YYYY-MM-DD), defaults to today",
-          "name": "date-to",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
         "app": {
           "description": "Keep only rows in this app; repeatable",
           "name": "app",
@@ -3965,32 +4105,11 @@
           "hasDynamicHelp": false,
           "multiple": true,
           "type": "option"
-        },
-        "search": {
-          "description": "Case-insensitive substring match on the name",
-          "name": "search",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "campaign": {
-          "description": "Keep only rows in this campaign; repeatable",
-          "name": "campaign",
-          "hasDynamicHelp": false,
-          "multiple": true,
-          "type": "option"
-        },
-        "ad-group": {
-          "description": "Keep only rows in this ad group; repeatable",
-          "name": "ad-group",
-          "hasDynamicHelp": false,
-          "multiple": true,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "asa:search-terms:list",
+      "id": "asa:product-pages:list",
       "pluginAlias": "adapty",
       "pluginName": "adapty",
       "pluginType": "core",
@@ -4001,17 +4120,17 @@
         "dist",
         "commands",
         "asa",
-        "search-terms",
+        "product-pages",
         "list.js"
       ]
     },
-    "asa:product-pages:list": {
+    "asa:product-pages:sync": {
       "aliases": [],
       "args": {},
-      "description": "List custom product pages (read-only; authoring stays in App Store Connect)",
+      "description": "Refresh custom product pages from Apple",
       "examples": [
-        "<%= config.bin %> asa product-pages list",
-        "<%= config.bin %> asa product-pages list --app APP_UUID"
+        "<%= config.bin %> asa product-pages sync",
+        "<%= config.bin %> asa product-pages sync --adam-id 123456"
       ],
       "flags": {
         "json": {
@@ -4021,40 +4140,31 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "page": {
-          "description": "Page number",
-          "name": "page",
-          "default": 1,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
+        "yes": {
+          "char": "y",
+          "description": "Apply without asking; required when the output is piped or --json is used",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
         },
-        "page-size": {
-          "description": "Items per page (max 1000); prefer one big page over a pagination loop",
-          "name": "page-size",
-          "default": 100,
+        "idempotency-key": {
+          "description": "Idempotency key for this write; re-running with the same key replays the stored result instead of applying twice",
+          "name": "idempotency-key",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "app": {
-          "description": "Keep only rows in this app; repeatable",
-          "name": "app",
-          "hasDynamicHelp": false,
-          "multiple": true,
-          "type": "option"
-        },
-        "campaign-group": {
-          "description": "Keep only rows in this campaign group; repeatable",
-          "name": "campaign-group",
+        "adam-id": {
+          "description": "Limit the refresh to one app; omit to cover every app",
+          "name": "adam-id",
           "hasDynamicHelp": false,
-          "multiple": true,
+          "multiple": false,
           "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "asa:product-pages:list",
+      "id": "asa:product-pages:sync",
       "pluginAlias": "adapty",
       "pluginName": "adapty",
       "pluginType": "core",
@@ -4066,16 +4176,16 @@
         "commands",
         "asa",
         "product-pages",
-        "list.js"
+        "sync.js"
       ]
     },
-    "asa:product-pages:sync": {
+    "asa:search-terms:list": {
       "aliases": [],
       "args": {},
-      "description": "Refresh custom product pages from Apple",
+      "description": "List the search terms your ads matched, with their metrics",
       "examples": [
-        "<%= config.bin %> asa product-pages sync",
-        "<%= config.bin %> asa product-pages sync --adam-id 123456"
+        "<%= 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"
       ],
       "flags": {
         "json": {
@@ -4085,31 +4195,75 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "yes": {
-          "char": "y",
-          "description": "Apply without asking; required when the output is piped or --json is used",
-          "name": "yes",
-          "allowNo": false,
-          "type": "boolean"
+        "page": {
+          "description": "Page number",
+          "name": "page",
+          "default": 1,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         },
-        "idempotency-key": {
-          "description": "Idempotency key for this write; re-running with the same key replays the stored result instead of applying twice",
-          "name": "idempotency-key",
+        "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"
         },
-        "adam-id": {
-          "description": "Limit the refresh to one app; omit to cover every app",
-          "name": "adam-id",
+        "date-from": {
+          "description": "Start of the reporting period (YYYY-MM-DD), defaults to today",
+          "name": "date-from",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "date-to": {
+          "description": "End of the reporting period (YYYY-MM-DD), defaults to today",
+          "name": "date-to",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "app": {
+          "description": "Keep only rows in this app; repeatable",
+          "name": "app",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "campaign-group": {
+          "description": "Keep only rows in this campaign group; repeatable",
+          "name": "campaign-group",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "search": {
+          "description": "Case-insensitive substring match on the name",
+          "name": "search",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "campaign": {
+          "description": "Keep only rows in this campaign; repeatable",
+          "name": "campaign",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "ad-group": {
+          "description": "Keep only rows in this ad group; repeatable",
+          "name": "ad-group",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "asa:product-pages:sync",
+      "id": "asa:search-terms:list",
       "pluginAlias": "adapty",
       "pluginName": "adapty",
       "pluginType": "core",
@@ -4120,10 +4274,10 @@
         "dist",
         "commands",
         "asa",
-        "product-pages",
-        "sync.js"
+        "search-terms",
+        "list.js"
       ]
     }
   },
-  "version": "0.4.0"
+  "version": "0.5.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "adapty",
   "description": "Adapty command line interface",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "author": "Adapty team <support@adapty.io>",
   "bin": {
     "adapty": "./bin/run.js"
@@ -130,6 +130,7 @@
   },
   "scripts": {
     "build": "shx rm -rf dist && tsc -b",
+    "check:agent-docs": "oclif manifest && node scripts/check-agent-docs.mjs",
     "lint": "eslint",
     "postpack": "shx rm -f oclif.manifest.json",
     "posttest": "pnpm run lint",