adapty 0.9.3 → 0.9.5

package/README.md

@@ -90,6 +90,24 @@ adapty placements create --app UUID [flags]
 adapty placements update --app UUID PLACEMENT_ID [flags]
 ```
 
+### Segments
+
+```sh
+adapty segments list --app UUID [--page N] [--page-size N]
+adapty segments get --app UUID SEGMENT_ID                      # with filters, profile_count, refresh_in_progress
+adapty segments create --app UUID --title "US installs" --filter ip_country:IN:US --filter install_date:>=:2026-01-01
+adapty segments update --app UUID SEGMENT_ID --title "..." --filter campaign:IN:2144520245
+```
+
+A filter is `field:OPERATOR:value[,value...]`, or `field:IS NULL` / `field:IS NOT NULL` with no value. Operators:
+`IN`, `NOT IN`, `IS NULL`, `IS NOT NULL`, `>`, `>=`, `<`, `<=`, `BETWEEN`. Numeric fields (`age`,
+`total_revenue_usd`, `@float` custom attributes) take the plain number — `age:>:18` — the server converts it. For
+anything the short form cannot express pass one JSON object: `--filter '{"field_name":"age","operator":">","value_list":[18]}'`.
+The server validates field names, operators and value types and reports one error per field.
+`update` replaces the whole segment — pass every filter you want to keep. Segments
+built from Apple Search Ads entities are easier to create with `adapty asa segments create`, which resolves the
+Apple ids and names the segment the way the dashboard does (see [Apple Search Ads](#apple-search-ads)).
+
 ### Flows
 
 ```sh
@@ -299,6 +317,28 @@ adapty asa keywords list --ad-group AD_GROUP_UUID --ad-group OTHER_UUID   # repe
 adapty asa creatives list --app APP_UUID
 ```
 
+#### Segments from Apple Search Ads entities
+
+The Ads Manager "create segment" button, as commands. Each one builds an Adapty segment with a single
+attribution filter over the Apple ids of the chosen entities and names it `[ASA] Campaign: <name>` (or the ad
+group / keyword wording), so the dashboard recognises it as its own. These commands write through the Developer
+API, which is why they are the one place in the `asa` topic that takes `--app`: the Adapty app the segment
+belongs to, from `adapty apps list`.
+
+```sh
+adapty asa segments create --app APP_UUID --campaign CAMPAIGN_UUID
+adapty asa segments create --app APP_UUID --campaign UUID_1 --campaign UUID_2 --title "[ASA] Brand campaigns"
+adapty asa segments create --app APP_UUID --ad-group AD_GROUP_UUID
+adapty asa segments create --app APP_UUID --ad-group AD_GROUP_UUID --keyword KEYWORD_UUID --keyword OTHER_UUID
+adapty asa segments update SEGMENT_UUID --app APP_UUID --campaign CAMPAIGN_UUID     # keeps title and description
+adapty asa segments list --app APP_UUID [--campaign CAMPAIGN_UUID | --ad-group AD_GROUP_UUID]
+```
+
+One kind of entity per call. `--keyword` needs exactly one `--ad-group` to look the keywords up in. `list` shows
+the `[ASA]`-titled segments; with `--campaign` or `--ad-group` it keeps only those whose filter carries that
+entity, so a script can check for an existing segment before creating one. Any other filter shape goes through
+`adapty segments create`.
+
 `--campaign-group`, `--app`, `--campaign`, `--ad-group` are repeatable and take the UUIDs printed by the
 matching list command; `--search` matches names case-insensitively. Each list accepts only the filters that
 make sense for it: `--ad-group` starts at keywords, negative keywords, search terms and ads, `--status` is
@@ -365,8 +405,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/cli/input/segment.d.ts

@@ -0,0 +1,20 @@
+/** One filter of a segment body, as the developer API takes it. */
+export type SegmentFilterInput = {
+    field_name: string;
+    operator: string;
+    value_list: unknown[];
+};
+/**
+ * Values stay strings on the short form: the server turns them into numbers for numeric fields. The JSON form is
+ * for typed or nested values the short form cannot express.
+ */
+export declare function parseSegmentFilter(input: string): SegmentFilterInput;
+/** Spread into a write command: `static flags = { ...appIdFlag, ...segmentWriteFlags }`. */
+export declare const segmentWriteFlags: {
+    description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    filter: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+    title: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare function segmentFilters(flags: {
+    filter?: string[] | undefined;
+}): SegmentFilterInput[];

package/dist/cli/input/segment.js

@@ -0,0 +1,61 @@
+import { Flags } from '@oclif/core';
+import { usageError } from '../errors.js';
+const FILTER_USAGE = 'Filters are written as field:OPERATOR:value[,value...] (e.g. campaign:IN:2144520245), as field:IS NULL, '
+    + 'or as one JSON object {"field_name": ..., "operator": ..., "value_list": [...]}.';
+const EXISTENCE_OPERATORS = new Set(['IS NOT NULL', 'IS NULL']);
+function parseJsonSegmentFilter(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw usageError(`The filter is not valid JSON. ${FILTER_USAGE}`);
+    }
+    const { field_name: fieldName, operator, value_list: valueList } = (parsed ?? {});
+    if (typeof fieldName !== 'string' || typeof operator !== 'string' || !Array.isArray(valueList)) {
+        throw usageError(`A JSON filter needs field_name, operator and value_list. ${FILTER_USAGE}`);
+    }
+    return { field_name: fieldName, operator, value_list: valueList };
+}
+/**
+ * Values stay strings on the short form: the server turns them into numbers for numeric fields. The JSON form is
+ * for typed or nested values the short form cannot express.
+ */
+export function parseSegmentFilter(input) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith('{')) {
+        return parseJsonSegmentFilter(trimmed);
+    }
+    const [fieldName, rawOperator, ...rest] = trimmed.split(':');
+    const operator = rawOperator?.trim() ?? '';
+    if (!fieldName || !operator) {
+        throw usageError(FILTER_USAGE);
+    }
+    const valueList = rest.join(':').split(',').map(value => value.trim()).filter(value => value !== '');
+    if (EXISTENCE_OPERATORS.has(operator)) {
+        if (valueList.length > 0) {
+            throw usageError(`${operator} takes no values. ${FILTER_USAGE}`);
+        }
+        return { field_name: fieldName, operator, value_list: [] };
+    }
+    if (valueList.length === 0) {
+        throw usageError(`A filter needs at least one value. ${FILTER_USAGE}`);
+    }
+    return { field_name: fieldName, operator, value_list: valueList };
+}
+/** Spread into a write command: `static flags = { ...appIdFlag, ...segmentWriteFlags }`. */
+export const segmentWriteFlags = {
+    description: Flags.string({ description: 'Segment description' }),
+    filter: Flags.string({
+        description: 'Filter as field:OPERATOR:value[,value...] (e.g. campaign:IN:2144520245), field:IS NULL, or a JSON '
+            + 'object {"field_name","operator","value_list"}; repeatable',
+        multiple: true,
+        // oclif keeps a string flag a string: the parsed filter travels as JSON and segmentFilters unpacks it
+        parse: (input) => Promise.resolve(JSON.stringify(parseSegmentFilter(input))),
+        required: true,
+    }),
+    title: Flags.string({ description: 'Segment title', required: true }),
+};
+export function segmentFilters(flags) {
+    return (flags.filter ?? []).map(raw => JSON.parse(raw));
+}

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/commands/asa/segments/create.d.ts

@@ -0,0 +1,17 @@
+import { Command } from '@oclif/core';
+import type { SegmentDetailDTO } from '../../../lib/api-schemas.js';
+export default class AsaSegmentsCreate extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        title: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        '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>;
+        keyword: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        app: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<SegmentDetailDTO>;
+}

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

@@ -0,0 +1,53 @@
+import { Command, Flags } from '@oclif/core';
+import { appIdFlag } from '../../../cli/input/app.js';
+import { createAsaClient, fetchAsaSegmentEntities } from '../../../lib/asa-client.js';
+import { ASA_SEGMENT_FIELD, asaSegmentSourceFlags, buildAsaSegmentNaming, resolveAsaSegmentSource } from '../../../lib/asa-flags.js';
+import { createAuthenticatedClient } from '../../../lib/client-from-config.js';
+import { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaSegmentsCreate extends Command {
+    static description = `Create an Adapty segment from Apple Search Ads campaigns, ad groups or keywords
+
+Builds the same segment the Ads Manager "create segment" button does: one attribution filter over the Apple ids
+of the chosen entities, named "[ASA] Campaign: <name>" unless --title is passed. Pass one kind of entity per call;
+--keyword needs exactly one --ad-group to look the keywords up in. --app is the Adapty app the segment belongs to
+(see \`adapty apps list\`).`;
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa segments create --app APP_UUID --campaign CAMPAIGN_UUID',
+        '<%= config.bin %> asa segments create --app APP_UUID --campaign UUID_1 --campaign UUID_2 --title "[ASA] Brand campaigns"',
+        '<%= config.bin %> asa segments create --app APP_UUID --ad-group AD_GROUP_UUID --keyword KEYWORD_UUID',
+    ];
+    static flags = {
+        ...appIdFlag,
+        ...asaSegmentSourceFlags,
+        ...confirmFlags,
+        description: Flags.string({ description: 'Segment description; defaults to the dashboard wording' }),
+        title: Flags.string({ description: 'Segment title; defaults to the dashboard wording, e.g. "[ASA] Campaign: <name>"' }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaSegmentsCreate);
+        let selection;
+        try {
+            selection = resolveAsaSegmentSource(flags);
+        }
+        catch (error) {
+            this.error(error.message, { exit: 2 });
+        }
+        const asaClient = await createAsaClient(this);
+        const entities = await fetchAsaSegmentEntities(asaClient, selection);
+        const naming = buildAsaSegmentNaming(selection.source, entities);
+        const body = {
+            description: flags.description ?? naming.description,
+            filters: [{ field_name: ASA_SEGMENT_FIELD[selection.source], operator: 'IN', value_list: entities.map(entity => entity.id) }],
+            title: flags.title ?? naming.title,
+        };
+        const path = `/apps/${flags.app}/segments`;
+        await confirmMutation(this, { body, method: 'POST', path: `${path}/`, summary: `Create segment ${body.title}` }, flags.yes);
+        const client = await createAuthenticatedClient(this.config);
+        const result = await client.post(path, body);
+        this.log('Segment created!');
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

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

@@ -0,0 +1,16 @@
+import { Command } from '@oclif/core';
+import type { SegmentDTO } from '../../../lib/api-schemas.js';
+export default class AsaSegmentsList 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>;
+        app: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<SegmentDTO[]>;
+    /** The Apple id the segments must filter on, resolved from the ASA entity the user named. */
+    private wantedFilterValue;
+    private keepMatching;
+}

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

@@ -0,0 +1,59 @@
+import { Command, Flags } from '@oclif/core';
+import { appIdFlag } from '../../../cli/input/app.js';
+import { createAsaClient, fetchAsaSegmentEntities } from '../../../lib/asa-client.js';
+import { ASA_SEGMENT_FIELD, resolveAsaSegmentSource } from '../../../lib/asa-flags.js';
+import { createAuthenticatedClient } from '../../../lib/client-from-config.js';
+import { isValidUuid } from '../../../lib/flags.js';
+import { printList } from '../../../lib/output.js';
+const ASA_TITLE_PREFIX = '[ASA]';
+const parseId = (input) => (isValidUuid(input)
+    ? Promise.resolve(input)
+    : Promise.reject(new Error('Ids are the UUIDs printed by the matching list command.')));
+export default class AsaSegmentsList extends Command {
+    static description = `List the segments created from Apple Search Ads entities
+
+Segments whose title starts with "[ASA]", the dashboard's own marker. With --campaign or --ad-group only the
+segments whose filter carries that entity's Apple id are kept, so a script can tell whether a campaign already
+has its segment before creating one.`;
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa segments list --app APP_UUID',
+        '<%= config.bin %> asa segments list --app APP_UUID --campaign CAMPAIGN_UUID',
+    ];
+    static flags = {
+        ...appIdFlag,
+        'ad-group': Flags.string({ description: 'Keep only segments built from this ad group (UUID)', parse: parseId }),
+        'campaign': Flags.string({ description: 'Keep only segments built from this campaign (UUID)', parse: parseId }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaSegmentsList);
+        const wanted = await this.wantedFilterValue(flags);
+        const client = await createAuthenticatedClient(this.config);
+        const page = await client.get(`/apps/${flags.app}/segments`, { 'page[size]': '100' });
+        const asaSegments = page.data.filter(segment => segment.title.startsWith(ASA_TITLE_PREFIX));
+        const result = wanted === undefined
+            ? asaSegments
+            : await this.keepMatching(client, flags.app, asaSegments, wanted);
+        printList(result, this.log.bind(this));
+        return result;
+    }
+    /** The Apple id the segments must filter on, resolved from the ASA entity the user named. */
+    async wantedFilterValue(flags) {
+        if (flags.campaign === undefined && flags['ad-group'] === undefined) {
+            return undefined;
+        }
+        if (flags.campaign !== undefined && flags['ad-group'] !== undefined) {
+            this.error('Pass either --campaign or --ad-group, not both.', { exit: 2 });
+        }
+        const selection = resolveAsaSegmentSource({
+            'ad-group': flags['ad-group'] === undefined ? undefined : [flags['ad-group']],
+            'campaign': flags.campaign === undefined ? undefined : [flags.campaign],
+        });
+        const [entity] = await fetchAsaSegmentEntities(await createAsaClient(this), selection);
+        return { field: ASA_SEGMENT_FIELD[selection.source], value: entity?.id };
+    }
+    async keepMatching(client, app, segments, wanted) {
+        const details = await Promise.all(segments.map(segment => client.get(`/apps/${app}/segments/${segment.id}`)));
+        return details.filter(detail => detail.filters.some(filter => filter.field_name === wanted.field && filter.value_list.map(String).includes(wanted.value ?? '')));
+    }
+}

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

@@ -0,0 +1,20 @@
+import { Command } from '@oclif/core';
+import type { SegmentDetailDTO } from '../../../lib/api-schemas.js';
+export default class AsaSegmentsUpdate extends Command {
+    static args: {
+        segment_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        title: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        '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>;
+        keyword: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        app: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<SegmentDetailDTO>;
+}

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

@@ -0,0 +1,60 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { appIdFlag } from '../../../cli/input/app.js';
+import { createAsaClient, fetchAsaSegmentEntities } from '../../../lib/asa-client.js';
+import { ASA_SEGMENT_FIELD, asaSegmentSourceFlags, resolveAsaSegmentSource } from '../../../lib/asa-flags.js';
+import { createAuthenticatedClient } from '../../../lib/client-from-config.js';
+import { confirmFlags, confirmMutation } from '../../../lib/confirm.js';
+import { isValidUuid } from '../../../lib/flags.js';
+import { printResponse } from '../../../lib/output.js';
+export default class AsaSegmentsUpdate extends Command {
+    static args = {
+        segment_id: Args.string({ description: 'Segment ID (UUID)', required: true }),
+    };
+    static description = `Point an existing segment at other Apple Search Ads campaigns, ad groups or keywords
+
+Replaces the segment's filter with one attribution filter over the chosen entities, as the dashboard does.
+Title and description stay as stored unless --title / --description are passed.`;
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa segments update SEGMENT_UUID --app APP_UUID --campaign CAMPAIGN_UUID --campaign OTHER_UUID',
+        '<%= config.bin %> asa segments update SEGMENT_UUID --app APP_UUID --ad-group AD_GROUP_UUID --keyword KEYWORD_UUID --title "Top keywords"',
+    ];
+    static flags = {
+        ...appIdFlag,
+        ...asaSegmentSourceFlags,
+        ...confirmFlags,
+        description: Flags.string({ description: 'New description; omit to keep the stored one' }),
+        title: Flags.string({ description: 'New title; omit to keep the stored one' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(AsaSegmentsUpdate);
+        if (!isValidUuid(args.segment_id)) {
+            this.error('Invalid segment ID format.', { exit: 2 });
+        }
+        let selection;
+        try {
+            selection = resolveAsaSegmentSource(flags);
+        }
+        catch (error) {
+            this.error(error.message, { exit: 2 });
+        }
+        const asaClient = await createAsaClient(this);
+        const entities = await fetchAsaSegmentEntities(asaClient, selection);
+        const client = await createAuthenticatedClient(this.config);
+        const path = `/apps/${flags.app}/segments/${args.segment_id}`;
+        // PUT replaces the whole segment, so the stored title and description are read back unless overridden
+        const overridesBoth = flags.title !== undefined && flags.description !== undefined;
+        const stored = overridesBoth ? undefined : await client.get(path);
+        const body = {
+            description: flags.description ?? stored?.description ?? undefined,
+            filters: [{ field_name: ASA_SEGMENT_FIELD[selection.source], operator: 'IN', value_list: entities.map(entity => entity.id) }],
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- stored is read whenever title is missing
+            title: flags.title ?? stored.title,
+        };
+        await confirmMutation(this, { body, method: 'PUT', path: `${path}/`, summary: `Replace filters of segment ${args.segment_id}` }, flags.yes);
+        const result = await client.put(path, body);
+        this.log('Segment updated!');
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

package/dist/commands/segments/create.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+import type { SegmentDetailDTO } from '../../lib/api-schemas.js';
+export default class SegmentsCreate extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        filter: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        title: 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<SegmentDetailDTO>;
+}

package/dist/commands/segments/create.js

@@ -0,0 +1,30 @@
+import { Command } from '@oclif/core';
+import { appIdFlag } from '../../cli/input/app.js';
+import { segmentFilters, segmentWriteFlags } from '../../cli/input/segment.js';
+import { createAuthenticatedClient } from '../../lib/client-from-config.js';
+import { printResponse } from '../../lib/output.js';
+export default class SegmentsCreate extends Command {
+    static description = `Create a segment from filters over profile fields
+
+Filters are written as field:OPERATOR:value[,value...] and validated by the server. Apple Search Ads
+attribution uses campaign, ad_group and creative (a keyword) with Apple ids as values; build those from
+ASA entities with \`asa segments create\` instead of copying ids by hand.`;
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> segments create --app UUID --title "[ASA] Campaign: Brand" --filter campaign:IN:2144520245',
+        '<%= config.bin %> segments create --app UUID --title "US installs" --filter ip_country:IN:US --filter install_date:>=:2026-01-01',
+    ];
+    static flags = { ...appIdFlag, ...segmentWriteFlags };
+    async run() {
+        const { flags } = await this.parse(SegmentsCreate);
+        const body = {
+            description: flags.description,
+            filters: segmentFilters(flags),
+            title: flags.title,
+        };
+        const client = await createAuthenticatedClient(this.config);
+        const result = await client.post(`/apps/${flags.app}/segments`, body);
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

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

@@ -0,0 +1,17 @@
+import { Command } from '@oclif/core';
+import type { SegmentDetailDTO } from '../../lib/api-schemas.js';
+export default class SegmentsUpdate extends Command {
+    static args: {
+        segment_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        filter: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        title: 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<SegmentDetailDTO>;
+}