adapty 0.3.0 → 0.4.0

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}`);
+    }
+}

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

@@ -0,0 +1,287 @@
+export type AsaAccessSource = 'allowlist' | 'legacy' | 'none' | 'payg';
+export type AsaAppleCredentialsStatus = 'active' | 'expired' | 'invalid' | 'unset';
+export type AsaKeywordMatchType = 'BROAD' | 'EXACT';
+export type AsaKeywordStatus = 'ACTIVE' | 'PAUSED';
+export type AsaStatus = 'ENABLED' | 'PAUSED';
+export type AsaNegativeKeywordScope = 'AD_GROUP' | 'ALL_CAMPAIGN_AD_GROUPS' | 'CAMPAIGN';
+export interface AsaMoney {
+    amount: string;
+    currency: string;
+}
+export interface AsaMetricsDTO {
+    avg_cpm: string;
+    avg_cpt: string;
+    impressions: number;
+    ipm: string;
+    local_spend: string;
+    tap_install_cpi: string;
+    tap_install_rate: string;
+    tap_installs: number;
+    tap_new_downloads: number;
+    tap_redownloads: number;
+    taps: number;
+    total_avg_cpi: string;
+    total_install_rate: string;
+    total_installs: number;
+    total_new_downloads: number;
+    total_redownloads: number;
+    ttr: string;
+    view_installs: number;
+    view_new_downloads: number;
+    view_redownloads: number;
+}
+export interface AsaMeDTO {
+    access_source: AsaAccessSource;
+    apple_credentials_status: AsaAppleCredentialsStatus;
+    company_id: string;
+}
+export interface AsaAppleOAuthDTO {
+    auth_url: string;
+}
+export interface AsaAppDTO {
+    adam_id: number;
+    bundle_id: null | string;
+    campaign_group_ids: string[];
+    country_or_region_codes: string[];
+    developer_name: null | string;
+    internal_id: string;
+    last_synced_at: string;
+    name: string;
+}
+export interface AsaCampaignGroupDTO {
+    currency: string;
+    internal_id: string;
+    last_synced_at: string;
+    org_id: number;
+    org_name: string;
+    parent_org_id: number;
+    time_zone: string;
+}
+export interface AsaCampaignDTO {
+    ad_channel_type: string;
+    adam_id: number;
+    app_id: string;
+    bidding_strategy: null | string;
+    billing_event: string;
+    budget_amount: AsaMoney | null;
+    campaign_group_id: string;
+    campaign_id: number;
+    countries_or_regions: string[];
+    daily_budget_amount: AsaMoney | null;
+    end_time: null | string;
+    internal_id: string;
+    name: string;
+    org_id: number;
+    start_time: null | string;
+    status: AsaStatus;
+    supply_sources: string[];
+    target_cpa: AsaMoney | null;
+}
+export interface AsaAdGroupDTO {
+    ad_group_id: number;
+    app_id: string;
+    automated_keywords_opt_in: boolean | null;
+    bidding_strategy: null | string;
+    campaign_group_id: string;
+    campaign_id: string;
+    cpa_goal: AsaMoney | null;
+    default_bid_amount: AsaMoney;
+    end_time: null | string;
+    internal_id: string;
+    name: string;
+    payment_model: null | string;
+    pricing_model: null | string;
+    start_time: null | string;
+    status: AsaStatus | null;
+    target_cpa: AsaMoney | null;
+}
+export interface AsaKeywordDTO {
+    ad_group_id: string;
+    app_id: string;
+    bid_amount: AsaMoney;
+    campaign_group_id: string;
+    campaign_id: string;
+    creation_time: null | string;
+    internal_id: string;
+    keyword_id: number;
+    match_type: AsaKeywordMatchType;
+    status: AsaKeywordStatus | null;
+    text: string;
+}
+export interface AsaSearchTermDTO {
+    ad_group_id: string;
+    app_id: string;
+    campaign_group_id: string;
+    campaign_id: string;
+    country_or_region: string;
+    keyword_id: null | string;
+    match_type: AsaKeywordMatchType | null;
+    metrics: AsaMetricsDTO;
+    rank: null | number;
+    search_popularity: null | number;
+    source: null | string;
+    text: null | string;
+}
+export interface AsaNegativeKeywordDTO {
+    ad_group_id: null | string;
+    ad_group_name: null | string;
+    campaign_id: string;
+    campaign_name: null | string;
+    internal_id: string;
+    last_synced_at: string;
+    match_type: AsaKeywordMatchType;
+    status: AsaKeywordStatus;
+    text: string;
+}
+export interface AsaCreativeDTO {
+    adam_id: number;
+    app_id: string;
+    campaign_group_id: string;
+    creative_id: number;
+    internal_id: string;
+    name: string;
+    org_id: number;
+    product_page_id: null | string;
+    state: string;
+    state_reasons: string[];
+    type: string;
+}
+export interface AsaProductPageDTO {
+    adam_id: number;
+    app_id: string;
+    deep_link: null | string;
+    external_id: number;
+    internal_id: string;
+    language_codes: string[];
+    languages: string[];
+    last_synced_at: string;
+    name: string;
+    state: string;
+}
+export interface AsaAdDTO {
+    ad_group_id: string;
+    ad_group_name: null | string;
+    ad_id: number;
+    app_id: null | string;
+    campaign_group_id: string;
+    campaign_id: string;
+    creation_time: null | string;
+    creative_id: null | string;
+    creative_type: string;
+    internal_id: string;
+    last_synced_at: string;
+    name: string;
+    product_page_id: null | string;
+    product_page_name: null | string;
+    serving_state_reasons: string[];
+    serving_status: string;
+    status: AsaStatus;
+}
+export interface AsaAutomationDTO {
+    actions: unknown[];
+    apply_to: unknown[];
+    conditions: unknown[];
+    created_at: string;
+    date_last_run: null | string;
+    date_next_run: null | string;
+    id: string;
+    name: string;
+    operate_with: string;
+    rba_type: string;
+    run_frequency: Record<string, unknown>;
+    status: number;
+    updated_at: string;
+}
+export interface AsaAutomationRunDTO {
+    [key: string]: unknown;
+    id?: string;
+}
+export interface AsaAutomationRunEnqueuedDTO {
+    automation_id: string;
+    dry_run: boolean;
+    run_id: null | string;
+}
+export interface AsaProductPageSyncDTO {
+    accepted_at: string;
+    message: string;
+    org_targets: number;
+    replayed: boolean;
+    state: string;
+    sync_id: string;
+}
+export interface AsaCompetitorTopAppDTO {
+    adamId: number;
+    avgSov: string;
+    countries: string[];
+    iconUrl: null | string;
+    name: null | string;
+    termsCount: number;
+}
+export interface AsaCompetitorContestedTermDTO {
+    competitorCount: number;
+    maxSov: string;
+    term: string;
+}
+export interface AsaCompetitorsSummaryTotalDTO {
+    competitorsCount: number;
+    countriesAsaCount: number;
+    countriesWithAsaTerms: number;
+    mostContestedTerms: AsaCompetitorContestedTermDTO[];
+    topAppsByPerformance: AsaCompetitorTopAppDTO[];
+    totalUniqueTerms: number;
+}
+export interface AsaCompetitorAppTermsDTO {
+    adamId: number;
+    countries: Record<string, {
+        sov: string;
+        term: string;
+    }[]>;
+    iconUrl: null | string;
+    name: null | string;
+}
+export interface AsaCompetitorsSummaryDTO {
+    byApps: AsaCompetitorAppTermsDTO[];
+    total: AsaCompetitorsSummaryTotalDTO;
+}
+export interface AsaMutationError {
+    apple_error_code?: null | string;
+    apple_error_message?: null | string;
+    entity_type?: string;
+    input_ref?: null | number;
+    operation?: string;
+    retryable?: boolean;
+    validation_error_code?: string;
+    validation_error_message?: string;
+}
+export interface AsaCampaignMutationDTO {
+    campaign: AsaCampaignMutationEntity | null;
+    errors: AsaMutationError[];
+}
+export interface AsaCampaignMutationEntity {
+    campaign_group_id: string;
+    campaign_id: number;
+    internal_id: string;
+    name: string;
+    status: AsaStatus;
+}
+export interface AsaAdGroupMutationDTO {
+    ad_group: null | Record<string, unknown>;
+    errors: AsaMutationError[];
+}
+export interface AsaAdMutationDTO {
+    ad: AsaAdDTO | null;
+    errors: AsaMutationError[];
+}
+export interface AsaKeywordMutationDTO {
+    errors: AsaMutationError[];
+    is_validation_failure: boolean;
+    keywords: Record<string, unknown>[];
+}
+export interface AsaNegativeKeywordMutationDTO {
+    errors: AsaMutationError[];
+    is_validation_failure: boolean;
+    negative_keywords: Record<string, unknown>[];
+}
+export interface AsaAutomationMutationDTO {
+    automation: AsaAutomationDTO | null;
+}

package/dist/lib/asa-schemas.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/errors.d.ts

@@ -1,14 +1,37 @@
 export interface ApiErrorBody {
+    detail?: string;
     error?: string;
     error_code?: string;
     errors?: Record<string, string[]>;
+    retry_after_seconds?: number;
     status_code?: number;
 }
+export type ApiErrorFormat = 'asa' | 'developer';
+export interface ApiErrorOptions {
+    detail?: string;
+    retryAfterSeconds?: number;
+}
+export interface ListedError {
+    apple_error_code?: null | string;
+    apple_error_message?: null | string;
+    error_code?: string;
+    field_name?: null | string;
+    input_ref?: null | number;
+    message?: string;
+    validation_error_code?: string;
+    validation_error_message?: string;
+}
+export declare function describeListedError(error: ListedError): {
+    code: string | undefined;
+    text: string;
+};
 export declare class ApiError extends Error {
     statusCode: number;
     errorCode: string;
     fieldErrors: Record<string, string[]>;
-    constructor(statusCode: number, errorCode: string, fieldErrors: Record<string, string[]>);
+    detail?: string;
+    retryAfterSeconds?: number;
+    constructor(statusCode: number, errorCode: string, fieldErrors: Record<string, string[]>, opts?: ApiErrorOptions);
     toHuman(): string;
     toJSON(): ApiErrorBody;
 }
@@ -20,4 +43,4 @@ export declare class NetworkError extends Error {
 export declare class AuthRequiredError extends Error {
     constructor();
 }
-export declare function parseApiError(statusCode: number, body: unknown): ApiError;
+export declare function parseApiError(statusCode: number, body: unknown, opts?: ApiErrorOptions, format?: ApiErrorFormat): ApiError;

package/dist/lib/errors.js

@@ -1,13 +1,23 @@
+export function describeListedError(error) {
+    const code = error.error_code ?? error.apple_error_code ?? error.validation_error_code ?? undefined;
+    const reason = error.message ?? error.apple_error_message ?? error.validation_error_message ?? code ?? 'rejected';
+    const position = error.input_ref === null || error.input_ref === undefined ? '' : ` (item ${error.input_ref + 1})`;
+    return { code, text: `${reason}${position}` };
+}
 export class ApiError extends Error {
     statusCode;
     errorCode;
     fieldErrors;
-    constructor(statusCode, errorCode, fieldErrors) {
-        super(errorCode);
+    detail;
+    retryAfterSeconds;
+    constructor(statusCode, errorCode, fieldErrors, opts = {}) {
+        super(opts.detail ?? errorCode);
         this.statusCode = statusCode;
         this.errorCode = errorCode;
         this.fieldErrors = fieldErrors;
         this.name = 'ApiError';
+        this.detail = opts.detail;
+        this.retryAfterSeconds = opts.retryAfterSeconds;
     }
     toHuman() {
         const lines = [`Error: ${this.errorCode}`];
@@ -24,8 +34,10 @@ export class ApiError extends Error {
     }
     toJSON() {
         return {
+            detail: this.detail,
             error_code: this.errorCode,
             errors: Object.keys(this.fieldErrors).length > 0 ? this.fieldErrors : undefined,
+            retry_after_seconds: this.retryAfterSeconds,
             status_code: this.statusCode,
         };
     }
@@ -48,16 +60,45 @@ export class AuthRequiredError extends Error {
         this.name = 'AuthRequiredError';
     }
 }
-export function parseApiError(statusCode, body) {
+function parseListedErrors(errors, statusCode, opts) {
+    const fieldErrors = {};
+    for (const item of errors) {
+        if (item.field_name && item.message) {
+            fieldErrors[item.field_name] = [...(fieldErrors[item.field_name] ?? []), item.message];
+        }
+    }
+    const described = errors.map((item) => describeListedError(item));
+    const detail = described.map((item) => item.text).join('; ');
+    return new ApiError(statusCode, described[0]?.code ?? `http_${statusCode}`, fieldErrors, {
+        ...opts,
+        detail: detail || undefined,
+    });
+}
+export function parseApiError(statusCode, body, opts = {}, format = 'developer') {
     if (!body || typeof body !== 'object') {
-        return new ApiError(statusCode, `http_${statusCode}`, {});
+        return new ApiError(statusCode, `http_${statusCode}`, {}, opts);
     }
     const parsed = body;
+    if (format === 'asa' && Array.isArray(parsed.errors) && parsed.errors.length > 0) {
+        return parseListedErrors(parsed.errors, statusCode, opts);
+    }
     if (parsed.error_code) {
-        return new ApiError(statusCode, parsed.error_code, parsed.errors ?? {});
+        return new ApiError(statusCode, parsed.error_code, parsed.errors ?? {}, opts);
     }
     if (parsed.error) {
-        return new ApiError(statusCode, parsed.error, {});
+        return new ApiError(statusCode, parsed.error, {}, opts);
+    }
+    if (format === 'asa' && Array.isArray(parsed.detail)) {
+        const fieldErrors = {};
+        for (const item of parsed.detail) {
+            const field = (item.loc ?? []).slice(1).join('.') || 'body';
+            if (item.msg)
+                fieldErrors[field] = [...(fieldErrors[field] ?? []), item.msg];
+        }
+        return new ApiError(statusCode, `http_${statusCode}`, fieldErrors, opts);
+    }
+    if (format === 'asa' && typeof parsed.detail === 'string') {
+        return new ApiError(statusCode, `http_${statusCode}`, {}, { ...opts, detail: parsed.detail });
     }
-    return new ApiError(statusCode, `http_${statusCode}`, {});
+    return new ApiError(statusCode, `http_${statusCode}`, {}, opts);
 }

package/dist/lib/output.js

@@ -11,30 +11,60 @@ function formatLabel(snakeKey) {
     })
         .join(' ');
 }
-function formatValue(value, indent = '') {
-    if (Array.isArray(value)) {
-        return value.map((v) => (typeof v === 'object' && v !== null ? formatValue(v, indent) : String(v))).join(', ');
-    }
-    if (typeof value === 'object' && value !== null) {
-        return Object.entries(value)
-            .filter(([, v]) => v !== undefined && v !== null)
-            .map(([k, v]) => `${indent}  ${formatLabel(k)}: ${formatValue(v, indent + '  ')}`)
-            .join('\n');
+function isScalar(value) {
+    return typeof value !== 'object' || value === null;
+}
+function renderArrayItems(items, indent) {
+    const childIndent = indent + '  ';
+    const lines = [];
+    for (const item of items) {
+        if (item === undefined || item === null)
+            continue;
+        if (Array.isArray(item)) {
+            lines.push(...renderArrayItems(item, childIndent));
+        }
+        else if (isScalar(item)) {
+            lines.push(`${indent}- ${String(item)}`);
+        }
+        else {
+            const rendered = renderObject(item, childIndent);
+            if (rendered.length === 0)
+                continue;
+            lines.push(`${indent}- ${rendered[0].slice(childIndent.length)}`, ...rendered.slice(1));
+        }
     }
-    return String(value);
+    return lines;
 }
-export function printResponse(data, log) {
+function renderObject(data, indent) {
+    const lines = [];
     for (const [key, value] of Object.entries(data)) {
         if (value === undefined || value === null)
             continue;
-        if (typeof value === 'object' && !Array.isArray(value)) {
-            log(`${formatLabel(key)}:`);
-            log(formatValue(value));
+        const label = `${indent}${formatLabel(key)}:`;
+        if (Array.isArray(value)) {
+            if (value.length === 0)
+                continue;
+            if (value.every((v) => isScalar(v))) {
+                lines.push(`${label} ${value.map(String).join(', ')}`);
+            }
+            else {
+                lines.push(label, ...renderArrayItems(value, indent + '  '));
+            }
+        }
+        else if (isScalar(value)) {
+            lines.push(`${label} ${String(value)}`);
         }
         else {
-            log(`${formatLabel(key)}: ${formatValue(value)}`);
+            const nested = renderObject(value, indent + '  ');
+            if (nested.length > 0)
+                lines.push(label, ...nested);
         }
     }
+    return lines;
+}
+export function printResponse(data, log) {
+    for (const line of renderObject(data, ''))
+        log(line);
 }
 export function printList(items, log, pagination) {
     for (const [i, item] of items.entries()) {