adapty 0.3.0 → 0.5.0

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

@@ -0,0 +1,25 @@
+import { Command } from '@oclif/core';
+import type { AsaCampaignMutationDTO } from '../../../lib/asa-schemas.js';
+export default class AsaCampaignsCreate extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'ad-channel-type': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'adam-id': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'bidding-strategy': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'billing-event': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        budget: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        country: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        'daily-budget': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        name: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        org: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        status: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'supply-source': import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        'target-cpa': 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>;
+        currency: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<AsaCampaignMutationDTO>;
+}

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

@@ -0,0 +1,67 @@
+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 } from '../../../lib/asa-flags.js';
+import { isValidUuid } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaCampaignsCreate extends Command {
+    static description = 'Create a campaign in Apple Search Ads';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa campaigns create --org UUID --name "Winter push" --adam-id 123456 --country US --daily-budget 50',
+    ];
+    static flags = {
+        ...currencyFlag,
+        ...confirmFlags,
+        ...idempotencyFlags,
+        'ad-channel-type': Flags.string({ default: 'SEARCH', description: 'Ad channel type', options: ['DISPLAY', 'SEARCH'] }),
+        'adam-id': Flags.integer({ description: 'App Store app ID (adam_id)', required: true }),
+        'bidding-strategy': Flags.string({
+            description: 'Bidding strategy; Apple defaults to MANUAL_CPT when omitted',
+            options: ['MANUAL_CPT', 'MAX_CONVERSIONS'],
+        }),
+        'billing-event': Flags.string({ default: 'TAPS', description: 'Billing event', options: ['IMPRESSIONS', 'TAPS'] }),
+        budget: moneyFlag('Lifetime budget'),
+        country: Flags.string({ description: 'Country or region code, repeatable', multiple: true, required: true }),
+        'daily-budget': moneyFlag('Daily budget', { required: true }),
+        name: Flags.string({ description: 'Campaign name', required: true }),
+        org: Flags.string({ description: 'Campaign group ID (UUID) — see `adapty asa orgs list`', required: true }),
+        status: Flags.string({ description: 'Initial status', options: ['ENABLED', 'PAUSED'] }),
+        'supply-source': Flags.string({
+            default: ['APPSTORE_SEARCH_RESULTS'],
+            description: 'Supply source, repeatable',
+            multiple: true,
+        }),
+        'target-cpa': moneyFlag('Target CPA'),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaCampaignsCreate);
+        if (!isValidUuid(flags.org))
+            this.error('Invalid org ID format.', { exit: 2 });
+        const body = {
+            ad_channel_type: flags['ad-channel-type'],
+            adam_id: flags['adam-id'],
+            bidding_strategy: flags['bidding-strategy'],
+            billing_event: flags['billing-event'],
+            budget_amount: money(flags.budget, flags.currency),
+            campaign_group_id: flags.org,
+            countries_or_regions: flags.country,
+            daily_budget_amount: money(flags['daily-budget'], flags.currency),
+            name: flags.name,
+            status: flags.status,
+            supply_sources: flags['supply-source'],
+            target_cpa: money(flags['target-cpa'], flags.currency),
+        };
+        await confirmMutation(this, { body, method: 'POST', path: '/campaigns/', summary: `Create campaign ${flags.name}` }, flags.yes);
+        const client = await createAsaClient(this.config);
+        const { replayed, result } = await asaWrite(client, 'post', '/campaigns', {
+            body,
+            idempotencyKey: flags['idempotency-key'],
+        });
+        noteReplay(replayed, this.log.bind(this));
+        if (result.campaign && !replayed)
+            this.log('Campaign created!');
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

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

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

package/dist/commands/asa/campaigns/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 AsaCampaignsGet extends Command {
+    static args = {
+        campaign_id: Args.string({ description: 'Campaign ID (UUID)', required: true }),
+    };
+    static description = 'Show one campaign; read numbers with asa metrics';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa campaigns get 550e8400-e29b-41d4-a716-446655440000'];
+    async run() {
+        const { args } = await this.parse(AsaCampaignsGet);
+        if (!isValidUuid(args.campaign_id))
+            this.error('Invalid campaign ID format.', { exit: 2 });
+        const client = await createAsaClient(this.config);
+        const result = await client.get(`/campaigns/${args.campaign_id}`);
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

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

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

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

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

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

@@ -0,0 +1,23 @@
+import { Command } from '@oclif/core';
+import type { AsaCampaignMutationDTO } from '../../../lib/asa-schemas.js';
+export default class AsaCampaignsUpdate extends Command {
+    static args: {
+        campaign_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'bidding-strategy': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        budget: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        country: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'daily-budget': 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>;
+        'target-cpa': 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>;
+        currency: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<AsaCampaignMutationDTO>;
+}

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

@@ -0,0 +1,66 @@
+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 } from '../../../lib/asa-flags.js';
+import { isValidUuid } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaCampaignsUpdate extends Command {
+    static args = {
+        campaign_id: Args.string({ description: 'Campaign ID (UUID)', required: true }),
+    };
+    static description = 'Change a campaign: budgets, countries, status or schedule';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa campaigns update UUID --status PAUSED',
+        '<%= config.bin %> asa campaigns update UUID --daily-budget 80',
+    ];
+    static flags = {
+        ...currencyFlag,
+        ...confirmFlags,
+        ...idempotencyFlags,
+        'bidding-strategy': Flags.string({
+            description: 'Bidding strategy',
+            options: ['MANUAL_CPT', 'MAX_CONVERSIONS'],
+        }),
+        budget: moneyFlag('Lifetime budget'),
+        country: Flags.string({ description: 'Replace the country list, repeatable', multiple: true }),
+        'daily-budget': moneyFlag('Daily budget'),
+        name: Flags.string({ description: 'Campaign name' }),
+        status: Flags.string({ description: 'Campaign status', options: ['ENABLED', 'PAUSED'] }),
+        'target-cpa': moneyFlag('Target CPA'),
+    };
+    async run() {
+        const { args, flags } = await this.parse(AsaCampaignsUpdate);
+        if (!isValidUuid(args.campaign_id))
+            this.error('Invalid campaign ID format.', { exit: 2 });
+        const body = {};
+        if (flags.name !== undefined)
+            body.name = flags.name;
+        if (flags.status !== undefined)
+            body.status = flags.status;
+        if (flags.country !== undefined)
+            body.countries_or_regions = flags.country;
+        if (flags['daily-budget'] !== undefined)
+            body.daily_budget_amount = money(flags['daily-budget'], flags.currency);
+        if (flags.budget !== undefined)
+            body.budget_amount = money(flags.budget, flags.currency);
+        if (flags['target-cpa'] !== undefined)
+            body.target_cpa = money(flags['target-cpa'], flags.currency);
+        if (flags['bidding-strategy'] !== undefined)
+            body.bidding_strategy = flags['bidding-strategy'];
+        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: `/campaigns/${args.campaign_id}/`, summary: 'Update campaign' }, flags.yes);
+        const client = await createAsaClient(this.config);
+        const { replayed, result } = await asaWrite(client, 'put', `/campaigns/${args.campaign_id}`, {
+            body,
+            idempotencyKey: flags['idempotency-key'],
+        });
+        noteReplay(replayed, this.log.bind(this));
+        if (result.campaign && !replayed)
+            this.log('Campaign updated!');
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/asa/competitors/summary.d.ts

@@ -0,0 +1,11 @@
+import { Command } from '@oclif/core';
+import type { AsaCompetitorsSummaryDTO } from '../../../lib/asa-schemas.js';
+export default class AsaCompetitorsSummary extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'app-ids': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<AsaCompetitorsSummaryDTO>;
+}

package/dist/commands/asa/competitors/summary.js

@@ -0,0 +1,56 @@
+import { Command, Flags } from '@oclif/core';
+import { asaWrite, createAsaClient } from '../../../lib/asa-client.js';
+import { printList, printResponse } from '../../../lib/output.js';
+const MAX_APP_IDS = 5;
+export default class AsaCompetitorsSummary extends Command {
+    static description = 'Competitor summary for up to five App Store apps; the server covers the last full month and every country';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa competitors summary --app-ids 1668337467,6503873027'];
+    static flags = {
+        'app-ids': Flags.string({
+            description: `Apple App Store IDs (adam_id), comma-separated, 1-${MAX_APP_IDS} values`,
+            required: true,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaCompetitorsSummary);
+        const appIds = flags['app-ids']
+            .split(',')
+            .map((part) => part.trim())
+            .filter(Boolean);
+        if (appIds.length === 0 || appIds.length > MAX_APP_IDS) {
+            this.error(`Pass 1 to ${MAX_APP_IDS} App Store IDs, got ${appIds.length}.`, { exit: 2 });
+        }
+        if (appIds.some((id) => !/^\d+$/.test(id))) {
+            this.error('App Store IDs are numbers, e.g. --app-ids 1668337467,6503873027.', { exit: 2 });
+        }
+        const client = await createAsaClient(this.config);
+        const { result } = await asaWrite(client, 'post', '/competitors/summary', {
+            body: { app_ids: appIds.map(Number) },
+        });
+        const { total } = result;
+        printResponse({
+            competitors_count: total.competitorsCount,
+            countries_asa_count: total.countriesAsaCount,
+            countries_with_asa_terms: total.countriesWithAsaTerms,
+            total_unique_terms: total.totalUniqueTerms,
+        }, this.log.bind(this));
+        this.log('');
+        this.log('Top apps by performance:');
+        printList(total.topAppsByPerformance.map((app) => ({
+            adam_id: app.adamId,
+            avg_sov: app.avgSov,
+            countries: app.countries,
+            name: app.name,
+            terms_count: app.termsCount,
+        })), this.log.bind(this));
+        this.log('');
+        this.log('Most contested terms:');
+        printList(total.mostContestedTerms.map((term) => ({
+            competitor_count: term.competitorCount,
+            max_sov: term.maxSov,
+            term: term.term,
+        })), this.log.bind(this));
+        return result;
+    }
+}

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

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+import type { AsaAppleOAuthDTO, AsaMeDTO } from '../../lib/asa-schemas.js';
+export default class AsaConnect extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        wait: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<AsaAppleOAuthDTO | AsaMeDTO>;
+}

package/dist/commands/asa/connect.js

@@ -0,0 +1,39 @@
+import { Command, Flags } from '@oclif/core';
+import open from 'open';
+import { createAsaClient } from '../../lib/asa-client.js';
+const POLL_INTERVAL_MS = 3000;
+export default class AsaConnect extends Command {
+    static description = 'Connect an Apple Search Ads account to this company';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa connect', '<%= config.bin %> asa connect --no-wait'];
+    static flags = {
+        timeout: Flags.integer({ default: 300, description: 'Seconds to wait for the browser step' }),
+        wait: Flags.boolean({ allowNo: true, default: true, description: 'Wait until Apple Ads reports as connected' }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaConnect);
+        const client = await createAsaClient(this.config);
+        const { auth_url: authUrl } = await client.get('/apple/oauth');
+        this.log(`If the browser doesn't open, visit: ${authUrl}\n`);
+        this.log('The link is valid for one hour. Sign in to the Adapty dashboard in that browser first — the last');
+        this.log('step is authorized by the dashboard session, not by this CLI.');
+        await open(authUrl).catch(() => false);
+        if (!flags.wait)
+            return { auth_url: authUrl };
+        const deadline = Date.now() + flags.timeout * 1000;
+        let status;
+        while (Date.now() < deadline) {
+            status = await client.get('/me');
+            if (status.apple_credentials_status === 'active') {
+                this.log('Apple Ads connected. The first metadata import starts automatically.');
+                return status;
+            }
+            await new Promise((resolve) => {
+                setTimeout(resolve, POLL_INTERVAL_MS);
+            });
+        }
+        this.log(`Still not connected after ${flags.timeout}s. The usual cause is a browser that is not signed in to`);
+        this.log(`the Adapty dashboard. Finish the browser step, then check with: ${this.config.bin} asa whoami`);
+        return status ?? { auth_url: authUrl };
+    }
+}

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

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

package/dist/commands/asa/creatives/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 AsaCreativesList extends Command {
+    static description = 'List creatives; creative_id is what `asa ads create` needs';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa creatives list',
+        '<%= config.bin %> asa creatives list --app APP_UUID',
+    ];
+    static flags = { ...asaPaginationFlags, ...assetScopeFlags };
+    async run() {
+        const { flags } = await this.parse(AsaCreativesList);
+        const client = await createAsaClient(this.config);
+        const result = await client.get('/creatives', {
+            ...paginationParams(flags),
+            ...scopeParams(flags),
+        });
+        printList(result.data, this.log.bind(this), result.meta.pagination);
+        return result;
+    }
+}

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

@@ -0,0 +1,20 @@
+import { Command } from '@oclif/core';
+import type { AsaKeywordMutationDTO } from '../../../lib/asa-schemas.js';
+export default class AsaKeywordsAdd 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>;
+        bid: 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>;
+        '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[] | 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>;
+        currency: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<AsaKeywordMutationDTO>;
+    private readTexts;
+}

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

@@ -0,0 +1,73 @@
+import { Command, Flags } from '@oclif/core';
+import { readFile } from 'node:fs/promises';
+import { asaWrite, createAsaClient, noteReplay } from '../../../lib/asa-client.js';
+import { confirmFlags, confirmMutation } from '../../../lib/asa-confirm.js';
+import { currencyFlag, idempotencyFlags, MAX_BULK_ITEMS, money, moneyFlag, reportBulkOutcome } from '../../../lib/asa-flags.js';
+import { isValidUuid } from '../../../lib/flags.js';
+export default class AsaKeywordsAdd extends Command {
+    static description = 'Add targeting keywords to an ad group';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa keywords add --ad-group UUID --text "running shoes" --text "trail shoes" --bid 1.20',
+        '<%= config.bin %> asa keywords add --ad-group UUID --from-file keywords.txt --match-type EXACT',
+    ];
+    static flags = {
+        ...currencyFlag,
+        ...confirmFlags,
+        ...idempotencyFlags,
+        'ad-group': Flags.string({ description: 'Ad group ID (UUID) — the campaign is resolved from it', required: true }),
+        bid: moneyFlag('Bid per keyword'),
+        'from-file': Flags.string({ description: 'File with one keyword per line, combined with any --text values' }),
+        'match-type': Flags.string({ default: 'BROAD', 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 }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaKeywordsAdd);
+        if (!isValidUuid(flags['ad-group']))
+            this.error('Invalid ad group ID format.', { exit: 2 });
+        const texts = [...(flags.text ?? []), ...(await this.readTexts(flags['from-file']))];
+        if (texts.length === 0)
+            this.error('Pass at least one --text or a --from-file with keywords.', { exit: 2 });
+        if (texts.length > MAX_BULK_ITEMS) {
+            this.error(`A single call takes at most ${MAX_BULK_ITEMS} keywords, got ${texts.length}.`, { exit: 2 });
+        }
+        const body = {
+            keywords: texts.map((text) => ({
+                ad_group_id: flags['ad-group'],
+                bid_amount: money(flags.bid, flags.currency),
+                match_type: flags['match-type'],
+                status: flags.status,
+                text,
+            })),
+        };
+        await confirmMutation(this, { body, method: 'POST', path: '/keywords/', summary: `Add ${texts.length} keyword(s)` }, flags.yes);
+        const client = await createAsaClient(this.config);
+        const { replayed, result } = await asaWrite(client, 'post', '/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;
+    }
+    async readTexts(path) {
+        if (!path)
+            return [];
+        try {
+            const raw = await readFile(path, 'utf8');
+            return raw
+                .split('\n')
+                .map((line) => line.trim())
+                .filter(Boolean);
+        }
+        catch {
+            this.error(`Could not read ${path}.`, { exit: 2 });
+        }
+    }
+}

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

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

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

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

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

@@ -0,0 +1,21 @@
+import { Command } from '@oclif/core';
+import type { AsaKeywordMutationDTO } from '../../../lib/asa-schemas.js';
+export default class AsaKeywordsUpdate extends Command {
+    static args: {
+        keyword_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        bid: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'match-type': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        status: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        text: 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>;
+        currency: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static strict: boolean;
+    run(): Promise<AsaKeywordMutationDTO>;
+}