adapty 0.9.3 → 0.9.5

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 {};

package/dist/lib/asa-flags.js

@@ -247,3 +247,72 @@ export function reportBulkOutcome({ applied, errors, isValidationFailure, kind }
         log(`  ${describeListedError(error).text}`);
     }
 }
+export const asaSegmentSourceFlags = {
+    'ad-group': idFilter('ad group'),
+    'campaign': idFilter('campaign'),
+    'keyword': idFilter('keyword'),
+};
+export function resolveAsaSegmentSource(flags) {
+    const keywords = flags.keyword ?? [];
+    const adGroups = flags['ad-group'] ?? [];
+    const campaigns = flags.campaign ?? [];
+    if (keywords.length > 0) {
+        const [scopeAdGroup] = adGroups;
+        if (campaigns.length > 0 || adGroups.length !== 1 || scopeAdGroup === undefined) {
+            throw new Error('--keyword takes exactly one --ad-group as the lookup scope and no --campaign.');
+        }
+        return { ids: [...new Set(keywords)], scopeAdGroup, source: 'keyword' };
+    }
+    if (campaigns.length > 0 && adGroups.length > 0) {
+        throw new Error('Pass either --campaign or --ad-group, not both: a segment is built from one kind of entity.');
+    }
+    if (campaigns.length > 0) {
+        return { ids: [...new Set(campaigns)], scopeAdGroup: undefined, source: 'campaign' };
+    }
+    if (adGroups.length > 0) {
+        return { ids: [...new Set(adGroups)], scopeAdGroup: undefined, source: 'ad-group' };
+    }
+    throw new Error('Pass at least one --campaign, --ad-group or --keyword.');
+}
+export const ASA_SEGMENT_FIELD = {
+    'ad-group': 'ad_group',
+    'campaign': 'campaign',
+    // The portal calls a keyword attribution "creative"
+    'keyword': 'creative',
+};
+const ASA_TITLE_MAX = 120;
+const ASA_DESCRIPTION_MAX = 240;
+const ASA_PREVIEW_COUNT = 3;
+const ASA_SOURCE_WORDS = {
+    'ad-group': { many: 'ad groups', one: 'ad group', title: 'Ad group' },
+    'campaign': { many: 'campaigns', one: 'campaign', title: 'Campaign' },
+    'keyword': { many: 'keywords', one: 'keyword', title: 'Keyword' },
+};
+function truncate(text, max) {
+    if (text.length <= max) {
+        return text;
+    }
+    return max <= 3 ? text.slice(0, max) : `${text.slice(0, max - 3)}...`;
+}
+function withRest(preview, rest) {
+    return rest > 0 ? `${preview} +${rest}...` : preview;
+}
+/** The dashboard's own title and description for an Ads Manager segment, so it recognises the segment as its own. */
+export function buildAsaSegmentNaming(source, entities) {
+    const words = ASA_SOURCE_WORDS[source];
+    if (entities.length === 1) {
+        const [entity] = entities;
+        return {
+            description: truncate(`Created from Apple Search Ads ${words.one} "${entity.name}".\n\nID: ${entity.id}`, ASA_DESCRIPTION_MAX),
+            title: truncate(`[ASA] ${words.title}: ${entity.name}`, ASA_TITLE_MAX),
+        };
+    }
+    const shown = entities.slice(0, ASA_PREVIEW_COUNT);
+    const rest = entities.length - shown.length;
+    const names = withRest(shown.map(entity => entity.name).join(', '), rest);
+    const ids = withRest(shown.map(entity => entity.id).join(', '), rest);
+    return {
+        description: truncate(`Created from Apple Search Ads ${words.many} (${entities.length}).\n\nPreview: ${names}\n\nIDs: ${ids}`, ASA_DESCRIPTION_MAX),
+        title: truncate(`[ASA] ${entities.length} ${words.many}: ${names}`, ASA_TITLE_MAX),
+    };
+}

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

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