adapty 0.3.0 → 0.4.0

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>;
+}

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;
+    }
+}