adapty 0.9.3 → 0.9.4

package/README.md

@@ -365,8 +365,14 @@ adapty asa negative-keywords add --ad-group UUID --text free
 adapty asa negative-keywords add --campaign UUID [--all-ad-groups] --text free
 
 adapty asa search-terms list [--date-from ... --date-to ...]
+
+adapty asa change-history list --campaign-group UUID [--date-from ... --date-to ...] [--entity-type Campaign --event-type UPDATE]
+adapty asa change-history list --campaign-group UUID --fields                    # flat rows: field, old values, new values (page size 10)
+adapty asa change-history get Campaign.444555666.TXN_ID --campaign-group UUID   # detail_id comes from the list
 ```
 
+Change history is read live from Apple (proxied from the Apple Ads Platform API; Apple keeps 6 months). Its id filters (`--campaign`, `--ad-group`, `--entity-id`, `--user`, `--txn`) take Apple's own ids, not UUIDs; `modified_by` is an Apple user id, not an email.
+
 Product pages and rule-based automations:
 
 ```sh

package/dist/commands/asa/change-history/get.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+import type { AsaChangeHistoryDetailDTO } from '../../../lib/asa-schemas.js';
+export default class AsaChangeHistoryGet extends Command {
+    static args: {
+        detail_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'campaign-group': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<AsaChangeHistoryDetailDTO>;
+}

package/dist/commands/asa/change-history/get.js

@@ -0,0 +1,39 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { createAsaClient } from '../../../lib/asa-client.js';
+import { isValidUuid } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+const DETAIL_ID_REGEX = /^[A-Za-z]+\.[\w-]+\.[\w-]+$/;
+export default class AsaChangeHistoryGet extends Command {
+    static args = {
+        detail_id: Args.string({
+            description: 'Detail ID from asa change-history list (EntityType.entityId.txnId)',
+            required: true,
+        }),
+    };
+    static description = 'Field-level before/after of one change (proxied from the Apple Ads Platform API)';
+    static enableJsonFlag = true;
+    static examples = ['<%= config.bin %> asa change-history get Campaign.444555666.TXN_ID --campaign-group <uuid>'];
+    static flags = {
+        'campaign-group': Flags.string({
+            description: 'Organization the change belongs to (UUID; take campaign_group_id from the list row)',
+            required: true,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(AsaChangeHistoryGet);
+        if (!DETAIL_ID_REGEX.test(args.detail_id)) {
+            this.error('Invalid detail ID format. Take it from `adapty asa change-history list` (EntityType.entityId.txnId).', {
+                exit: 2,
+            });
+        }
+        if (!isValidUuid(flags['campaign-group'])) {
+            this.error('Invalid campaign group ID format. Run `adapty asa orgs list` to find it.', { exit: 2 });
+        }
+        const client = await createAsaClient(this);
+        const result = await client.get(`/change-history/${args.detail_id}`, {
+            campaign_group_id: flags['campaign-group'],
+        });
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/asa/change-history/list.d.ts

@@ -0,0 +1,27 @@
+import { Command } from '@oclif/core';
+import type { AsaChangeHistoryEventDTO, AsaChangeHistoryFieldEventDTO } from '../../../lib/asa-schemas.js';
+import type { PaginatedResponse } from '../../../lib/flags.js';
+type ChangeHistoryPage = PaginatedResponse<AsaChangeHistoryEventDTO> | PaginatedResponse<AsaChangeHistoryFieldEventDTO>;
+export default class AsaChangeHistoryList 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>;
+        campaign: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'campaign-group': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'date-from': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'date-to': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'entity-id': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'entity-type': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'event-type': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        fields: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        txn: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        user: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'user-type': 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<ChangeHistoryPage>;
+}
+export {};

package/dist/commands/asa/change-history/list.js

@@ -0,0 +1,102 @@
+import { Command, Flags } from '@oclif/core';
+import { createAsaClient } from '../../../lib/asa-client.js';
+import { asaPaginationFlags, parseDate, periodParams } from '../../../lib/asa-flags.js';
+import { isValidUuid, paginationParams } from '../../../lib/flags.js';
+import { printList } from '../../../lib/output.js';
+const FIELDS_MAX_PAGE_SIZE = 10;
+const MAX_SPAN_DAYS = 14;
+const MS_PER_DAY = 86_400_000;
+export default class AsaChangeHistoryList extends Command {
+    static description = 'Apple Ads change history of one organization, read live from Apple (proxied from the Apple Ads Platform API)';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa change-history list --campaign-group <uuid>',
+        '<%= config.bin %> asa change-history list --campaign-group <uuid> --date-from 2026-09-01 --entity-type Campaign --event-type UPDATE',
+        '<%= config.bin %> asa change-history list --campaign-group <uuid> --fields',
+    ];
+    static flags = {
+        ...asaPaginationFlags,
+        'ad-group': Flags.string({
+            description: 'Keep only changes inside these Apple ad group ids (not UUIDs); repeatable',
+            multiple: true,
+        }),
+        'campaign': Flags.string({
+            description: 'Keep only changes inside these Apple campaign ids (not UUIDs); repeatable',
+            multiple: true,
+        }),
+        'campaign-group': Flags.string({
+            description: 'Organization to read (UUID from asa orgs list); one organization per call',
+            required: true,
+        }),
+        'date-from': Flags.string({
+            description: 'Start of the period (YYYY-MM-DD), defaults to 7 days ago; at most 14 days per call, Apple keeps 6 months',
+            parse: parseDate,
+        }),
+        'date-to': Flags.string({
+            description: 'End of the period (YYYY-MM-DD), defaults to today',
+            parse: parseDate,
+        }),
+        'entity-id': Flags.string({
+            description: 'Keep only changes of these Apple entity ids (not UUIDs); repeatable',
+            multiple: true,
+        }),
+        'entity-type': Flags.string({
+            description: 'Keep only changes of this entity type; repeatable. Default is the campaign domain (Campaign, AdGroup, Keyword, NegativeKeyword, Ad, Creative, LocationGroup); Org and AdAccount cannot be mixed with it',
+            multiple: true,
+            options: ['Ad', 'AdAccount', 'AdGroup', 'Campaign', 'Creative', 'Keyword', 'LocationGroup', 'NegativeKeyword', 'Org'],
+        }),
+        'event-type': Flags.string({
+            description: 'Keep only this operation; repeatable',
+            multiple: true,
+            options: ['CREATE', 'DELETE', 'UPDATE'],
+        }),
+        'fields': Flags.boolean({
+            description: `Expand into flat field-level rows (field, old values, new values); page size defaults to ${FIELDS_MAX_PAGE_SIZE} and may not exceed it`,
+        }),
+        'txn': Flags.string({ description: 'Keep only these Apple transaction ids; repeatable', multiple: true }),
+        'user': Flags.string({
+            description: 'Keep only changes made by these Apple user ids (not emails); repeatable',
+            multiple: true,
+        }),
+        'user-type': Flags.string({
+            description: 'Keep only changes by this actor category; repeatable',
+            multiple: true,
+            options: ['APPLE_SUPPORT', 'CUSTOMER', 'CUSTOMER_API'],
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaChangeHistoryList);
+        const isPageSizeGiven = this.argv.some(arg => arg === '--page-size' || arg.startsWith('--page-size='));
+        if (flags.fields && isPageSizeGiven && flags['page-size'] > FIELDS_MAX_PAGE_SIZE) {
+            this.error(`--fields allows --page-size up to ${FIELDS_MAX_PAGE_SIZE}.`, { exit: 2 });
+        }
+        if (!isValidUuid(flags['campaign-group'])) {
+            this.error('Invalid campaign group ID format. Run `adapty asa orgs list` to find it.', { exit: 2 });
+        }
+        const dateFrom = flags['date-from'];
+        const dateTo = flags['date-to'];
+        if (dateFrom !== undefined
+            && dateTo !== undefined
+            && (Date.parse(dateTo) - Date.parse(dateFrom)) / MS_PER_DAY >= MAX_SPAN_DAYS) {
+            this.error(`--date-from/--date-to may span at most ${MAX_SPAN_DAYS} days.`, { exit: 2 });
+        }
+        const client = await createAsaClient(this);
+        const result = await client.get('/change-history', {
+            ...paginationParams(flags),
+            ...(flags.fields && !isPageSizeGiven ? { 'page[size]': String(FIELDS_MAX_PAGE_SIZE) } : {}),
+            ...periodParams(flags),
+            ad_group_id: flags['ad-group'],
+            campaign_group_id: flags['campaign-group'],
+            campaign_id: flags.campaign,
+            entity_id: flags['entity-id'],
+            entity_type: flags['entity-type'],
+            event_type: flags['event-type'],
+            fields: flags.fields ? 'true' : undefined,
+            txn_id: flags.txn,
+            user_id: flags.user,
+            user_type: flags['user-type'],
+        });
+        printList(result.data, this.log.bind(this), result.meta.pagination);
+        return result;
+    }
+}

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

@@ -424,3 +424,50 @@ export type AsaCompetitorBrandKeywordPoolDTO = {
 export type AsaCompetitorBrandKeywordPoolsDTO = {
     pools: AsaCompetitorBrandKeywordPoolDTO[];
 };
+export type AsaChangeHistoryEntityRefDTO = {
+    detail_id: string;
+    entity_id: string;
+    entity_name: null | string;
+};
+export type AsaChangeHistoryEventDTO = {
+    campaign_group_id: string;
+    changes_count: number;
+    entities: AsaChangeHistoryEntityRefDTO[];
+    entity_type: string;
+    event_time: string;
+    event_type: string;
+    modified_by: null | string;
+    transaction_id: string;
+    user_type: string;
+};
+export type AsaFieldChangeDTO = {
+    field: string;
+    new_values: string[];
+    old_values: string[];
+};
+export type AsaChangeHistoryDetailDTO = {
+    campaign_group_id: string;
+    changes: AsaFieldChangeDTO[];
+    detail_id: string;
+    entity_id: string;
+    entity_metadata: Record<string, unknown>;
+    entity_type: string;
+    event_time: string;
+    event_type: string;
+    modified_by: null | string;
+    user_type: string;
+};
+export type AsaChangeHistoryFieldEventDTO = {
+    campaign_group_id: string;
+    entity_id: string;
+    entity_name: null | string;
+    entity_type: string;
+    event_time: string;
+    event_type: string;
+    field: string;
+    modified_by: null | string;
+    new_values: string[];
+    old_values: string[];
+    transaction_id: string;
+    user_type: string;
+};