adapty 0.3.0 → 0.5.0

package/dist/lib/api-client.js

@@ -1,51 +1,75 @@
 import { ApiError, NetworkError, parseApiError } from './errors.js';
 const DEFAULT_API_URL = 'https://api-admin.adapty.io/api/v1/developer';
+const MAX_RETRY_AFTER_SECONDS = 60;
 function ensureTrailingSlash(path) {
     return path.endsWith('/') ? path : `${path}/`;
 }
 export class ApiClient {
     baseUrl;
+    errorFormat;
     token;
     userAgent;
     constructor(opts = {}) {
-        this.baseUrl = (opts.baseUrl ?? process.env.ADAPTY_API_URL ?? DEFAULT_API_URL).replace(/\/$/, '');
-        if (this.baseUrl !== DEFAULT_API_URL) {
+        const defaultBaseUrl = opts.defaultBaseUrl ?? DEFAULT_API_URL;
+        const envBaseUrl = process.env[opts.urlEnvVar ?? 'ADAPTY_API_URL'];
+        this.baseUrl = (opts.baseUrl ?? envBaseUrl ?? defaultBaseUrl).replace(/\/$/, '');
+        if (this.baseUrl !== defaultBaseUrl) {
             process.stderr.write(`Warning: using non-default API URL: ${this.baseUrl}\n`);
         }
+        this.errorFormat = opts.errorFormat ?? 'developer';
         this.token = opts.token ?? null;
         this.userAgent = opts.userAgent ?? 'adapty-cli';
     }
     async get(path, params) {
-        let url = `${this.baseUrl}${ensureTrailingSlash(path)}`;
-        if (params) {
-            const qs = new URLSearchParams(params);
-            url += `?${qs.toString()}`;
-        }
-        return this.request(url, { method: 'GET' });
+        return this.request(this.buildUrl(path, params), { method: 'GET' });
     }
-    async post(path, body) {
-        return this.request(`${this.baseUrl}${ensureTrailingSlash(path)}`, {
+    async post(path, body, params, opts) {
+        return this.request(this.buildUrl(path, params), {
             body: body ? JSON.stringify(body) : undefined,
             method: 'POST',
-        });
+        }, opts);
+    }
+    async postForm(path, form, params, opts) {
+        return this.request(this.buildUrl(path, params), { body: form, method: 'POST' }, opts);
     }
-    async put(path, body) {
-        return this.request(`${this.baseUrl}${ensureTrailingSlash(path)}`, {
+    async put(path, body, params, opts) {
+        return this.request(this.buildUrl(path, params), {
             body: body ? JSON.stringify(body) : undefined,
             method: 'PUT',
-        });
+        }, opts);
+    }
+    buildUrl(path, params) {
+        const url = `${this.baseUrl}${ensureTrailingSlash(path)}`;
+        if (!params)
+            return url;
+        const search = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (value === undefined)
+                continue;
+            for (const item of Array.isArray(value) ? value : [value])
+                search.append(key, item);
+        }
+        return search.size === 0 ? url : `${url}?${search.toString()}`;
+    }
+    isRetryableRateLimit(error) {
+        return (this.errorFormat === 'asa' &&
+            error.statusCode === 429 &&
+            error.errorCode !== 'cli_cooldown_active' &&
+            error.retryAfterSeconds !== undefined &&
+            error.retryAfterSeconds <= MAX_RETRY_AFTER_SECONDS);
     }
     // eslint-disable-next-line no-undef
-    async request(url, init) {
+    async request(url, init, opts = {}, retried = false) {
         const headers = {
             'User-Agent': this.userAgent,
         };
-        if (init.body) {
+        if (init.body && !(init.body instanceof FormData)) {
             headers['Content-Type'] = 'application/json';
         }
         if (this.token) {
             headers.Authorization = `Bearer ${this.token}`;
         }
+        Object.assign(headers, opts.headers);
         let response;
         try {
             response = await fetch(url, { ...init, headers });
@@ -53,24 +77,35 @@ export class ApiClient {
         catch (error) {
             throw new NetworkError(error instanceof Error ? error.message : 'Connection failed');
         }
+        opts.onResponse?.(response.headers);
         if (response.status === 204) {
             return undefined;
         }
+        const retryAfter = Number.parseInt(response.headers.get('Retry-After') ?? '', 10);
+        const errorOptions = this.errorFormat === 'asa' && !Number.isNaN(retryAfter) ? { retryAfterSeconds: retryAfter } : {};
         let body;
         try {
             body = await response.json();
         }
         catch {
             if (!response.ok) {
-                throw new ApiError(response.status, `http_${response.status}`, {});
+                throw new ApiError(response.status, `http_${response.status}`, {}, errorOptions);
             }
             return undefined;
         }
         if (!response.ok) {
-            const error = parseApiError(response.status, body);
+            const error = parseApiError(response.status, body, errorOptions, this.errorFormat);
             if (response.status === 401) {
                 error.message = 'Token expired or invalid. Run `adapty auth login`.';
             }
+            if (!retried && this.isRetryableRateLimit(error)) {
+                const seconds = error.retryAfterSeconds ?? 0;
+                process.stderr.write(`Rate limited (${error.errorCode}); waiting ${seconds}s per Retry-After, then retrying once.\n`);
+                await new Promise((resolve) => {
+                    setTimeout(resolve, seconds * 1000);
+                });
+                return this.request(url, init, opts, true);
+            }
             throw error;
         }
         return body;

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

@@ -0,0 +1,16 @@
+import type { Config } from '@oclif/core';
+import { ApiClient, type QueryParams } from './api-client.js';
+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";
+export declare function createAsaClient(config: Config): Promise<ApiClient>;
+export interface AsaWriteOptions {
+    body?: unknown;
+    idempotencyKey?: string;
+    params?: QueryParams;
+}
+export interface AsaWriteOutcome<T> {
+    replayed: boolean;
+    result: 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;

package/dist/lib/asa-client.js

@@ -0,0 +1,46 @@
+import { randomUUID } from 'node:crypto';
+import { ApiClient } from './api-client.js';
+import { resolveToken } from './auth.js';
+import { buildUserAgent } from './client-from-config.js';
+import { AuthRequiredError, NetworkError } from './errors.js';
+export const ASA_API_URL = 'https://api-asa-admin.adapty.io/api/v1/cli';
+export const ASA_API_URL_ENV_VAR = 'ADAPTY_ASA_API_URL';
+export async function createAsaClient(config) {
+    const token = await resolveToken(config.configDir);
+    if (!token)
+        throw new AuthRequiredError();
+    return new ApiClient({
+        defaultBaseUrl: ASA_API_URL,
+        errorFormat: 'asa',
+        token,
+        urlEnvVar: ASA_API_URL_ENV_VAR,
+        userAgent: buildUserAgent(config),
+    });
+}
+export async function asaWrite(client, method, path, opts = {}) {
+    const key = opts.idempotencyKey ?? randomUUID();
+    let replayed = false;
+    const requestOpts = {
+        headers: { 'Idempotency-Key': key },
+        onResponse(headers) {
+            replayed = headers.get('Idempotency-Replayed') === 'true';
+        },
+    };
+    const send = () => method === 'post'
+        ? client.post(path, opts.body, opts.params, requestOpts)
+        : client.put(path, opts.body, opts.params, requestOpts);
+    try {
+        const result = await send();
+        return { replayed, result };
+    }
+    catch (error) {
+        if (!(error instanceof NetworkError))
+            throw error;
+        const result = await send();
+        return { replayed, result };
+    }
+}
+export function noteReplay(replayed, log) {
+    if (replayed)
+        log('Already applied earlier — showing the stored result.');
+}

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

@@ -0,0 +1,18 @@
+import { Command } from '@oclif/core';
+export declare const confirmFlags: {
+    yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};
+export type ConfirmDecision = 'ask' | 'proceed' | 'refuse';
+export declare function decideConfirmation(opts: {
+    isTty: boolean;
+    json: boolean;
+    yes: boolean;
+}): ConfirmDecision;
+export interface MutationPreview {
+    body?: unknown;
+    method: string;
+    path: string;
+    summary: string;
+}
+export declare function renderPreview(preview: MutationPreview): string;
+export declare function confirmMutation(command: Command, preview: MutationPreview, yes: boolean): Promise<void>;

package/dist/lib/asa-confirm.js

@@ -0,0 +1,41 @@
+import { Flags } from '@oclif/core';
+import { createInterface } from 'node:readline/promises';
+export const confirmFlags = {
+    yes: Flags.boolean({
+        char: 'y',
+        description: 'Apply without asking; required when the output is piped or --json is used',
+    }),
+};
+export function decideConfirmation(opts) {
+    if (opts.yes)
+        return 'proceed';
+    if (opts.json || !opts.isTty)
+        return 'refuse';
+    return 'ask';
+}
+export function renderPreview(preview) {
+    const lines = [preview.summary, `${preview.method} ${preview.path}`];
+    if (preview.body !== undefined)
+        lines.push(JSON.stringify(preview.body, null, 2));
+    return lines.join('\n');
+}
+export async function confirmMutation(command, preview, yes) {
+    const decision = decideConfirmation({ isTty: process.stdin.isTTY === true, json: command.jsonEnabled(), yes });
+    if (decision === 'proceed')
+        return;
+    if (decision === 'refuse') {
+        const reason = `${preview.summary} changes your account. Re-run with --yes to apply it without a prompt.`;
+        process.stderr.write(`${reason}\n${renderPreview(preview)}\n`);
+        command.error(reason, { exit: 2 });
+    }
+    process.stderr.write(`${renderPreview(preview)}\n`);
+    const reader = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await reader.question('Apply? [y/N] ');
+        if (!/^y(es)?$/i.test(answer.trim()))
+            command.error('Cancelled, nothing was sent.', { exit: 1 });
+    }
+    finally {
+        reader.close();
+    }
+}

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

@@ -0,0 +1,88 @@
+import type { QueryParams } from './api-client.js';
+import type { AsaMoney, AsaMutationError } from './asa-schemas.js';
+export declare const MAX_BULK_ITEMS = 100;
+export declare const MAX_BY_DAYS = 16;
+export declare const ASA_METRIC_ENTITIES: string[];
+export declare const ASA_GROUP_BY_DIMENSIONS: string[];
+export declare const asaPaginationFlags: {
+    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>;
+};
+export declare const byDaysFlag: {
+    'by-days': import("@oclif/core/interfaces").OptionFlag<number[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare const periodFlags: {
+    '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>;
+};
+export declare const assetScopeFlags: {
+    app: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'campaign-group': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare const orgScopeFlags: {
+    search: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    app: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'campaign-group': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare const campaignScopeFlags: {
+    campaign: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    search: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    app: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'campaign-group': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare const adGroupScopeFlags: {
+    '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>;
+    search: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    app: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'campaign-group': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare const adScopeFlags: {
+    search: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    '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[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare const statusFilter: (options: string[]) => {
+    status: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
+interface ScopeFlags {
+    'ad-group'?: string[];
+    app?: string[];
+    campaign?: string[];
+    'campaign-group'?: string[];
+    search?: string;
+    status?: string;
+}
+export declare function scopeParams(flags: ScopeFlags): QueryParams;
+export declare const scheduleFlags: {
+    'end-time': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'start-time': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare const pricingModelFlag: {
+    'pricing-model': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare function startOfDayUtc(date: string | undefined): string | undefined;
+export declare function todayUtc(): string;
+export declare function periodParams(flags: {
+    'date-from'?: string;
+    'date-to'?: string;
+}): Record<string, string>;
+export declare function moneyFlag(description: string, opts?: {
+    required?: boolean;
+}): import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+export declare const currencyFlag: {
+    currency: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare const idempotencyFlags: {
+    'idempotency-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare function money(amount: string | undefined, currency: string): AsaMoney | undefined;
+interface BulkOutcome {
+    applied: unknown[];
+    errors: AsaMutationError[];
+    isValidationFailure: boolean;
+    kind: string;
+}
+export declare function reportBulkOutcome({ applied, errors, isValidationFailure, kind }: BulkOutcome, log: (msg: string) => void): void;
+export {};

package/dist/lib/asa-flags.js

@@ -0,0 +1,137 @@
+import { Flags } from '@oclif/core';
+import { describeListedError } from './errors.js';
+import { isValidUuid } from './flags.js';
+const DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+const MONEY_REGEX = /^\d+(\.\d{1,6})?$/;
+export const MAX_BULK_ITEMS = 100;
+export const MAX_BY_DAYS = 16;
+export const ASA_METRIC_ENTITIES = ['ad', 'ad-group', 'campaign', 'keyword'];
+export const ASA_GROUP_BY_DIMENSIONS = ['country', 'day', 'month', 'quarter', 'week', 'year'];
+export const asaPaginationFlags = {
+    page: Flags.integer({
+        default: 1,
+        description: 'Page number',
+        min: 1,
+    }),
+    'page-size': Flags.integer({
+        default: 100,
+        description: 'Items per page (max 1000); prefer one big page over a pagination loop',
+        max: 1000,
+        min: 1,
+    }),
+};
+export const byDaysFlag = {
+    'by-days': Flags.integer({
+        description: 'Renewal window in days for cohort metrics, repeatable; omit for the dashboard defaults',
+        multiple: true,
+    }),
+};
+async function parseDate(input) {
+    if (!DATE_REGEX.test(input))
+        throw new Error('Dates must be written as YYYY-MM-DD.');
+    return input;
+}
+export const periodFlags = {
+    'date-from': Flags.string({
+        description: 'Start of the reporting period (YYYY-MM-DD), defaults to today',
+        parse: parseDate,
+    }),
+    'date-to': Flags.string({
+        description: 'End of the reporting period (YYYY-MM-DD), defaults to today',
+        parse: parseDate,
+    }),
+};
+async function parseId(input) {
+    if (!isValidUuid(input))
+        throw new Error('Ids are the UUIDs printed by the matching list command.');
+    return input;
+}
+function idFilter(entity) {
+    return Flags.string({ description: `Keep only rows in this ${entity}; repeatable`, multiple: true, parse: parseId });
+}
+const searchFilter = { search: Flags.string({ description: 'Case-insensitive substring match on the name' }) };
+export const assetScopeFlags = {
+    app: idFilter('app'),
+    'campaign-group': idFilter('campaign group'),
+};
+export const orgScopeFlags = { ...assetScopeFlags, ...searchFilter };
+export const campaignScopeFlags = { ...orgScopeFlags, campaign: idFilter('campaign') };
+export const adGroupScopeFlags = { ...campaignScopeFlags, 'ad-group': idFilter('ad group') };
+export const adScopeFlags = {
+    'ad-group': idFilter('ad group'),
+    campaign: idFilter('campaign'),
+    'campaign-group': idFilter('campaign group'),
+    ...searchFilter,
+};
+export const statusFilter = (options) => ({
+    status: Flags.string({ description: 'Keep only rows in this state', options }),
+});
+export function scopeParams(flags) {
+    return {
+        ad_group_id: flags['ad-group'],
+        app_id: flags.app,
+        campaign_group_id: flags['campaign-group'],
+        campaign_id: flags.campaign,
+        search: flags.search,
+        status: flags.status,
+    };
+}
+export const scheduleFlags = {
+    'end-time': Flags.string({ description: 'Schedule end (YYYY-MM-DD)', parse: parseDate }),
+    'start-time': Flags.string({ description: 'Schedule start (YYYY-MM-DD), defaults to today', parse: parseDate }),
+};
+export const pricingModelFlag = {
+    'pricing-model': Flags.string({
+        default: 'CPC',
+        description: 'Pricing model; Apple requires one on every ad group',
+        options: ['CPC', 'CPM'],
+    }),
+};
+export function startOfDayUtc(date) {
+    return date === undefined ? undefined : `${date}T00:00:00Z`;
+}
+export function todayUtc() {
+    return new Date().toISOString().slice(0, 10);
+}
+export function periodParams(flags) {
+    const params = {};
+    if (flags['date-from'])
+        params.date_from = flags['date-from'];
+    if (flags['date-to'])
+        params.date_to = flags['date-to'];
+    return params;
+}
+async function parseMoney(input) {
+    if (!MONEY_REGEX.test(input))
+        throw new Error('Amounts must be plain numbers, e.g. 50 or 12.50.');
+    return input;
+}
+export function moneyFlag(description, opts = {}) {
+    return Flags.string({
+        description: `${description} (amount, e.g. 50 or 12.50)`,
+        parse: parseMoney,
+        required: opts.required,
+    });
+}
+export const currencyFlag = {
+    currency: Flags.string({ default: 'USD', description: 'Currency code for the amounts in this call' }),
+};
+export const idempotencyFlags = {
+    'idempotency-key': Flags.string({
+        description: 'Idempotency key for this write; re-running with the same key replays the stored result instead of applying twice',
+    }),
+};
+export function money(amount, currency) {
+    return amount === undefined ? undefined : { amount, currency };
+}
+export function reportBulkOutcome({ applied, errors, isValidationFailure, kind }, log) {
+    if (isValidationFailure) {
+        log(`Nothing was applied: the batch failed validation before Apple was called.`);
+    }
+    else {
+        log(`${applied.length} ${kind} applied, ${errors.length} rejected.`);
+    }
+    for (const error of errors) {
+        log(`  ${describeListedError(error).text}`);
+    }
+}