adapty 0.9.4 → 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

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

package/dist/commands/segments/update.js

@@ -0,0 +1,35 @@
+import { Args, 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 { isValidUuid } from '../../lib/flags.js';
+import { printResponse } from '../../lib/output.js';
+export default class SegmentsUpdate extends Command {
+    static args = {
+        segment_id: Args.string({ description: 'Segment ID (UUID)', required: true }),
+    };
+    static description = `Replace a segment's title, description and filters
+
+The server takes the whole segment, as the dashboard sends it: pass every filter you want to keep, not only
+the changed one. Read the current ones with \`segments get\`.`;
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> segments update --app UUID 550e8400-e29b-41d4-a716-446655440000 --title "[ASA] Campaign: Brand" --filter campaign:IN:2144520245',
+    ];
+    static flags = { ...appIdFlag, ...segmentWriteFlags };
+    async run() {
+        const { args, flags } = await this.parse(SegmentsUpdate);
+        if (!isValidUuid(args.segment_id)) {
+            this.error('Invalid segment ID format.', { exit: 2 });
+        }
+        const body = {
+            description: flags.description,
+            filters: segmentFilters(flags),
+            title: flags.title,
+        };
+        const client = await createAuthenticatedClient(this.config);
+        const result = await client.put(`/apps/${flags.app}/segments/${args.segment_id}`, body);
+        printResponse(result, this.log.bind(this));
+        return result;
+    }
+}

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

@@ -136,6 +136,30 @@ export type SegmentDTO = {
     id: string;
     title: string;
 };
+export type SegmentFilterDTO = {
+    field_name: string;
+    operator: string;
+    segment_filter_id: null | string;
+    value_list: unknown[];
+};
+/** What `segments get`, `create` and `update` return; the list stays `SegmentDTO`. */
+export type SegmentDetailDTO = SegmentDTO & {
+    created_at: string;
+    filters: SegmentFilterDTO[];
+    profile_count: number;
+    refresh_in_progress: boolean;
+    updated_at: string;
+};
+export type SegmentFilterInput = {
+    field_name: string;
+    operator: string;
+    value_list: unknown[];
+};
+export type SegmentWriteRequestDTO = {
+    description?: string | undefined;
+    filters: SegmentFilterInput[];
+    title: string;
+};
 export type PlacementPaywallAudienceEntryDTO = {
     content_type: 'paywall';
     paywall_id: string;

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

@@ -1,5 +1,6 @@
 import { ApiClient } from './api-client.js';
 import type { QueryParams } from './api-client.js';
+import type { AsaSegmentEntity, AsaSegmentSelection } from './asa-flags.js';
 import type { Config } from '@oclif/core';
 export declare const ASA_API_URL = "https://api-asa-admin.adapty.io/api/v1/cli";
 export declare const ASA_API_URL_ENV_VAR = "ADAPTY_ASA_API_URL";
@@ -19,3 +20,5 @@ export type AsaWriteOutcome<T> = {
 };
 export declare function asaWrite<T>(client: ApiClient, method: 'post' | 'put', path: string, opts?: AsaWriteOptions): Promise<AsaWriteOutcome<T>>;
 export declare function noteReplay(replayed: boolean, log: (msg: string) => void): void;
+/** The ASA entities behind a segment source, with the Apple ids the portal filters on. */
+export declare function fetchAsaSegmentEntities(client: ApiClient, selection: AsaSegmentSelection): Promise<AsaSegmentEntity[]>;

package/dist/lib/asa-client.js

@@ -49,3 +49,29 @@ export function noteReplay(replayed, log) {
         log('Already applied earlier — showing the stored result.');
     }
 }
+/** The ASA entities behind a segment source, with the Apple ids the portal filters on. */
+export async function fetchAsaSegmentEntities(client, selection) {
+    if (selection.source === 'campaign') {
+        const campaigns = await Promise.all(selection.ids.map(id => client.get(`/campaigns/${id}`)));
+        return campaigns.map(campaign => ({ id: String(campaign.campaign_id), name: campaign.name }));
+    }
+    if (selection.source === 'ad-group') {
+        const adGroups = await Promise.all(selection.ids.map(id => client.get(`/ad-groups/${id}`)));
+        return adGroups.map(adGroup => ({ id: String(adGroup.ad_group_id), name: adGroup.name }));
+    }
+    // No single-keyword read exists; the ad group is small, so one scoped page covers the lookup
+    const page = await client.get('/keywords', {
+        'ad_group_id': selection.scopeAdGroup,
+        'page[size]': '1000',
+    });
+    const byId = new Map(page.data.map(keyword => [keyword.internal_id, keyword]));
+    const missing = selection.ids.filter(id => !byId.has(id));
+    if (missing.length > 0) {
+        throw new Error(`Keyword(s) not found in ad group ${selection.scopeAdGroup}: ${missing.join(', ')}`);
+    }
+    return selection.ids.map((id) => {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- membership checked above
+        const keyword = byId.get(id);
+        return { id: String(keyword.keyword_id), name: keyword.text };
+    });
+}

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

@@ -131,4 +131,35 @@ type BulkOutcome = {
     kind: string;
 };
 export declare function reportBulkOutcome({ applied, errors, isValidationFailure, kind }: BulkOutcome, log: (msg: string) => void): void;
+export type AsaSegmentSource = 'ad-group' | 'campaign' | 'keyword';
+export declare const asaSegmentSourceFlags: {
+    '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>;
+};
+export type AsaSegmentSourceFlags = {
+    'ad-group'?: string[] | undefined;
+    'campaign'?: string[] | undefined;
+    'keyword'?: string[] | undefined;
+};
+/**
+ * One source kind per segment, as in the Ads Manager modal. Keywords are looked up inside one ad group, so
+ * `--keyword` borrows `--ad-group` as its scope instead of competing with it.
+ */
+export type AsaSegmentSelection = {
+    ids: string[];
+    scopeAdGroup: string | undefined;
+    source: AsaSegmentSource;
+};
+export declare function resolveAsaSegmentSource(flags: AsaSegmentSourceFlags): AsaSegmentSelection;
+export declare const ASA_SEGMENT_FIELD: Record<AsaSegmentSource, string>;
+export type AsaSegmentEntity = {
+    id: string;
+    name: string;
+};
+/** The dashboard's own title and description for an Ads Manager segment, so it recognises the segment as its own. */
+export declare function buildAsaSegmentNaming(source: AsaSegmentSource, entities: AsaSegmentEntity[]): {
+    description: string;
+    title: string;
+};
 export {};