adapty 0.8.5 → 0.8.7

package/dist/sdk/core/errors.js

@@ -0,0 +1,84 @@
+/**
+ * Sdk errors carry no user-facing text and no exit code: the adapter assigns both
+ * (src/cli/errors.ts, and a future MCP server).
+ *
+ * Every error has a stable `kind`, and the adapter switches over it. An instanceof chain would
+ * let a new error class fall through to the fallback and become exit 1 with no readable text.
+ */
+/** Abstract on purpose: `new SdkError(...)` would be an error without a kind, unrecognisable. */
+export class SdkError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/** No response at all: DNS, refused connection, a dropped socket. */
+export class NetworkError extends SdkError {
+    kind = 'network';
+    url;
+    constructor(url, cause) {
+        super(`Request to ${url} failed`, { cause });
+        this.url = url;
+    }
+}
+/** The server answered with an error. `code` and `details` follow the service's own format. */
+export class ApiError extends SdkError {
+    kind = 'api';
+    code;
+    details;
+    retryAfterMs;
+    status;
+    constructor(init) {
+        super(init.message);
+        this.status = init.status;
+        this.code = init.code;
+        this.details = init.details;
+        this.retryAfterMs = init.retryAfterMs;
+    }
+}
+export class AuthRequiredError extends SdkError {
+    kind = 'auth_required';
+    reason;
+    constructor(reason) {
+        super(reason === 'missing' ? 'Not authenticated' : 'Token expired or invalid');
+        this.reason = reason;
+    }
+}
+export class CancelledError extends SdkError {
+    kind = 'cancelled';
+    constructor() {
+        super('Operation cancelled');
+    }
+}
+/** A business rule broken before any network call. */
+export class ValidationError extends SdkError {
+    kind = 'validation';
+    issues;
+    constructor(issues) {
+        super(issues.map(issue => (issue.path === undefined ? issue.message : `${issue.path}: ${issue.message}`)).join('; '));
+        this.issues = issues;
+    }
+}
+export class DeviceFlowExpiredError extends SdkError {
+    kind = 'device_flow_expired';
+    constructor() {
+        super('Device code expired before authorization');
+    }
+}
+export class DeviceFlowDeniedError extends SdkError {
+    kind = 'device_flow_denied';
+    constructor() {
+        super('Authorization denied');
+    }
+}
+/** The session file is there but unusable: corrupted JSON, or something else in its place. */
+export class StorageError extends SdkError {
+    kind = 'storage';
+    path;
+    constructor(message, path, options) {
+        super(message, options);
+        this.path = path;
+    }
+}
+export const isSdkError = (error) => error instanceof SdkError;
+export const isAbortError = (error) => error instanceof Error && error.name === 'AbortError';

package/dist/sdk/core/http/client.d.ts

@@ -0,0 +1,46 @@
+import type { Clock } from '../clock.js';
+import type { ErrorParser, ShouldRetry } from './policies.js';
+import type { RetryAttempt, RetryPolicy } from './retry.js';
+import type { QueryParams } from './url.js';
+export type HttpMethod = 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';
+export type RequestOptions = {
+    /** A JSON-serializable value, or FormData for file uploads. */
+    body?: unknown;
+    headers?: Record<string, string> | undefined;
+    /** Retry on 429, 5xx and network errors. On by default for GET only. */
+    idempotent?: boolean | undefined;
+    /** Response headers, e.g. an ETag for optimistic locking. */
+    onResponse?: ((headers: Headers) => void) | undefined;
+    query?: QueryParams | undefined;
+    signal?: AbortSignal | undefined;
+};
+type BodylessOptions = Omit<RequestOptions, 'body'>;
+export type Http = {
+    delete<T>(path: string, options?: BodylessOptions): Promise<T>;
+    get<T>(path: string, options?: BodylessOptions): Promise<T>;
+    patch<T>(path: string, body?: unknown, options?: BodylessOptions): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: BodylessOptions): Promise<T>;
+    put<T>(path: string, body?: unknown, options?: BodylessOptions): Promise<T>;
+    request<T>(method: HttpMethod, path: string, options?: RequestOptions): Promise<T>;
+};
+export type HttpOptions = {
+    baseUrl: string;
+    clock?: Clock | undefined;
+    fetch?: typeof globalThis.fetch | undefined;
+    headers?: Record<string, string> | undefined;
+    onRetry?: ((info: RetryAttempt) => void) | undefined;
+    parseError?: ErrorParser | undefined;
+    retry?: RetryPolicy | undefined;
+    /** When to retry an idempotent request. */
+    shouldRetry?: ShouldRetry | undefined;
+    signal?: AbortSignal | undefined;
+    token?: string | undefined;
+    /** Trailing slash in paths (Django style). On by default. */
+    trailingSlash?: boolean | undefined;
+};
+/**
+ * The transport: base URL, bearer token, JSON both ways, responses mapped to sdk errors,
+ * retry for idempotent requests. It knows nothing about resources or about the CLI.
+ */
+export declare const createHttp: (options: HttpOptions) => Http;
+export {};

package/dist/sdk/core/http/client.js

@@ -0,0 +1,127 @@
+import { systemClock } from '../clock.js';
+import { ApiError, AuthRequiredError, CancelledError, isAbortError, NetworkError } from '../errors.js';
+import { defaultErrorParser, defaultShouldRetry } from './policies.js';
+import { defaultRetryPolicy, retry } from './retry.js';
+import { buildUrl } from './url.js';
+/**
+ * The transport: base URL, bearer token, JSON both ways, responses mapped to sdk errors,
+ * retry for idempotent requests. It knows nothing about resources or about the CLI.
+ */
+export const createHttp = (options) => {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const clock = options.clock ?? systemClock;
+    const policy = options.retry ?? defaultRetryPolicy;
+    const shouldRetry = options.shouldRetry ?? defaultShouldRetry;
+    const parseError = options.parseError ?? defaultErrorParser;
+    const trailingSlash = options.trailingSlash ?? true;
+    const send = async (method, path, req) => {
+        const url = buildUrl(options.baseUrl, path, req.query, trailingSlash);
+        const signal = combineSignals(options.signal, req.signal);
+        const headers = new Headers({ accept: 'application/json', ...options.headers, ...req.headers });
+        if (options.token !== undefined) {
+            headers.set('authorization', `Bearer ${options.token}`);
+        }
+        const init = { headers, method };
+        if (req.body instanceof FormData) {
+            init.body = req.body;
+        }
+        else if (req.body !== undefined) {
+            headers.set('content-type', 'application/json');
+            init.body = JSON.stringify(req.body);
+        }
+        if (signal) {
+            init.signal = signal;
+        }
+        let response;
+        try {
+            response = await fetchImpl(url, init);
+        }
+        catch (error) {
+            if (signal?.aborted === true || isAbortError(error)) {
+                throw new CancelledError();
+            }
+            throw new NetworkError(url, error);
+        }
+        req.onResponse?.(response.headers);
+        // fetch resolves at the headers; reading the body can still fail or be cancelled.
+        // Keep the caller's onResponse callback outside this network-error conversion.
+        let payload;
+        try {
+            payload = await readBody(response);
+        }
+        catch (error) {
+            if (signal?.aborted === true || isAbortError(error)) {
+                throw new CancelledError();
+            }
+            throw new NetworkError(url, error);
+        }
+        if (response.ok) {
+            return payload;
+        }
+        if (response.status === 401) {
+            throw new AuthRequiredError('rejected');
+        }
+        const parsed = parseError(response.status, payload);
+        throw new ApiError({
+            code: parsed.code ?? `http_${response.status}`,
+            details: payload,
+            message: parsed.message ?? `${method} ${path} failed with HTTP ${response.status}`,
+            retryAfterMs: parseRetryAfter(response.headers.get('retry-after'), clock),
+            status: response.status,
+        });
+    };
+    const request = (method, path, req = {}) => {
+        const idempotent = req.idempotent ?? method === 'GET';
+        if (!idempotent) {
+            return send(method, path, req);
+        }
+        return retry(() => send(method, path, req), {
+            clock,
+            onRetry: options.onRetry,
+            policy,
+            shouldRetry,
+            signal: combineSignals(options.signal, req.signal),
+        });
+    };
+    return {
+        request,
+        delete: (path, req) => request('DELETE', path, req),
+        get: (path, req) => request('GET', path, req),
+        patch: (path, body, req) => request('PATCH', path, { ...req, body }),
+        post: (path, body, req) => request('POST', path, { ...req, body }),
+        put: (path, body, req) => request('PUT', path, { ...req, body }),
+    };
+};
+const combineSignals = (...signals) => {
+    const present = signals.filter((signal) => signal !== undefined);
+    if (present.length <= 1) {
+        return present[0];
+    }
+    return AbortSignal.any(present);
+};
+const readBody = async (response) => {
+    if (response.status === 204) {
+        return undefined;
+    }
+    const text = await response.text();
+    if (text.length === 0) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+};
+const parseRetryAfter = (header, clock) => {
+    if (header === null) {
+        return undefined;
+    }
+    const seconds = Number(header);
+    if (Number.isFinite(seconds)) {
+        return Math.max(0, seconds * 1000);
+    }
+    const date = Date.parse(header);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - clock.now());
+};

package/dist/sdk/core/http/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The transport as a module: one door out. An eslint zone fences off the internals (client,
+ * policies, retry, url), so they can be rearranged without touching products.
+ */
+export { createHttp } from './client.js';
+export type { Http, HttpMethod, HttpOptions, RequestOptions } from './client.js';
+export { defaultErrorParser, defaultShouldRetry } from './policies.js';
+export type { ErrorParser, ShouldRetry } from './policies.js';
+export { defaultRetryPolicy, retry } from './retry.js';
+export type { RetryAttempt, RetryDecision, RetryOptions, RetryPolicy } from './retry.js';
+export type { QueryParams, QueryValue } from './url.js';

package/dist/sdk/core/http/index.js

@@ -0,0 +1,7 @@
+/**
+ * The transport as a module: one door out. An eslint zone fences off the internals (client,
+ * policies, retry, url), so they can be rearranged without touching products.
+ */
+export { createHttp } from './client.js';
+export { defaultErrorParser, defaultShouldRetry } from './policies.js';
+export { defaultRetryPolicy, retry } from './retry.js';

package/dist/sdk/core/http/policies.d.ts

@@ -0,0 +1,14 @@
+import type { RetryDecision } from './retry.js';
+/** How to pull code and message out of an error body. Developer API and ASA differ, so it is a parameter. */
+export type ErrorParser = (status: number, body: unknown) => {
+    code?: string | undefined;
+    message?: string | undefined;
+};
+export type ShouldRetry = (error: unknown, attempt: number) => RetryDecision;
+/** Default: network errors with backoff, 429 and 5xx after the delay the server asked for, if any. */
+export declare const defaultShouldRetry: ShouldRetry;
+/**
+ * The default error format, tolerant of the three common body shapes:
+ * { error: 'code', error_description }, { error: { code, message } }, { code, message | detail }.
+ */
+export declare const defaultErrorParser: ErrorParser;

package/dist/sdk/core/http/policies.js

@@ -0,0 +1,29 @@
+import { ApiError, NetworkError } from '../errors.js';
+/** Default: network errors with backoff, 429 and 5xx after the delay the server asked for, if any. */
+export const defaultShouldRetry = (error) => {
+    if (error instanceof NetworkError) {
+        return {};
+    }
+    if (error instanceof ApiError && (error.status === 429 || error.status >= 500)) {
+        return { delayMs: error.retryAfterMs };
+    }
+    return false;
+};
+/**
+ * The default error format, tolerant of the three common body shapes:
+ * { error: 'code', error_description }, { error: { code, message } }, { code, message | detail }.
+ */
+export const defaultErrorParser = (_status, body) => {
+    if (!isRecord(body)) {
+        return {};
+    }
+    if (typeof body.error === 'string') {
+        return { code: body.error, message: asString(body.error_description ?? body.message) };
+    }
+    if (isRecord(body.error)) {
+        return { code: asString(body.error.code), message: asString(body.error.message) };
+    }
+    return { code: asString(body.code), message: asString(body.message ?? body.detail) };
+};
+const isRecord = (value) => typeof value === 'object' && value !== null;
+const asString = (value) => (typeof value === 'string' ? value : undefined);

package/dist/sdk/core/http/retry.d.ts

@@ -0,0 +1,27 @@
+import type { Clock } from '../clock.js';
+export type RetryPolicy = {
+    /** Total attempts, the first one included. */
+    attempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+};
+export declare const defaultRetryPolicy: RetryPolicy;
+/** false: do not retry. An object: retry, optionally after the delay the server suggested. */
+export type RetryDecision = false | {
+    delayMs?: number | undefined;
+};
+export type RetryAttempt = {
+    /** Number of the failed attempt, starting at 1. */
+    attempt: number;
+    delayMs: number;
+    error: unknown;
+};
+export type RetryOptions = {
+    clock: Clock;
+    /** Called before the pause. The sdk never prints: cli warns, MCP stays quiet. */
+    onRetry?: ((info: RetryAttempt) => void) | undefined;
+    policy: RetryPolicy;
+    shouldRetry: (error: unknown, attempt: number) => RetryDecision;
+    signal?: AbortSignal | undefined;
+};
+export declare const retry: <T>(fn: () => Promise<T>, options: RetryOptions) => Promise<T>;

package/dist/sdk/core/http/retry.js

@@ -0,0 +1,22 @@
+import { throwIfAborted } from '../clock.js';
+export const defaultRetryPolicy = { attempts: 3, baseDelayMs: 500, maxDelayMs: 8000 };
+export const retry = async (fn, options) => {
+    const { clock, policy, signal } = options;
+    for (let attempt = 1;; attempt += 1) {
+        throwIfAborted(signal);
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const decision = attempt < policy.attempts ? options.shouldRetry(error, attempt) : false;
+            if (decision === false) {
+                throw error;
+            }
+            const delayMs = decision.delayMs ?? backoffDelay(policy, attempt);
+            options.onRetry?.({ attempt, delayMs, error });
+            await clock.sleep(delayMs, signal);
+        }
+    }
+};
+/** Exponential backoff without jitter: deterministic tests are worth more than spread here. */
+const backoffDelay = (policy, attempt) => Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** (attempt - 1));

package/dist/sdk/core/http/url.d.ts

@@ -0,0 +1,3 @@
+export type QueryValue = boolean | number | readonly string[] | string | undefined;
+export type QueryParams = Record<string, QueryValue>;
+export declare const buildUrl: (baseUrl: string, path: string, query: QueryParams | undefined, trailingSlash: boolean) => string;

package/dist/sdk/core/http/url.js

@@ -0,0 +1,19 @@
+export const buildUrl = (baseUrl, path, query, trailingSlash) => {
+    // A relative path against a base ending in a slash keeps a prefix like /api/v1/developer
+    const base = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+    let relative = path.replace(/^\/+/, '');
+    if (trailingSlash && relative !== '' && !relative.endsWith('/')) {
+        relative += '/';
+    }
+    const url = new URL(relative, base);
+    for (const [key, value] of Object.entries(query ?? {})) {
+        if (value === undefined) {
+            continue;
+        }
+        const items = typeof value === 'object' ? value : [value];
+        for (const item of items) {
+            url.searchParams.append(key, String(item));
+        }
+    }
+    return url.toString();
+};

package/dist/sdk/core/session.d.ts

@@ -0,0 +1,20 @@
+export type SessionUser = {
+    email: string;
+    name: string;
+};
+export type Session = {
+    token: string;
+    user?: SessionUser | undefined;
+};
+/**
+ * Where the session lives is a port, not a path: a keychain, a CI secret store or an in-memory
+ * store for an MCP server plug into this same type without touching a command.
+ */
+export type SessionStore = {
+    clear(): Promise<void>;
+    load(): Promise<Session | undefined>;
+    readonly path: string;
+    save(session: Session): Promise<void>;
+};
+/** A file under a directory the adapter picks: the sdk touches neither HOME nor process.env. */
+export declare const createFileSessionStore: (dir: string) => SessionStore;

package/dist/sdk/core/session.js

@@ -0,0 +1,69 @@
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { StorageError } from './errors.js';
+/**
+ * The file and field names the published CLI already writes. A rename would log every existing
+ * user out, so the on-disk contract stays `{ "access_token", "user": { "email", "name" } }`.
+ */
+const FILE_NAME = 'config.json';
+/** A file under a directory the adapter picks: the sdk touches neither HOME nor process.env. */
+export const createFileSessionStore = (dir) => {
+    const path = join(dir, FILE_NAME);
+    return {
+        path,
+        clear: async () => {
+            await rm(path, { force: true });
+        },
+        load: async () => {
+            let raw;
+            try {
+                raw = await readFile(path, 'utf8');
+            }
+            catch (error) {
+                if (isErrno(error, 'ENOENT')) {
+                    return undefined;
+                }
+                // No permission, a broken disk: not ours to paper over as "not logged in"
+                throw error;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (error) {
+                throw new StorageError(`Session file is corrupted: ${path}`, path, { cause: error });
+            }
+            // An unknown shape is most likely a file from another version: asking for a fresh
+            // login beats failing every command.
+            return toSession(parsed);
+        },
+        save: async (session) => {
+            await mkdir(dir, { recursive: true, mode: 0o700 });
+            await writeFile(path, `${JSON.stringify(toStored(session), null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+            // `mode` above applies only when the file is created; an existing 0644 one (a hand
+            // edit, a restored backup) would leave the token readable for everyone on the machine.
+            await chmod(path, 0o600);
+        },
+    };
+};
+const toStored = (session) => (session.user === undefined
+    ? { access_token: session.token }
+    : { access_token: session.token, user: session.user });
+/** Not a full schema check: only the minimum the rest of the code leans on. */
+const toSession = (parsed) => {
+    const record = asRecord(parsed);
+    if (record === undefined || typeof record.access_token !== 'string' || record.access_token === '') {
+        return undefined;
+    }
+    const user = toUser(record.user);
+    return user === undefined ? { token: record.access_token } : { token: record.access_token, user };
+};
+const toUser = (value) => {
+    const record = asRecord(value);
+    if (record === undefined || typeof record.email !== 'string' || typeof record.name !== 'string') {
+        return undefined;
+    }
+    return { email: record.email, name: record.name };
+};
+const asRecord = (value) => (typeof value === 'object' && value !== null ? value : undefined);
+const isErrno = (error, code) => error instanceof Error && 'code' in error && error.code === code;

package/dist/sdk/core/testing.d.ts

@@ -0,0 +1,25 @@
+import type { Clock } from './clock.js';
+export type FakeClock = {
+    advance(ms: number): void;
+    /** Durations of every sleep, in order. */
+    readonly sleeps: number[];
+} & Clock;
+/** A clock whose sleep moves time forward instantly. */
+export declare const createFakeClock: (start?: number) => FakeClock;
+export type ScriptedResponse = {
+    body?: unknown;
+    headers?: Record<string, string>;
+    status?: number;
+};
+export type RecordedCall = {
+    body: string | undefined;
+    headers: Headers;
+    method: string;
+    url: string;
+};
+export type ScriptedFetch = {
+    calls: RecordedCall[];
+    fetch: typeof globalThis.fetch;
+};
+/** Answers with the scripted responses in order; an Error in the script is thrown, as fetch would. */
+export declare const createScriptedFetch: (script: readonly (Error | ScriptedResponse)[]) => ScriptedFetch;

package/dist/sdk/core/testing.js

@@ -0,0 +1,46 @@
+/** Fakes for the sdk and its consumers: cli, MCP and any other adapter test with the same tools. */
+import { throwIfAborted } from './clock.js';
+/** A clock whose sleep moves time forward instantly. */
+export const createFakeClock = (start = 0) => {
+    let time = start;
+    const sleeps = [];
+    return {
+        sleeps,
+        now: () => time,
+        advance: (ms) => {
+            time += ms;
+        },
+        sleep: (ms, signal) => {
+            throwIfAborted(signal);
+            sleeps.push(ms);
+            time += ms;
+            return Promise.resolve();
+        },
+    };
+};
+/** Answers with the scripted responses in order; an Error in the script is thrown, as fetch would. */
+export const createScriptedFetch = (script) => {
+    const queue = [...script];
+    const calls = [];
+    const fetch = (input, init) => {
+        calls.push({
+            body: typeof init?.body === 'string' ? init.body : undefined,
+            headers: new Headers(init?.headers),
+            method: init?.method ?? 'GET',
+            url: String(input instanceof Request ? input.url : input),
+        });
+        const next = queue.shift();
+        if (next === undefined) {
+            return Promise.reject(new Error(`scripted fetch: no response for call #${calls.length}`));
+        }
+        if (next instanceof Error) {
+            return Promise.reject(next);
+        }
+        // ResponseInit.headers is readonly in @types/node, so the init is built in one go
+        const status = next.status ?? 200;
+        const responseInit = next.headers ? { headers: next.headers, status } : { status };
+        const body = next.body === undefined ? null : JSON.stringify(next.body);
+        return Promise.resolve(new Response(body, responseInit));
+    };
+    return { calls, fetch };
+};

package/dist/sdk/core/validation.d.ts

@@ -0,0 +1,10 @@
+import type { Issue } from './errors.js';
+/**
+ * Turns a rule's problems into a throw — the only place that does. Rules return lists instead of
+ * throwing, so a table test walks them without an environment and the user sees every problem at
+ * once.
+ *
+ * Call it from an `async` method: a broken rule then arrives as a rejected promise, like a network
+ * failure, instead of a throw the caller has to handle separately.
+ */
+export declare const assertValid: (issues: readonly Issue[]) => void;

package/dist/sdk/core/validation.js

@@ -0,0 +1,14 @@
+import { ValidationError } from './errors.js';
+/**
+ * Turns a rule's problems into a throw — the only place that does. Rules return lists instead of
+ * throwing, so a table test walks them without an environment and the user sees every problem at
+ * once.
+ *
+ * Call it from an `async` method: a broken rule then arrives as a rejected promise, like a network
+ * failure, instead of a throw the caller has to handle separately.
+ */
+export const assertValid = (issues) => {
+    if (issues.length > 0) {
+        throw new ValidationError(issues);
+    }
+};