adapty 0.8.8 → 0.9.0

package/dist/sdk/adapty/errors.js

@@ -5,6 +5,10 @@
  *
  * Wired once in createAdapty: which shapes a service speaks is product knowledge, and ASA speaks
  * another — which is why the transport takes the parser as a parameter.
+ *
+ * The Wizard Service sits behind the same transport (section 4.5 of the CLI–WS contract) and
+ * words its rejection as `{ error: { code, message } }` (`WizardError`) — one shape this parser
+ * now reads too, alongside the ones the developer API sends.
  */
 export const developerErrorParser = (_status, body) => {
     if (typeof body !== 'object' || body === null) {
@@ -16,11 +20,32 @@ export const developerErrorParser = (_status, body) => {
         // than an HTTP status when the server sends no field errors
         return { code: errorCode, message: fieldMessages(errors) ?? errorCode };
     }
+    if (typeof error === 'object' && error !== null) {
+        const { code, message } = error;
+        if (typeof code === 'string' && code !== '') {
+            return { code, message: typeof message === 'string' && message !== '' ? message : code };
+        }
+    }
     if (typeof error === 'string' && error !== '') {
         return { code: error, message: error };
     }
+    if (Array.isArray(errors)) {
+        return listedErrors(errors);
+    }
     return {};
 };
+/** `{ errors: [{ detail, code, status }] }`: how the API turns a token away, `not_authenticated` on a 403. */
+const listedErrors = (errors) => {
+    const items = errors.filter(item => typeof item === 'object' && item !== null);
+    const details = items.map(item => item.detail).filter(isText);
+    const code = items.map(item => item.code).find(isText);
+    const message = details.length > 0 ? details.join('; ') : code;
+    if (message === undefined) {
+        return {};
+    }
+    return code === undefined ? { message } : { code, message };
+};
+const isText = (value) => typeof value === 'string' && value !== '';
 /** `non_field_errors` is the server's name for "about the request as a whole": printed bare. */
 const fieldMessages = (errors) => {
     if (typeof errors !== 'object' || errors === null) {

package/dist/sdk/adapty/index.d.ts

@@ -1,6 +1,7 @@
 import type { AccessLevelsApi } from './access-levels.js';
 import type { AppsApi } from './apps/index.js';
 import type { AuthApi } from './auth/index.js';
+import type { MigrationApi } from './migrations/index.js';
 import type { Clock } from '../core/clock.js';
 import type { RetryAttempt } from '../core/http/index.js';
 export { platforms } from './apps/index.js';
@@ -8,6 +9,7 @@ export { developerErrorParser } from './errors.js';
 export type { AccessLevel, AccessLevelList, AccessLevelsApi } from './access-levels.js';
 export type { AppDetail, AppsApi, AppSummary, CreateAppInput, UpdateAppInput } from './apps/index.js';
 export type { AuthApi, AuthUser, IssuedToken } from './auth/index.js';
+export type { Action, ActionKind, AvailableFlow, CreateMigrationInput, Envelope, Issue, JsonSchema, Migration, MigrationApi, MigrationList, MigrationState, Progress, ResourceRef, Step, StepStatus, WaitOptions, WizardError, } from './migrations/index.js';
 export type { PageParams, Paginated, Pagination } from './pagination.js';
 /** Exported because the adapter compares the resolved URL with it and warns when they differ. */
 export declare const DEFAULT_ADAPTY_API_URL = "https://api-admin.adapty.io/api/v1/developer";
@@ -20,6 +22,8 @@ export type AdaptyOptions = {
     baseUrl?: string | undefined;
     clock?: Clock | undefined;
     fetch?: typeof globalThis.fetch | undefined;
+    /** Whether a person is watching the caller, for the server's audit trail. */
+    interactive?: boolean | undefined;
     onRetry?: ((info: RetryAttempt) => void) | undefined;
     signal?: AbortSignal | undefined;
     /** Without a token only auth is usable — that is how login builds the sdk. */
@@ -31,6 +35,7 @@ export type Adapty = {
     accessLevels: AccessLevelsApi;
     apps: AppsApi;
     auth: AuthApi;
+    migrations: MigrationApi;
 };
 /** The assembly point of the developer API: one transport, resources on top of it. */
 export declare const createAdapty: (options?: AdaptyOptions) => Adapty;

package/dist/sdk/adapty/index.js

@@ -1,27 +1,53 @@
+import { systemClock } from '../core/clock.js';
 import { createHttp } from '../core/http/index.js';
 import { accessLevels } from './access-levels.js';
 import { apps } from './apps/index.js';
 import { auth } from './auth/index.js';
 import { developerErrorParser } from './errors.js';
+import { migrations } from './migrations/index.js';
 export { platforms } from './apps/index.js';
 export { developerErrorParser } from './errors.js';
 /** Exported because the adapter compares the resolved URL with it and warns when they differ. */
 export const DEFAULT_ADAPTY_API_URL = 'https://api-admin.adapty.io/api/v1/developer';
+/**
+ * Who is calling, on every request of both clients: `User-Agent` says which program, section 3's
+ * `X-Adapty-Interactive` says whether a person is watching it. Both are claims a client makes about
+ * itself, so the server may log them and choose a format by them, never grant anything on them.
+ */
+const callerHeaders = (options) => {
+    const headers = {};
+    if (options.userAgent !== undefined) {
+        headers['user-agent'] = options.userAgent;
+    }
+    // Sent as `false` too: "nobody was watching" is the half of the audit trail that matters.
+    if (options.interactive !== undefined) {
+        headers['x-adapty-interactive'] = String(options.interactive);
+    }
+    return Object.keys(headers).length === 0 ? undefined : headers;
+};
 /** The assembly point of the developer API: one transport, resources on top of it. */
 export const createAdapty = (options = {}) => {
-    const http = createHttp({
+    const transport = {
         baseUrl: options.baseUrl ?? DEFAULT_ADAPTY_API_URL,
         clock: options.clock,
         fetch: options.fetch,
-        headers: options.userAgent === undefined ? undefined : { 'user-agent': options.userAgent },
+        headers: callerHeaders(options),
         onRetry: options.onRetry,
         parseError: developerErrorParser,
         signal: options.signal,
         token: options.token,
-    });
+    };
+    const http = createHttp(transport);
+    // Same host, same token, another service: /migrations is proxied through to the Wizard
+    // Service, which is not Django and answers 404 to the trailing slash the rest of this API
+    // requires. One client per convention, so neither resource has to remember the other's.
+    const wizard = createHttp({ ...transport, trailingSlash: false });
     return {
         accessLevels: accessLevels(http),
         apps: apps(http),
         auth: auth(http),
+        // The clock is a dependency here too, not only in the transport: `waitFor` sleeps
+        // between polls, and a test must be able to do that instantly.
+        migrations: migrations(wizard, options.clock ?? systemClock),
     };
 };

package/dist/sdk/adapty/migrations/action.d.ts

@@ -0,0 +1,15 @@
+import type { Issue } from '../../core/errors.js';
+/** Pass the revision you read; the server rejects stale revisions with 409 revision_conflict. */
+export type RunActionInput = {
+    expectedRevision: number;
+    input?: unknown;
+};
+type RunActionRequest = {
+    expected_revision: number;
+    input: Record<string, unknown>;
+};
+/** Validate the input shape locally; the server validates its fields against the action schema. */
+export declare const validateActionInput: (input: unknown) => Issue[];
+/** Omitted input is sent as an empty object. */
+export declare const toRunActionRequest: ({ expectedRevision, input }: RunActionInput) => RunActionRequest;
+export {};

package/dist/sdk/adapty/migrations/action.js

@@ -0,0 +1,17 @@
+const isPlainObject = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+/** Validate the input shape locally; the server validates its fields against the action schema. */
+export const validateActionInput = (input) => {
+    if (input === undefined || isPlainObject(input)) {
+        return [];
+    }
+    return [{ message: 'must be a JSON object', path: 'input' }];
+};
+/** Omitted input is sent as an empty object. */
+export const toRunActionRequest = ({ expectedRevision, input }) => {
+    return {
+        expected_revision: expectedRevision,
+        input: isPlainObject(input) ? input : {},
+    };
+};

package/dist/sdk/adapty/migrations/close.d.ts

@@ -0,0 +1,16 @@
+import type { Issue } from '../../core/errors.js';
+/** Both outcomes permanently close the migration. */
+export type CloseOutcome = 'cancel' | 'finish';
+/** Accept strings so invalid outcomes produce a validation error for any caller. */
+export type CloseMigrationInput = {
+    expectedRevision: number;
+    outcome: string;
+};
+type CloseMigrationRequest = {
+    expected_revision: number;
+    outcome: string;
+};
+export declare const validateCloseMigration: ({ outcome }: CloseMigrationInput) => Issue[];
+/** The server rejects a stale revision with 409. */
+export declare const toCloseRequest: ({ expectedRevision, outcome }: CloseMigrationInput) => CloseMigrationRequest;
+export {};

package/dist/sdk/adapty/migrations/close.js

@@ -0,0 +1,7 @@
+const OUTCOMES = new Set(['cancel', 'finish']);
+export const validateCloseMigration = ({ outcome }) => (OUTCOMES.has(outcome) ? [] : [{ message: 'must be `finish` or `cancel`', path: 'outcome' }]);
+/** The server rejects a stale revision with 409. */
+export const toCloseRequest = ({ expectedRevision, outcome }) => ({
+    expected_revision: expectedRevision,
+    outcome,
+});

package/dist/sdk/adapty/migrations/create.d.ts

@@ -0,0 +1,16 @@
+import type { Issue } from '../../core/errors.js';
+/** Keep fields optional so incomplete input produces a validation error. */
+export type CreateMigrationInput = {
+    appId?: string | undefined;
+    appName?: string | undefined;
+    flow?: string | undefined;
+};
+type CreateMigrationRequest = {
+    app_id?: string;
+    app_name?: string;
+    flow: string;
+};
+/** Accept either a new app name or an existing app ID with a flow. Issue paths identify CLI flags. */
+export declare const validateCreateMigration: (input: CreateMigrationInput) => Issue[];
+export declare const toCreateRequest: (input: CreateMigrationInput) => CreateMigrationRequest;
+export {};

package/dist/sdk/adapty/migrations/create.js

@@ -0,0 +1,43 @@
+/** The main flow creates the Adapty app; other flows require an existing app. */
+const MAIN_FLOW = 'main';
+/** Accept either a new app name or an existing app ID with a flow. Issue paths identify CLI flags. */
+export const validateCreateMigration = (input) => {
+    const { appId, appName, flow } = input;
+    if (appName === undefined && flow === undefined && appId === undefined) {
+        return [{ message: 'pass --name to migrate into a new app, or --flow with --app for an existing one' }];
+    }
+    const issues = [];
+    if (appName !== undefined) {
+        if (appName.trim() === '') {
+            issues.push({ message: 'must not be empty', path: 'name' });
+        }
+        if (flow !== undefined || appId !== undefined) {
+            issues.push({ message: 'starts the main flow and names the app it creates: --flow and --app do not apply', path: 'name' });
+        }
+        return issues;
+    }
+    if (flow === undefined) {
+        issues.push({ message: 'required unless --name is given', path: 'flow' });
+    }
+    else if (flow.trim() === '') {
+        issues.push({ message: 'must not be empty', path: 'flow' });
+    }
+    else if (flow === MAIN_FLOW) {
+        issues.push({ message: 'main always creates a new Adapty app: use --name instead of --flow main --app', path: 'flow' });
+    }
+    if (appId === undefined) {
+        issues.push({ message: 'required with --flow: the app the flow runs for', path: 'app' });
+    }
+    return issues;
+};
+export const toCreateRequest = (input) => {
+    const { appId, appName, flow } = input;
+    if (appName !== undefined) {
+        return { app_name: appName, flow: MAIN_FLOW };
+    }
+    if (appId === undefined || flow === undefined) {
+        // The resource validates first; reaching this branch means a caller skipped validation.
+        throw new Error('createMigration needs either appName, or appId with flow');
+    }
+    return { app_id: appId, flow };
+};

package/dist/sdk/adapty/migrations/index.d.ts

@@ -0,0 +1,9 @@
+export { validateActionInput } from './action.js';
+export { validateCloseMigration } from './close.js';
+export { validateCreateMigration } from './create.js';
+export { migrations } from './resource.js';
+export type { RunActionInput } from './action.js';
+export type { CloseMigrationInput, CloseOutcome } from './close.js';
+export type { CreateMigrationInput } from './create.js';
+export type { MigrationApi, WaitOptions } from './resource.js';
+export type { Action, ActionKind, AvailableFlow, Envelope, Issue, JsonSchema, Migration, MigrationList, MigrationState, Progress, ResourceRef, Step, StepStatus, WizardError, } from './model.js';

package/dist/sdk/adapty/migrations/index.js

@@ -0,0 +1,4 @@
+export { validateActionInput } from './action.js';
+export { validateCloseMigration } from './close.js';
+export { validateCreateMigration } from './create.js';
+export { migrations } from './resource.js';

package/dist/sdk/adapty/migrations/model.d.ts

@@ -0,0 +1,100 @@
+export type MigrationState = 'running' | 'action_required' | 'completed' | 'failed' | 'canceled';
+export type ActionKind = 'input' | 'upload' | 'external';
+export type StepStatus = 'locked' | 'active' | 'done';
+export type JsonSchema = Record<string, unknown>;
+export type Envelope<TResult = unknown> = {
+    migration: Migration;
+    steps: Step[];
+    issues: Issue[];
+    next_actions: Action[];
+    available_actions: Action[];
+    resources: ResourceRef[];
+    result: TResult | null;
+};
+export type MigrationList = {
+    items: Migration[];
+    available: AvailableFlow[];
+};
+export type AvailableFlow = {
+    flow: string;
+    title: string;
+    detail: string | null;
+    app: {
+        id: string;
+        name: string;
+    };
+};
+export type Migration = {
+    id: string;
+    flow: string;
+    revision: number;
+    /** Known values are MigrationState; newer servers may introduce others. */
+    state: string;
+    app: {
+        id: string;
+        name: string;
+    } | null;
+    poll_after_seconds: number;
+    progress: Progress | null;
+    summary: string;
+    created_at: string;
+    updated_at: string;
+};
+export type Progress = {
+    done: number;
+    total: number | null;
+    unit: string;
+};
+export type Step = {
+    step_id: string;
+    title: string;
+    status: StepStatus;
+    summary: string | null;
+};
+export type Issue = {
+    code: string;
+    title: string;
+    detail: string | null;
+    step_id: string | null;
+    action_id: string | null;
+};
+type ActionBase = {
+    action_id: string;
+    step_id: string;
+    title: string;
+    detail: string | null;
+    reads: string[];
+    confirm: string | null;
+};
+export type Action = ActionBase & ({
+    kind: 'input';
+    input_schema: JsonSchema | null;
+} | {
+    kind: 'upload';
+} | {
+    kind: 'external';
+    href: string;
+} | {
+    kind: string;
+    href?: string;
+});
+export type ResourceRef = {
+    name: string;
+    title: string;
+};
+export type WizardError = {
+    error: {
+        code: string;
+        message: string;
+        detail: string | null;
+        next_step: string | null;
+        retryable: boolean;
+        retry_after_seconds: number | null;
+        fields: {
+            path: string;
+            message: string;
+        }[];
+        request_id: string;
+    };
+};
+export {};

package/dist/sdk/adapty/migrations/model.js

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

package/dist/sdk/adapty/migrations/resource.d.ts

@@ -0,0 +1,27 @@
+import type { RunActionInput } from './action.js';
+import type { CloseMigrationInput } from './close.js';
+import type { CreateMigrationInput } from './create.js';
+import type { Envelope, MigrationList } from './model.js';
+import type { Clock } from '../../core/clock.js';
+import type { Http } from '../../core/http/index.js';
+export type WaitOptions = {
+    /** Called before each pause with the latest response and the upcoming delay. */
+    onPoll?: ((envelope: Envelope, delayMs: number) => void) | undefined;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+};
+export declare const migrations: (http: Http, clock: Clock) => {
+    get: (id: string) => Promise<Envelope>;
+    list: () => Promise<MigrationList>;
+    resource: <TResult = unknown>(id: string, name: string) => Promise<Envelope<TResult>>;
+    create: (input: CreateMigrationInput) => Promise<Envelope>;
+    /** Closing does not require an offered action. */
+    close: (id: string, input: CloseMigrationInput) => Promise<Envelope>;
+    /**
+     * Poll until the revision changes or the state leaves running.
+     * Return the last response when the wait budget runs out.
+     */
+    waitFor: (id: string, options?: WaitOptions) => Promise<Envelope>;
+    runAction: (id: string, actionId: string, input: RunActionInput) => Promise<Envelope>;
+};
+export type MigrationApi = ReturnType<typeof migrations>;

package/dist/sdk/adapty/migrations/resource.js

@@ -0,0 +1,52 @@
+import { randomUUID } from 'node:crypto';
+import { assertValid } from '../../core/validation.js';
+import { toRunActionRequest, validateActionInput } from './action.js';
+import { toCloseRequest, validateCloseMigration } from './close.js';
+import { toCreateRequest, validateCreateMigration } from './create.js';
+import { DEFAULT_TIMEOUT_MS, hasMoved, pollDelayMs } from './wait.js';
+/** Reuse one idempotency key across retries to avoid applying the same write twice. */
+const write = () => ({
+    headers: { 'idempotency-key': randomUUID() },
+    idempotent: true,
+});
+export const migrations = (http, clock) => ({
+    get: (id) => http.get(`/migrations/${id}`),
+    list: () => http.get('/migrations'),
+    resource: (id, name) => {
+        return http.get(`/migrations/${id}/resources/${name}`);
+    },
+    create: async (input) => {
+        assertValid(validateCreateMigration(input));
+        return http.post('/migrations', toCreateRequest(input), write());
+    },
+    /** Closing does not require an offered action. */
+    close: async (id, input) => {
+        assertValid(validateCloseMigration(input));
+        return http.post(`/migrations/${id}/close`, toCloseRequest(input), write());
+    },
+    /**
+     * Poll until the revision changes or the state leaves running.
+     * Return the last response when the wait budget runs out.
+     */
+    waitFor: async (id, options = {}) => {
+        const deadline = clock.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        let envelope = await http.get(`/migrations/${id}`);
+        const baseline = envelope.migration.revision;
+        while (!hasMoved(envelope, baseline)) {
+            const delayMs = pollDelayMs(envelope);
+            // Stop if the next pause would exceed the deadline.
+            if (clock.now() + delayMs > deadline) {
+                return envelope;
+            }
+            options.onPoll?.(envelope, delayMs);
+            await clock.sleep(delayMs, options.signal);
+            envelope = await http.get(`/migrations/${id}`);
+        }
+        return envelope;
+    },
+    runAction: async (id, actionId, input) => {
+        assertValid(validateActionInput(input.input));
+        const path = `/migrations/${id}/actions/${actionId}`;
+        return http.post(path, toRunActionRequest(input), write());
+    },
+});

package/dist/sdk/adapty/migrations/wait.d.ts

@@ -0,0 +1,6 @@
+import type { Envelope } from './model.js';
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+/** Use the server's delay, with a five-second minimum to avoid rapid polling. */
+export declare const pollDelayMs: (envelope: Envelope) => number;
+/** Unknown states also end the wait. */
+export declare const hasMoved: (envelope: Envelope, baselineRevision: number) => boolean;

package/dist/sdk/adapty/migrations/wait.js

@@ -0,0 +1,9 @@
+const MIN_POLL_SECONDS = 5;
+export const DEFAULT_TIMEOUT_MS = 120_000;
+/** Use the server's delay, with a five-second minimum to avoid rapid polling. */
+export const pollDelayMs = (envelope) => Math.max(envelope.migration.poll_after_seconds, MIN_POLL_SECONDS) * 1000;
+/** Unknown states also end the wait. */
+export const hasMoved = (envelope, baselineRevision) => {
+    const { revision, state } = envelope.migration;
+    return revision !== baselineRevision || state !== 'running';
+};