adapty 0.9.4 → 0.10.0

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
@@ -275,6 +293,21 @@ When several agents are found, the command asks which to install into; with no o
 `npx skills add adaptyteam/adapty-skills --all --global`, which covers the other agents. Restart an agent to
 load the skills. Exit **1** means an install failed.
 
+### Feedback
+
+A short report to Adapty on how a task with the CLI or an Adapty skill went. Leave out secrets and personal
+data. There is no `--app`: put app, flow or other ids into the message when they matter:
+
+```sh
+adapty feedback --sentiment positive --message "Imported the paywall from Canva in one pass"
+adapty feedback --sentiment negative --message "flows config update rejected a valid button twice" \
+  --feature flow-generator --context "editing the paywall screen"
+```
+
+`--sentiment` is `positive`, `neutral` or `negative`. `--feature` takes letters, digits, `.`, `_` and `-`;
+Adapty records `unknown` when it is left out. The CLI won't send a report containing something that looks like
+an API key, a bearer token, a JWT or an email address; it exits 2 and names the flag to fix.
+
 ### Apple Search Ads
 
 Apple Search Ads commands live under `adapty asa` and talk to the ASA service rather than the Developer
@@ -299,6 +332,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/bin/dev.js

@@ -1,5 +1,11 @@
 #!/usr/bin/env -S node --loader ts-node/esm --disable-warning=ExperimentalWarning
 
+import net from 'node:net';
+
 import { execute } from '@oclif/core';
 
+// Node abandons every address but the last after 250ms. On a slow link the working address is
+// dropped and the last one, e.g. IPv6 with no route, fails. Never lower a user-set value.
+net.setDefaultAutoSelectFamilyAttemptTimeout(Math.max(net.getDefaultAutoSelectFamilyAttemptTimeout(), 1000));
+
 await execute({ development: true, dir: import.meta.url });

package/bin/run.js

@@ -1,5 +1,11 @@
 #!/usr/bin/env node
 
+import net from 'node:net';
+
 import { execute } from '@oclif/core';
 
+// Node abandons every address but the last after 250ms. On a slow link the working address is
+// dropped and the last one, e.g. IPv6 with no route, fails. Never lower a user-set value.
+net.setDefaultAutoSelectFamilyAttemptTimeout(Math.max(net.getDefaultAutoSelectFamilyAttemptTimeout(), 1000));
+
 await execute({ dir: import.meta.url });

package/dist/cli/commands/feedback.d.ts

@@ -0,0 +1,16 @@
+import { AdaptyCommand } from '../base/adapty/index.js';
+type Result = {
+    status: 'sent';
+};
+export default class Feedback extends AdaptyCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        sentiment: import("@oclif/core/interfaces").OptionFlag<"positive" | "neutral" | "negative", import("@oclif/core/interfaces").CustomOptions>;
+        message: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        feature: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        context: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<Result>;
+}
+export {};

package/dist/cli/commands/feedback.js

@@ -0,0 +1,36 @@
+import { Flags } from '@oclif/core';
+import { validateSendFeedback } from '../../sdk/adapty/feedback/index.js';
+import { sentiments } from '../../sdk/adapty/index.js';
+import { assertValid } from '../../sdk/core/validation.js';
+import { AdaptyCommand } from '../base/adapty/index.js';
+export default class Feedback extends AdaptyCommand {
+    static description = [
+        'Send a short report on how a task with the Adapty CLI or an Adapty skill went.',
+        'Meant for AI agents: say what worked, what failed or confused you. Put app, flow and other ids into the message if they matter.',
+        'Leave out secrets and personal data.',
+    ].join('\n');
+    static examples = [
+        '<%= config.bin %> feedback --sentiment negative --feature flow-generator --message "flows config update rejected a valid button component twice"',
+        '<%= config.bin %> feedback --sentiment positive --message "Imported the paywall from Canva in one pass" --context "Building an onboarding flow from a Canva file"',
+    ];
+    static flags = {
+        sentiment: Flags.option({ description: 'How the task went', options: sentiments, required: true })(),
+        message: Flags.string({ description: 'The report: a few sentences on what happened', required: true }),
+        feature: Flags.string({ description: 'Feature or skill the report comes from; Adapty records "unknown" when omitted' }),
+        context: Flags.string({ description: 'What you were doing at that moment' }),
+    };
+    async run() {
+        const { flags } = await this.parse(Feedback);
+        const input = {
+            context: flags.context,
+            feature: flags.feature,
+            message: flags.message,
+            sentiment: flags.sentiment,
+        };
+        assertValid(validateSendFeedback(input));
+        await this.adapty.feedback.send(input);
+        const result = { status: 'sent' };
+        this.render(result, () => 'Feedback sent. Thank you!');
+        return result;
+    }
+}

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/feedback.d.ts

@@ -0,0 +1 @@
+export { default } from '../cli/commands/feedback.js';

package/dist/commands/feedback.js

@@ -0,0 +1 @@
+export { default } from '../cli/commands/feedback.js';

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[]>;