adapty 0.8.1 → 0.8.3-beta.0

package/README.md

@@ -137,11 +137,15 @@ Campaign structure. These lists return metadata only — numbers come from `asa
 adapty asa campaigns list
 adapty asa campaigns get CAMPAIGN_ID
 adapty asa campaigns create --org UUID --name "Winter push" --adam-id 123456 --country US --daily-budget 50
+adapty asa campaigns create --org UUID --name "LOC push" --adam-id 123456 --country US --daily-budget 50 \
+  --invoice-advertiser "Acme Inc" --invoice-order-number PO-42 --invoice-contact-name "Jane Doe" \
+  --invoice-contact-email jane@acme.com --invoice-billing-email billing@acme.com   # payment_model LOC
 adapty asa campaigns update CAMPAIGN_ID [--status PAUSED] [--daily-budget 80] [--country US]
 
 adapty asa ad-groups list
 adapty asa ad-groups get AD_GROUP_ID
 adapty asa ad-groups create --campaign UUID --name "Brand terms" --default-bid 1.20
+adapty asa ad-groups create --campaign UUID --name "Automated Max Conv" --automated   # Max Conversions campaigns
 adapty asa ad-groups update AD_GROUP_ID [--default-bid 1.50] [--status PAUSED]
 
 adapty asa ads list

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

@@ -5,6 +5,7 @@ export default class AsaAdGroupsCreate extends Command {
     static enableJsonFlag: boolean;
     static examples: string[];
     static flags: {
+        automated: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'automated-keywords': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         campaign: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'cpa-goal': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

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

@@ -1,15 +1,16 @@
 import { Command, Flags } from '@oclif/core';
 import { asaWrite, createAsaClient, noteReplay } from '../../../lib/asa-client.js';
-import { confirmFlags, confirmMutation } from '../../../lib/asa-confirm.js';
 import { currencyFlag, idempotencyFlags, money, moneyFlag, pricingModelFlag, scheduleFlags, startOfDayUtc, todayUtc, } from '../../../lib/asa-flags.js';
+import { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
 import { isValidUuid } from '../../../lib/flags.js';
 import { printResponse } from '../../../lib/output.js';
 export default class AsaAdGroupsCreate extends Command {
-    static description = 'Create an ad group inside a campaign';
+    static description = 'Create an ad group inside a campaign; --automated creates the automated ad group a Max Conversions campaign needs to run';
     static enableJsonFlag = true;
     static examples = [
         '<%= config.bin %> asa ad-groups create --campaign UUID --name "Brand terms" --default-bid 1.20',
         '<%= config.bin %> asa ad-groups create --campaign UUID --name "Brand terms" --default-bid 1.20 --start-time 2026-09-01 --pricing-model CPM',
+        '<%= config.bin %> asa ad-groups create --campaign UUID --name "Automated Max Conv" --automated',
     ];
     static flags = {
         ...currencyFlag,
@@ -17,10 +18,14 @@ export default class AsaAdGroupsCreate extends Command {
         ...pricingModelFlag,
         ...confirmFlags,
         ...idempotencyFlags,
+        automated: Flags.boolean({
+            description: 'Create the automated ad group a Max Conversions campaign needs (no bid, no schedule, always ENABLED)',
+            exclusive: ['automated-keywords'],
+        }),
         'automated-keywords': Flags.boolean({ allowNo: true, description: 'Let Apple add keywords automatically' }),
         campaign: Flags.string({ description: 'Campaign ID (UUID)', required: true }),
         'cpa-goal': moneyFlag('CPA goal'),
-        'default-bid': moneyFlag('Default bid', { required: true }),
+        'default-bid': moneyFlag('Default bid; required unless --automated is set'),
         name: Flags.string({ description: 'Ad group name', required: true }),
         status: Flags.string({ description: 'Initial status', options: ['ENABLED', 'PAUSED'] }),
     };
@@ -28,15 +33,25 @@ export default class AsaAdGroupsCreate extends Command {
         const { flags } = await this.parse(AsaAdGroupsCreate);
         if (!isValidUuid(flags.campaign))
             this.error('Invalid campaign ID format.', { exit: 2 });
+        if (!flags.automated && flags['default-bid'] === undefined) {
+            this.error('--default-bid is required unless --automated is set.', { exit: 2 });
+        }
+        if (flags.automated && flags['start-time'] !== undefined) {
+            this.error('--start-time is not allowed with --automated: Apple schedules the automated ad group itself.', { exit: 2 });
+        }
+        if (flags.automated && flags.status === 'PAUSED') {
+            this.error('An automated ad group must be ENABLED; pause the campaign instead.', { exit: 2 });
+        }
         const body = {
-            automated_keywords_opt_in: flags['automated-keywords'],
+            automated_keywords_opt_in: flags.automated ? true : flags['automated-keywords'],
+            automated_keywords_required: flags.automated ? true : undefined,
             campaign_id: flags.campaign,
             cpa_goal: money(flags['cpa-goal'], flags.currency),
             default_bid_amount: money(flags['default-bid'], flags.currency),
             end_time: startOfDayUtc(flags['end-time']),
             name: flags.name,
             pricing_model: flags['pricing-model'],
-            start_time: startOfDayUtc(flags['start-time'] ?? todayUtc()),
+            start_time: flags.automated ? undefined : startOfDayUtc(flags['start-time'] ?? todayUtc()),
             status: flags.status,
         };
         await confirmMutation(this, { body, method: 'POST', path: '/ad-groups/', summary: `Create ad group ${flags.name}` }, flags.yes);

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

@@ -1,7 +1,7 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { asaWrite, createAsaClient, noteReplay } from '../../../lib/asa-client.js';
-import { confirmFlags, confirmMutation } from '../../../lib/asa-confirm.js';
 import { currencyFlag, idempotencyFlags, money, moneyFlag, scheduleFlags, startOfDayUtc } from '../../../lib/asa-flags.js';
+import { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
 import { isValidUuid } from '../../../lib/flags.js';
 import { printResponse } from '../../../lib/output.js';
 export default class AsaAdGroupsUpdate extends Command {

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

@@ -1,7 +1,7 @@
 import { Command, Flags } from '@oclif/core';
 import { asaWrite, createAsaClient, noteReplay } from '../../../lib/asa-client.js';
-import { confirmFlags, confirmMutation } from '../../../lib/asa-confirm.js';
 import { idempotencyFlags } from '../../../lib/asa-flags.js';
+import { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
 import { isValidUuid } from '../../../lib/flags.js';
 import { printResponse } from '../../../lib/output.js';
 export default class AsaAdsCreate extends Command {

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

@@ -1,7 +1,7 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { asaWrite, createAsaClient, noteReplay } from '../../../lib/asa-client.js';
-import { confirmFlags, confirmMutation } from '../../../lib/asa-confirm.js';
 import { idempotencyFlags } from '../../../lib/asa-flags.js';
+import { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
 import { isValidUuid } from '../../../lib/flags.js';
 import { printResponse } from '../../../lib/output.js';
 export default class AsaAdsUpdate extends Command {

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

@@ -1,8 +1,8 @@
 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 { idempotencyFlags } from '../../../lib/asa-flags.js';
+import { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
 import { printResponse } from '../../../lib/output.js';
 export default class AsaAutomationsCreate extends Command {
     static description = 'Create an automation rule from a JSON rule file';

package/dist/commands/asa/automations/run.js

@@ -1,7 +1,7 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { asaWrite, createAsaClient, noteReplay } from '../../../lib/asa-client.js';
-import { confirmFlags, confirmMutation } from '../../../lib/asa-confirm.js';
 import { idempotencyFlags } from '../../../lib/asa-flags.js';
+import { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
 import { isValidUuid } from '../../../lib/flags.js';
 export default class AsaAutomationsRun extends Command {
     static args = {

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

@@ -1,8 +1,8 @@
 import { Args, 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 { idempotencyFlags } from '../../../lib/asa-flags.js';
+import { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
 import { isValidUuid } from '../../../lib/flags.js';
 import { printResponse } from '../../../lib/output.js';
 export default class AsaAutomationsUpdate extends Command {

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

@@ -2,8 +2,8 @@ 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 { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
 import { printResponse } from '../../../lib/output.js';
 const TERMINAL_STATUSES = new Set(['failed', 'partial', 'success']);
 export default class AsaCampaignsBulkCreate extends Command {

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

@@ -17,6 +17,11 @@ export default class AsaCampaignsCreate extends Command {
         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>;
+        'invoice-advertiser': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'invoice-billing-email': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'invoice-contact-email': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'invoice-contact-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'invoice-order-number': 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>;

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

@@ -1,19 +1,22 @@
 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 { currencyFlag, idempotencyFlags, invoiceFlags, locInvoiceDetails, money, moneyFlag, reportServingState, } from '../../../lib/asa-flags.js';
+import { confirmFlags, confirmMutation } from '../../../lib/confirm.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 description = 'Create a campaign in Apple Search Ads. A Max Conversions campaign also needs an automated ad group (`asa ad-groups create --automated`); line-of-credit organizations must pass all five --invoice-* flags';
     static enableJsonFlag = true;
     static examples = [
         '<%= config.bin %> asa campaigns create --org UUID --name "Winter push" --adam-id 123456 --country US --daily-budget 50',
+        '<%= config.bin %> asa campaigns create --org UUID --name "Max Conv" --adam-id 123456 --country US --daily-budget 50 --bidding-strategy MAX_CONVERSIONS',
+        '<%= config.bin %> asa campaigns create --org UUID --name "LOC push" --adam-id 123456 --country US --daily-budget 50 --invoice-advertiser "Acme Inc" --invoice-order-number PO-42 --invoice-contact-name "Jane Doe" --invoice-contact-email jane@acme.com --invoice-billing-email billing@acme.com',
     ];
     static flags = {
         ...currencyFlag,
         ...confirmFlags,
         ...idempotencyFlags,
+        ...invoiceFlags,
         '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({
@@ -32,12 +35,19 @@ export default class AsaCampaignsCreate extends Command {
             description: 'Supply source, repeatable',
             multiple: true,
         }),
-        'target-cpa': moneyFlag('Target CPA'),
+        'target-cpa': moneyFlag('Target CPA; must be lower than --daily-budget'),
     };
     async run() {
         const { flags } = await this.parse(AsaCampaignsCreate);
         if (!isValidUuid(flags.org))
             this.error('Invalid org ID format.', { exit: 2 });
+        let invoice;
+        try {
+            invoice = locInvoiceDetails(flags);
+        }
+        catch (error) {
+            this.error(error.message, { exit: 2 });
+        }
         const body = {
             ad_channel_type: flags['ad-channel-type'],
             adam_id: flags['adam-id'],
@@ -47,6 +57,7 @@ export default class AsaCampaignsCreate extends Command {
             campaign_group_id: flags.org,
             countries_or_regions: flags.country,
             daily_budget_amount: money(flags['daily-budget'], flags.currency),
+            loc_invoice_details: invoice,
             name: flags.name,
             status: flags.status,
             supply_sources: flags['supply-source'],
@@ -62,6 +73,7 @@ export default class AsaCampaignsCreate extends Command {
         if (result.campaign && !replayed)
             this.log('Campaign created!');
         printResponse(result, this.log.bind(this));
+        reportServingState(result.campaign, this.warn.bind(this));
         return result;
     }
 }

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

@@ -15,6 +15,11 @@ export default class AsaCampaignsUpdate extends Command {
         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>;
+        'invoice-advertiser': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'invoice-billing-email': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'invoice-contact-email': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'invoice-contact-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'invoice-order-number': 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>;

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

@@ -1,23 +1,25 @@
 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 { currencyFlag, idempotencyFlags, invoiceFlags, locInvoiceDetails, money, moneyFlag, reportServingState, } from '../../../lib/asa-flags.js';
+import { confirmFlags, confirmMutation } from '../../../lib/confirm.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 description = 'Change a campaign: budgets, countries, status, schedule or Invoicing Options (all five --invoice-* flags together; they replace the stored set)';
     static enableJsonFlag = true;
     static examples = [
         '<%= config.bin %> asa campaigns update UUID --status PAUSED',
         '<%= config.bin %> asa campaigns update UUID --daily-budget 80',
+        '<%= config.bin %> asa campaigns update UUID --invoice-advertiser "Acme Inc" --invoice-order-number PO-42 --invoice-contact-name "Jane Doe" --invoice-contact-email jane@acme.com --invoice-billing-email billing@acme.com',
     ];
     static flags = {
         ...currencyFlag,
         ...confirmFlags,
         ...idempotencyFlags,
+        ...invoiceFlags,
         'bidding-strategy': Flags.string({
             description: 'Bidding strategy',
             options: ['MANUAL_CPT', 'MAX_CONVERSIONS'],
@@ -48,8 +50,16 @@ export default class AsaCampaignsUpdate extends Command {
             body.target_cpa = money(flags['target-cpa'], flags.currency);
         if (flags['bidding-strategy'] !== undefined)
             body.bidding_strategy = flags['bidding-strategy'];
+        try {
+            const details = locInvoiceDetails(flags);
+            if (details)
+                body.loc_invoice_details = details;
+        }
+        catch (error) {
+            this.error(error.message, { exit: 2 });
+        }
         if (Object.keys(body).length === 0) {
-            this.error('Nothing to change. Pass at least one field, e.g. --status PAUSED.', { exit: 2 });
+            this.error('Nothing to change. Pass at least one field, e.g. --status PAUSED, or the five --invoice-* flags for a line-of-credit organization.', { exit: 2 });
         }
         await confirmMutation(this, { body, method: 'PUT', path: `/campaigns/${args.campaign_id}/`, summary: 'Update campaign' }, flags.yes);
         const client = await createAsaClient(this.config);
@@ -61,6 +71,7 @@ export default class AsaCampaignsUpdate extends Command {
         if (result.campaign && !replayed)
             this.log('Campaign updated!');
         printResponse(result, this.log.bind(this));
+        reportServingState(result.campaign, this.warn.bind(this));
         return result;
     }
 }

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

@@ -1,8 +1,8 @@
 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 { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
 import { isValidUuid } from '../../../lib/flags.js';
 export default class AsaKeywordsAdd extends Command {
     static description = 'Add targeting keywords to an ad group';

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

@@ -1,7 +1,7 @@
 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 { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
 import { isValidUuid } from '../../../lib/flags.js';
 export default class AsaKeywordsUpdate extends Command {
     static args = {

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

@@ -1,7 +1,7 @@
 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 { confirmFlags, confirmMutation } from '../../../lib/confirm.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';

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

@@ -1,7 +1,7 @@
 import { Command, Flags } from '@oclif/core';
 import { asaWrite, createAsaClient } from '../../../lib/asa-client.js';
-import { confirmFlags, confirmMutation } from '../../../lib/asa-confirm.js';
 import { idempotencyFlags } from '../../../lib/asa-flags.js';
+import { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
 import { printResponse } from '../../../lib/output.js';
 export default class AsaProductPagesSync extends Command {
     static description = 'Refresh custom product pages from Apple';

package/dist/commands/flows/publish.d.ts

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import type { FlowDTO } from '../../lib/api-schemas.js';
+export default class FlowsPublish extends Command {
+    static args: {
+        flow_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        app: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<FlowDTO>;
+}

package/dist/commands/flows/publish.js

@@ -0,0 +1,34 @@
+import { Args, Command } from '@oclif/core';
+import { createAuthenticatedClient } from '../../lib/client-from-config.js';
+import { confirmFlags, confirmMutation } from '../../lib/confirm.js';
+import { appFlag, isValidUuid } from '../../lib/flags.js';
+import { printResponse } from '../../lib/output.js';
+export default class FlowsPublish extends Command {
+    static args = {
+        flow_id: Args.string({ description: 'Flow ID (UUID)', required: true }),
+    };
+    static description = 'Publish a flow (async — publication completes in the background)';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> flows publish --app UUID 550e8400-e29b-41d4-a716-446655440000'];
+    static flags = {
+        ...appFlag,
+        ...confirmFlags,
+    };
+    async run() {
+        const { args, flags } = await this.parse(FlowsPublish);
+        if (!isValidUuid(args.flow_id)) {
+            this.error('Invalid flow ID format.', { exit: 2 });
+        }
+        const client = await createAuthenticatedClient(this.config);
+        const flow = await client.get(`/apps/${flags.app}/flows/${args.flow_id}/`);
+        await confirmMutation(this, {
+            method: 'POST',
+            path: `/apps/${flags.app}/flows/${args.flow_id}/publish/`,
+            summary: `Publish flow "${flow.name}" live to end users`,
+        }, flags.yes);
+        const result = await client.post(`/apps/${flags.app}/flows/${args.flow_id}/publish/`);
+        this.log('Publishing started — status: publishing. Publication completes asynchronously.');
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/flows/update.d.ts

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import type { FlowDTO } from '../../lib/api-schemas.js';
+export default class FlowsUpdate extends Command {
+    static args: {
+        flow_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        name: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        app: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<FlowDTO>;
+}

package/dist/commands/flows/update.js

@@ -0,0 +1,28 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { createAuthenticatedClient } from '../../lib/client-from-config.js';
+import { appFlag, isValidUuid } from '../../lib/flags.js';
+import { printResponse } from '../../lib/output.js';
+export default class FlowsUpdate extends Command {
+    static args = {
+        flow_id: Args.string({ description: 'Flow ID (UUID)', required: true }),
+    };
+    static description = 'Rename a flow';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> flows update --app UUID 550e8400-e29b-41d4-a716-446655440000 --name "Onboarding v2"'];
+    static flags = {
+        ...appFlag,
+        name: Flags.string({ description: 'New flow name', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FlowsUpdate);
+        if (!isValidUuid(args.flow_id)) {
+            this.error('Invalid flow ID format.', { exit: 2 });
+        }
+        const body = { name: flags.name };
+        const client = await createAuthenticatedClient(this.config);
+        const result = await client.put(`/apps/${flags.app}/flows/${args.flow_id}/`, body);
+        this.log('Flow updated!');
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/placements/create.js

@@ -2,17 +2,22 @@ import { Command, Flags } from '@oclif/core';
 import { createAuthenticatedClient } from '../../lib/client-from-config.js';
 import { appFlag } from '../../lib/flags.js';
 import { printResponse } from '../../lib/output.js';
+import { audienceEntryProblem } from '../../lib/placement-audiences.js';
 export default class PlacementsCreate extends Command {
     static description = 'Create a placement with a paywall';
     static enableJsonFlag = true;
     static examples = [
-        '<%= config.bin %> placements create --app UUID --title "Default" --developer-id default --audiences \'[{"segment_ids":[],"paywall_id":"PAYWALL_UUID","priority":0}]\'',
+        '<%= config.bin %> placements create --app UUID --title "Default" --developer-id default --audiences \'[{"content_type":"paywall","segment_ids":[],"paywall_id":"PAYWALL_UUID","priority":0}]\'',
+        '<%= config.bin %> placements create --app UUID --title "Default" --developer-id default --audiences \'[{"content_type":"flow","segment_ids":[],"flow_id":"FLOW_UUID","priority":0}]\'',
         '<%= config.bin %> placements create --app UUID --title "Default" --developer-id default --paywall-id PAYWALL_UUID',
     ];
     static flags = {
         ...appFlag,
         audiences: Flags.string({
-            description: 'JSON array of audience entries: [{segment_ids, paywall_id, priority}]',
+            description: 'JSON array of audience entries. Every entry needs an explicit content_type. ' +
+                'Paywall: {content_type:"paywall", segment_ids, paywall_id, priority}. ' +
+                'Flow: {content_type:"flow", segment_ids, flow_id, priority}. ' +
+                'A flow must be published first (flows publish) — attaching a draft flow returns 400.',
             exactlyOne: ['paywall-id', 'audiences'],
         }),
         'developer-id': Flags.string({ description: 'Developer ID for the placement', required: true }),
@@ -36,12 +41,22 @@ export default class PlacementsCreate extends Command {
             body.paywall_id = flags['paywall-id'];
         }
         else {
+            let parsed;
             try {
-                body.audiences = JSON.parse(flags.audiences);
+                parsed = JSON.parse(flags.audiences);
             }
             catch (error) {
                 this.error(`Invalid --audiences JSON: ${error instanceof Error ? error.message : String(error)}`, { exit: 2 });
             }
+            if (!Array.isArray(parsed)) {
+                this.error('--audiences must be a JSON array of audience entries.', { exit: 2 });
+            }
+            for (const [index, entry] of parsed.entries()) {
+                const problem = audienceEntryProblem(entry);
+                if (problem)
+                    this.error(`--audiences[${index}]: ${problem}`, { exit: 2 });
+            }
+            body.audiences = parsed;
         }
         const client = await createAuthenticatedClient(this.config);
         const result = await client.post(`/apps/${flags.app}/placements`, body);

package/dist/commands/placements/update.js

@@ -2,6 +2,7 @@ import { Args, Command, Flags } from '@oclif/core';
 import { createAuthenticatedClient } from '../../lib/client-from-config.js';
 import { appFlag, isValidUuid } from '../../lib/flags.js';
 import { printResponse } from '../../lib/output.js';
+import { audienceEntryProblem } from '../../lib/placement-audiences.js';
 export default class PlacementsUpdate extends Command {
     static args = {
         placement_id: Args.string({ description: 'Placement ID (UUID)', required: true }),
@@ -9,13 +10,17 @@ export default class PlacementsUpdate extends Command {
     static description = 'Update a placement';
     static enableJsonFlag = true;
     static examples = [
-        '<%= config.bin %> placements update --app UUID 550e8400-... --title "Default" --developer-id default --audiences \'[{"segment_ids":[],"paywall_id":"PAYWALL_UUID","priority":0}]\'',
+        '<%= config.bin %> placements update --app UUID 550e8400-... --title "Default" --developer-id default --audiences \'[{"content_type":"paywall","segment_ids":[],"paywall_id":"PAYWALL_UUID","priority":0}]\'',
+        '<%= config.bin %> placements update --app UUID 550e8400-... --title "Default" --developer-id default --audiences \'[{"content_type":"flow","segment_ids":[],"flow_id":"FLOW_UUID","priority":0}]\'',
         '<%= config.bin %> placements update --app UUID 550e8400-... --title "Default" --developer-id default --paywall-id PAYWALL_UUID',
     ];
     static flags = {
         ...appFlag,
         audiences: Flags.string({
-            description: 'JSON array of audience entries: [{segment_ids, paywall_id, priority}]',
+            description: 'JSON array of audience entries. Every entry needs an explicit content_type. ' +
+                'Paywall: {content_type:"paywall", segment_ids, paywall_id, priority}. ' +
+                'Flow: {content_type:"flow", segment_ids, flow_id, priority}. ' +
+                'A flow must be published first (flows publish) — attaching a draft flow returns 400.',
             exactlyOne: ['paywall-id', 'audiences'],
         }),
         'developer-id': Flags.string({ description: 'Developer ID for the placement', required: true }),
@@ -45,12 +50,22 @@ export default class PlacementsUpdate extends Command {
             body.paywall_id = flags['paywall-id'];
         }
         else {
+            let parsed;
             try {
-                body.audiences = JSON.parse(flags.audiences);
+                parsed = JSON.parse(flags.audiences);
             }
             catch (error) {
                 this.error(`Invalid --audiences JSON: ${error instanceof Error ? error.message : String(error)}`, { exit: 2 });
             }
+            if (!Array.isArray(parsed)) {
+                this.error('--audiences must be a JSON array of audience entries.', { exit: 2 });
+            }
+            for (const [index, entry] of parsed.entries()) {
+                const problem = audienceEntryProblem(entry);
+                if (problem)
+                    this.error(`--audiences[${index}]: ${problem}`, { exit: 2 });
+            }
+            body.audiences = parsed;
         }
         const client = await createAuthenticatedClient(this.config);
         const result = await client.put(`/apps/${flags.app}/placements/${args.placement_id}`, body);

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

@@ -129,11 +129,20 @@ export interface SegmentDTO {
     id: string;
     title: string;
 }
-export interface PlacementAudienceEntryDTO {
+export interface PlacementPaywallAudienceEntryDTO {
+    content_type: 'paywall';
     paywall_id: string;
     priority: number;
     segment_ids?: string[];
 }
+export interface PlacementFlowAudienceEntryDTO {
+    content_type: 'flow';
+    /** The flow must be `published` (not draft) — the backend returns 400 otherwise. */
+    flow_id: string;
+    priority: number;
+    segment_ids?: string[];
+}
+export type PlacementAudienceEntryDTO = PlacementFlowAudienceEntryDTO | PlacementPaywallAudienceEntryDTO;
 export interface PlacementSummaryDTO {
     developer_id: string;
     id: string;

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

@@ -1,5 +1,5 @@
 import type { QueryParams } from './api-client.js';
-import type { AsaMoney, AsaMutationError } from './asa-schemas.js';
+import type { AsaLocInvoiceDetails, AsaMoney, AsaMutationError } from './asa-schemas.js';
 export declare const MAX_BULK_ITEMS = 100;
 export declare const MAX_BY_DAYS = 16;
 export declare const ASA_METRIC_ENTITIES: string[];
@@ -79,6 +79,27 @@ export declare const idempotencyFlags: {
     'idempotency-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
 };
 export declare function money(amount: string | undefined, currency: string): AsaMoney | undefined;
+declare const INVOICE_FIELDS: {
+    readonly 'invoice-advertiser': "client_name";
+    readonly 'invoice-billing-email': "billing_contact_email";
+    readonly 'invoice-contact-email': "buyer_email";
+    readonly 'invoice-contact-name': "buyer_name";
+    readonly 'invoice-order-number': "order_number";
+};
+type InvoiceFlagName = keyof typeof INVOICE_FIELDS;
+export declare const invoiceFlags: {
+    'invoice-advertiser': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'invoice-billing-email': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'invoice-contact-email': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'invoice-contact-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'invoice-order-number': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare function locInvoiceDetails(flags: Partial<Record<InvoiceFlagName, string>>): Record<keyof AsaLocInvoiceDetails, string> | undefined;
+export declare function reportServingState(campaign: null | {
+    internal_id: string;
+    serving_state_reasons?: null | string[];
+    serving_status?: null | string;
+}, warn: (msg: string) => void): void;
 interface BulkOutcome {
     applied: unknown[];
     errors: AsaMutationError[];