adapty 0.8.6 → 0.8.7

package/README.md

@@ -185,6 +185,7 @@ Keywords are always applied as a batch, at most 100 per call, and a partial reje
 
 ```sh
 adapty asa keywords list
+adapty asa keywords recommend --adam-id 1668337467 --type brand|generic|competitor [--country US...]
 adapty asa keywords add --ad-group UUID --text "running shoes" --text "trail shoes" [--bid 1.20] [--match-type EXACT]
 adapty asa keywords add --ad-group UUID --from-file keywords.txt
 adapty asa keywords update KEYWORD_ID [KEYWORD_ID...] [--bid 2.00] [--status PAUSED]

package/dist/commands/asa/keywords/recommend.d.ts

@@ -0,0 +1,20 @@
+import { Command } from '@oclif/core';
+import type { AsaBrandKeywordPoolDTO, AsaCompetitorBrandKeywordPoolsDTO, AsaGenericKeywordPoolDTO } from '../../../lib/asa-schemas.js';
+type PoolDTO = AsaBrandKeywordPoolDTO | AsaGenericKeywordPoolDTO;
+type RecommendationResult = AsaCompetitorBrandKeywordPoolsDTO | PoolDTO;
+export default class AsaKeywordsRecommend extends Command {
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'adam-id': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        country: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        type: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<RecommendationResult>;
+    private printCompetitorPools;
+    private printPool;
+    private omitAdamId;
+    private statusHint;
+}
+export {};

package/dist/commands/asa/keywords/recommend.js

@@ -0,0 +1,102 @@
+import { Command, Flags } from '@oclif/core';
+import { createAsaClient } from '../../../lib/asa-client.js';
+import { printList, printResponse } from '../../../lib/output.js';
+const TYPES = ['brand', 'generic', 'competitor'];
+const PATHS = {
+    brand: '/keyword-recommendations/brand',
+    competitor: '/keyword-recommendations/competitor-brand',
+    generic: '/keyword-recommendations/generic',
+};
+export default class AsaKeywordsRecommend extends Command {
+    static description = 'Keyword recommendations for one of your apps: its brand terms, generic terms, or the brand terms of its selected competitors';
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> asa keywords recommend --adam-id 1668337467 --type brand',
+        '<%= config.bin %> asa keywords recommend --adam-id 1668337467 --type generic --country US',
+        '<%= config.bin %> asa keywords recommend --adam-id 1668337467 --type competitor',
+    ];
+    static flags = {
+        'adam-id': Flags.integer({
+            description: 'Apple App Store ID (adam_id) of your app, from `asa apps list`',
+            required: true,
+        }),
+        'country': Flags.string({
+            description: 'ISO country code (e.g. US); repeatable, default every country in the pool',
+            multiple: true,
+        }),
+        'type': Flags.string({ description: 'Which pool to read', options: [...TYPES], required: true }),
+    };
+    async run() {
+        const { flags } = await this.parse(AsaKeywordsRecommend);
+        const countries = (flags.country ?? []).map(code => code.trim().toUpperCase());
+        if (countries.some(code => !/^[A-Z]{2}$/.test(code))) {
+            this.error('--country takes two-letter ISO codes, e.g. --country US.', { exit: 2 });
+        }
+        const type = flags.type;
+        const client = await createAsaClient(this);
+        const params = { adam_id: String(flags['adam-id']), country: countries.length > 0 ? countries : undefined };
+        if (type === 'competitor') {
+            const pools = await client.get(PATHS.competitor, params);
+            this.printCompetitorPools(pools);
+            return pools;
+        }
+        const pool = await client.get(PATHS[type], params);
+        this.printPool(pool, type);
+        return pool;
+    }
+    printCompetitorPools(result) {
+        if (result.pools.length === 0) {
+            this.log('No competitors selected for this app yet — select them in the Adapty dashboard (Autopilot setup).');
+            return;
+        }
+        for (const [i, pool] of result.pools.entries()) {
+            printResponse({
+                competitor_adam_id: pool.competitor_adam_id,
+                status: pool.status,
+                keywords_count: pool.keywords.length,
+            }, this.log.bind(this));
+            const hint = this.statusHint(pool.status);
+            if (hint !== undefined) {
+                this.log(hint);
+            }
+            if (pool.keywords.length > 0) {
+                this.log('');
+                printList(pool.keywords.map(keyword => this.omitAdamId(keyword)), this.log.bind(this));
+            }
+            if (i < result.pools.length - 1) {
+                this.log('===');
+            }
+        }
+    }
+    printPool(pool, type) {
+        const header = { status: pool.status, keywords_count: pool.keywords.length };
+        if (type === 'brand') {
+            header.brand_terms = pool.brand?.brand_terms ?? [];
+        }
+        printResponse(header, this.log.bind(this));
+        const hint = this.statusHint(pool.status);
+        if (hint !== undefined) {
+            this.log(hint);
+        }
+        if (pool.keywords.length > 0) {
+            this.log('');
+            const keywords = type === 'brand'
+                ? pool.keywords.map(keyword => this.omitAdamId(keyword))
+                : pool.keywords;
+            printList(keywords, this.log.bind(this));
+        }
+    }
+    omitAdamId(keyword) {
+        const { adam_id: _adamId, ...rest } = keyword;
+        return rest;
+    }
+    statusHint(status) {
+        if (status === 'building') {
+            return 'Still building — retry in about a minute.';
+        }
+        if (status === 'failed') {
+            return 'The pool build failed — retry later or contact support.';
+        }
+        return undefined;
+    }
+}

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

@@ -379,3 +379,43 @@ export type AsaBulkConvertResultDTO = {
     request: null | Record<string, unknown>;
     warnings: AsaTemplateIssueDTO[];
 };
+export type AsaKeywordPoolStatus = 'building' | 'empty' | 'failed' | 'missing' | 'ready';
+export type AsaBrandKeywordDTO = {
+    adam_id: number;
+    country: string;
+    median_organic_rank: null | number;
+    popularity: null | number;
+    score: null | number;
+    source: 'llm' | 'name' | 'organic';
+    text: string;
+};
+export type AsaAppBrandDTO = {
+    adam_id: number;
+    brand_terms: string[];
+    source: 'llm' | 'manual';
+};
+export type AsaBrandKeywordPoolDTO = {
+    brand: AsaAppBrandDTO | null;
+    keywords: AsaBrandKeywordDTO[];
+    status: AsaKeywordPoolStatus;
+};
+export type AsaGenericKeywordDTO = {
+    country: string;
+    median_organic_rank: null | number;
+    popularity: null | number;
+    relevance_tier: 'other' | 'top_organic';
+    score: null | number;
+    text: string;
+};
+export type AsaGenericKeywordPoolDTO = {
+    keywords: AsaGenericKeywordDTO[];
+    status: AsaKeywordPoolStatus;
+};
+export type AsaCompetitorBrandKeywordPoolDTO = {
+    competitor_adam_id: number;
+    keywords: AsaBrandKeywordDTO[];
+    status: AsaKeywordPoolStatus;
+};
+export type AsaCompetitorBrandKeywordPoolsDTO = {
+    pools: AsaCompetitorBrandKeywordPoolDTO[];
+};