adapty 0.8.1 → 0.8.2

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

@@ -5,11 +5,12 @@ import { currencyFlag, idempotencyFlags, money, moneyFlag, pricingModelFlag, sch
 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/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 { 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 { 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/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[];

package/dist/lib/asa-flags.js

@@ -124,6 +124,53 @@ export const idempotencyFlags = {
 export function money(amount, currency) {
     return amount === undefined ? undefined : { amount, currency };
 }
+const INVOICE_FIELDS = {
+    'invoice-advertiser': 'client_name',
+    'invoice-billing-email': 'billing_contact_email',
+    'invoice-contact-email': 'buyer_email',
+    'invoice-contact-name': 'buyer_name',
+    'invoice-order-number': 'order_number',
+};
+const INVOICE_PREFIX = 'Invoicing Options (line-of-credit orgs, see payment_model in asa orgs list)';
+function invoiceFlag(what) {
+    return Flags.string({ description: `${INVOICE_PREFIX}: ${what}` });
+}
+export const invoiceFlags = {
+    'invoice-advertiser': invoiceFlag('advertiser name'),
+    'invoice-billing-email': invoiceFlag('billing contact email'),
+    'invoice-contact-email': invoiceFlag('buyer contact email'),
+    'invoice-contact-name': invoiceFlag('buyer contact name'),
+    'invoice-order-number': invoiceFlag('order number'),
+};
+export function locInvoiceDetails(flags) {
+    const names = Object.keys(INVOICE_FIELDS);
+    const missing = names.filter((name) => flags[name] === undefined);
+    if (missing.length === names.length)
+        return undefined;
+    if (missing.length > 0) {
+        throw new Error(`Invoicing Options need all five flags; missing: ${missing.map((name) => `--${name}`).join(', ')}`);
+    }
+    return Object.fromEntries(names.map((name) => [INVOICE_FIELDS[name], flags[name]]));
+}
+const SERVING_HINTS = {
+    AUTOMATED_KEYWORDS_REQUIRED_AD_GROUP_MISSING: (campaignId) => `Max Conversions campaign needs an automated ad group: adapty asa ad-groups create --campaign ${campaignId} --name "Automated Max Conv" --automated`,
+    MISSING_BO_OR_INVOICING_FIELDS: (campaignId) => `This organization bills by line of credit — add Invoicing Options: adapty asa campaigns update ${campaignId} --invoice-advertiser ... --invoice-order-number ... --invoice-contact-name ... --invoice-contact-email ... --invoice-billing-email ...`,
+};
+export function reportServingState(campaign, warn) {
+    if (campaign?.serving_status !== 'NOT_RUNNING' || !campaign.serving_state_reasons?.length)
+        return;
+    const reasons = campaign.serving_state_reasons;
+    if (reasons.length === 1 && reasons[0] === 'PAUSED_BY_USER')
+        return;
+    for (const reason of reasons) {
+        const hint = SERVING_HINTS[reason];
+        if (hint)
+            warn(hint(campaign.internal_id));
+    }
+    const other = reasons.filter((reason) => !SERVING_HINTS[reason]);
+    if (other.length > 0)
+        warn(`Not serving: ${other.join(', ')}`);
+}
 export function reportBulkOutcome({ applied, errors, isValidationFailure, kind }, log) {
     if (isValidationFailure) {
         log(`Nothing was applied: the batch failed validation before Apple was called.`);

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

@@ -48,6 +48,13 @@ export interface AsaAppDTO {
     last_synced_at: string;
     name: string;
 }
+export interface AsaLocInvoiceDetails {
+    billing_contact_email: null | string;
+    buyer_email: null | string;
+    buyer_name: null | string;
+    client_name: null | string;
+    order_number: null | string;
+}
 export interface AsaCampaignGroupDTO {
     currency: string;
     internal_id: string;
@@ -55,6 +62,7 @@ export interface AsaCampaignGroupDTO {
     org_id: number;
     org_name: string;
     parent_org_id: number;
+    payment_model: null | string;
     time_zone: string;
 }
 export interface AsaCampaignDTO {
@@ -70,8 +78,12 @@ export interface AsaCampaignDTO {
     daily_budget_amount: AsaMoney | null;
     end_time: null | string;
     internal_id: string;
+    loc_invoice_details: AsaLocInvoiceDetails | null;
     name: string;
     org_id: number;
+    payment_model: null | string;
+    serving_state_reasons: null | string[];
+    serving_status: null | string;
     start_time: null | string;
     status: AsaStatus;
     supply_sources: string[];
@@ -81,6 +93,7 @@ export interface AsaAdGroupDTO {
     ad_group_id: number;
     app_id: string;
     automated_keywords_opt_in: boolean | null;
+    automated_keywords_required: boolean | null;
     bidding_strategy: null | string;
     campaign_group_id: string;
     campaign_id: string;
@@ -91,6 +104,8 @@ export interface AsaAdGroupDTO {
     name: string;
     payment_model: null | string;
     pricing_model: null | string;
+    serving_state_reasons: null | string[];
+    serving_status: null | string;
     start_time: null | string;
     status: AsaStatus | null;
     target_cpa: AsaMoney | null;
@@ -261,7 +276,11 @@ export interface AsaCampaignMutationEntity {
     campaign_group_id: string;
     campaign_id: number;
     internal_id: string;
+    loc_invoice_details: AsaLocInvoiceDetails | null;
     name: string;
+    payment_model: null | string;
+    serving_state_reasons: null | string[];
+    serving_status: null | string;
     status: AsaStatus;
 }
 export interface AsaAdGroupMutationDTO {