@storystick/cli 0.0.0-stage → 0.2.0-rc.0

package/dist/auth-device.js

@@ -0,0 +1,390 @@
+/**
+ * CLI device-auth client (SPEC-1 Item #2).
+ *
+ * Standard device-auth flow from the CLI's perspective:
+ *
+ *   1. POST /api/auth/device/start → receive deviceCode + userCode + URL
+ *   2. Print URL + userCode to the terminal
+ *   3. Poll /api/auth/device/poll every 3 seconds with deviceCode
+ *   4. On status=authorized, persist the returned JWT to
+ *      `~/.config/storystick/auth-<issuer-hash>.json` (chmod 600) and return
+ *   5. On status=expired: fail with a clear message
+ *   6. On user Ctrl-C: fail quietly, no token written
+ *
+ * Token file layout (spec §Token storage path):
+ *
+ *   {
+ *     "issuer":    "https://api.storystick.app",
+ *     "token":     "eyJ...",         ← CLI JWT (typ: "cli"), 30d
+ *     "expiresAt": 1735689600000,    ← epoch-ms, matches JWT `exp`
+ *     "userId":    "user_xyz",       ← for info/whoami without a ping
+ *     "email":     "you@…"           ← cached, not security-sensitive
+ *   }
+ *
+ * File location follows XDG:
+ *   - `$XDG_CONFIG_HOME/storystick/auth-<issuer-hash>.json` if set
+ *   - else `~/.config/storystick/auth-<issuer-hash>.json`
+ *
+ * Permissions:
+ *   - Parent dir: 0o700 (user-only read/write/execute)
+ *   - File:       0o600 (user-only read/write)
+ *
+ * This is the sole CLI user-session store. Project API keys remain separate
+ * credentials and never stand in for user authority.
+ */
+import { existsSync, chmodSync, closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, unlinkSync, } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { cliIssuerRequestUrl, DEFAULT_GATEWAY_URL, normalizeCliIssuer, resolveCliRuntimeConfig } from './runtime-config.js';
+import { abortableSleep, fetchWithDeadline } from './transport.js';
+import { StorystickError, storystickErrorFromResponse } from './cli-error.js';
+// ─────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────
+/** 3-second polling cadence — same as Convex CLI / GitHub CLI. */
+const POLL_INTERVAL_MS = 3000;
+// ─────────────────────────────────────────────────────────────
+// Token file location
+// ─────────────────────────────────────────────────────────────
+/**
+ * Resolve the token-file directory per XDG. Public so tests can stub
+ * HOME + XDG env vars and assert the resolved path.
+ */
+export function authDir() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    if (xdg && xdg.length > 0)
+        return join(xdg, 'storystick');
+    return join(homedir(), '.config', 'storystick');
+}
+export function authFilePath(issuer) {
+    const identity = normalizeCliIssuer(issuer);
+    const key = createHash('sha256').update(identity).digest('hex');
+    return join(authDir(), `auth-${key}.json`);
+}
+// ─────────────────────────────────────────────────────────────
+// Reading / writing the token file
+// ─────────────────────────────────────────────────────────────
+/**
+ * Read the cached CLI session. Returns null when:
+ *   - file does not exist
+ *   - file is unreadable (permissions / corruption)
+ *   - JSON is malformed
+ *   - required fields are missing
+ *   - `expiresAt` has passed (local preflight — the Hub is the source of truth)
+ */
+export function getAuthToken(issuer) {
+    const stored = loadAuth(issuer);
+    if (!stored)
+        return null;
+    if (stored.expiresAt <= Date.now())
+        return null;
+    return stored.token;
+}
+/** An unbound/corrupt credential requires a deliberate login, never inference. */
+export function requiresExplicitAuthLogin(issuer) {
+    if (loadAuth(issuer))
+        return false;
+    // Inspect existence only: the legacy credential is never read or migrated.
+    return existsSync(authFilePath(issuer)) || existsSync(join(authDir(), 'auth.json'));
+}
+/**
+ * Lower-level read — returns the whole struct so callers like `whoami`
+ * can display userId/email without re-parsing.
+ */
+export function loadAuth(issuer) {
+    const identity = normalizeCliIssuer(issuer);
+    try {
+        const path = authFilePath(identity);
+        if (!existsSync(path))
+            return null;
+        const raw = readFileSync(path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed.issuer !== identity ||
+            typeof parsed.token !== 'string' || parsed.token.length === 0 ||
+            typeof parsed.expiresAt !== 'number' || !Number.isFinite(parsed.expiresAt) ||
+            typeof parsed.userId !== 'string' || parsed.userId.length === 0) {
+            return null;
+        }
+        return {
+            issuer: identity,
+            token: parsed.token,
+            expiresAt: parsed.expiresAt,
+            userId: parsed.userId,
+            email: typeof parsed.email === 'string' ? parsed.email : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist this issuer’s session atomically. Separate files keep concurrent
+ * logins to different environments from replacing each other. Old unbound
+ * auth.json files are never loaded; their owners must log in again.
+ */
+export function saveAuth(auth, options = {}) {
+    const issuer = normalizeCliIssuer(auth.issuer);
+    const dir = authDir();
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    chmodSync(dir, 0o700);
+    const destination = authFilePath(issuer);
+    const temporary = join(dir, `.auth.${process.pid}.${randomUUID()}.tmp`);
+    let handle;
+    try {
+        handle = openSync(temporary, 'wx', 0o600);
+        writeFileSync(handle, JSON.stringify({ ...auth, issuer }, null, 2), 'utf8');
+        fsyncSync(handle);
+        closeSync(handle);
+        handle = undefined;
+        if (options.faultAt === 'before-rename') {
+            throw new Error('AUTH_SAVE_FAULT_BEFORE_RENAME');
+        }
+        renameSync(temporary, destination);
+        chmodSync(destination, 0o600);
+        fsyncDirectoryBestEffort(dir);
+    }
+    catch (error) {
+        if (handle !== undefined)
+            closeSync(handle);
+        try {
+            if (existsSync(temporary))
+                unlinkSync(temporary);
+        }
+        catch {
+            // Preserve the original write error; stale temp files carry no authority.
+        }
+        throw error;
+    }
+}
+/**
+ * Wipe the token file. Missing file is a no-op — `logout` should always
+ * succeed (same intent as `rm -f`).
+ */
+export async function clearAuthToken(issuer) {
+    const path = authFilePath(issuer);
+    try {
+        if (existsSync(path))
+            unlinkSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+}
+export async function revokeAuthSession(options = {}) {
+    const { gatewayUrl } = resolveCliRuntimeConfig({
+        rootDir: options.rootDir,
+        gatewayUrl: options.gatewayUrl,
+    });
+    const stored = loadAuth(gatewayUrl);
+    if (!stored)
+        return 'not-authenticated';
+    const response = await fetchWithDeadline(cliIssuerRequestUrl(stored.issuer, '/api/cli/session/revoke'), {
+        method: 'POST',
+        redirect: 'error',
+        headers: {
+            Authorization: `Bearer ${stored.token}`,
+            'X-Storystick-Client': 'cli',
+        },
+    }, options);
+    if (!response.ok)
+        throw await storystickErrorFromResponse(response);
+    const receipt = await response.json().catch(() => null);
+    if (!receipt || typeof receipt !== 'object' || receipt.revoked !== true) {
+        throw new StorystickError('The gateway did not confirm CLI session revocation.', {
+            code: 'AUTH_REVOCATION_UNCONFIRMED', category: 'auth', retryable: false,
+        });
+    }
+    return 'revoked';
+}
+export async function logoutAuthSession(options = {}) {
+    const { gatewayUrl } = resolveCliRuntimeConfig(options);
+    if (options.localOnly === true) {
+        await clearAuthToken(gatewayUrl);
+        return 'local-only';
+    }
+    // Deliberate order: remote authority first. If that call fails, the local
+    // credential remains available so the user can retry revocation.
+    const result = await revokeAuthSession({ ...options, gatewayUrl });
+    await clearAuthToken(gatewayUrl);
+    return result;
+}
+/**
+ * Return `{ userId, email }` from the local cache, or null when nothing is
+ * cached (or the cache has expired). Backs `storystick info` / `whoami`.
+ */
+export async function whoami(options = {}) {
+    const stored = loadAuth(resolveCliRuntimeConfig(options).gatewayUrl);
+    if (!stored)
+        return null;
+    if (stored.expiresAt <= Date.now())
+        return null;
+    return { userId: stored.userId, email: stored.email ?? null };
+}
+/**
+ * Drive the full device-auth flow.
+ *
+ * On success: writes `auth.json`, returns the token.
+ * On failure: throws a human-readable `Error`; nothing written.
+ *
+ * The function does NOT print anything directly — printing is the CLI
+ * command's responsibility. This keeps `deviceAuthLogin` testable without
+ * piping stdout around.
+ */
+export async function deviceAuthLogin(options = {}) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    // Precedence: explicit override (CLI flag) > env var > built-in default.
+    // The env vars let devs point the whole flow at a local Hub without
+    // threading flags through every caller (`init`, `link`, `list`, etc.).
+    const { gatewayUrl, hubUrl } = resolveCliRuntimeConfig({
+        rootDir: options.rootDir,
+        gatewayUrl: options.gatewayUrl,
+        hubUrl: options.hubUrl,
+    });
+    if (gatewayUrl !== DEFAULT_GATEWAY_URL && options.gatewayUrl === undefined) {
+        throw new StorystickError(`Explicit login is required for gateway ${gatewayUrl}. Run storystick login --gateway-url with this origin.`, { code: 'AUTH_ISSUER_CONFIRMATION_REQUIRED', category: 'auth', retryable: false });
+    }
+    const pollInterval = options.pollIntervalMs ?? POLL_INTERVAL_MS;
+    // 1. Start the flow.
+    const start = await startDevice(fetchImpl, gatewayUrl, options.deviceName, {
+        signal: options.signal,
+        timeoutMs: options.timeoutMs,
+    });
+    // Replace the server-provided `verificationUrl` with one built from the
+    // configured `hubUrl` so dev environments (where Central's URL points at
+    // the convex.site deployment) still show the user a Hub subdomain they
+    // can click through. The `userCode` is authoritative on Central either way.
+    const displayUrl = buildDisplayUrl(hubUrl, start.userCode);
+    options.onPrompt?.({
+        issuer: gatewayUrl,
+        verificationUrl: displayUrl,
+        userCode: start.userCode,
+        expiresIn: start.expiresIn,
+    });
+    // 2. Poll until authorized / expired / aborted.
+    while (true) {
+        if (options.signal?.aborted) {
+            throw new Error('Login cancelled.');
+        }
+        await abortableSleep(pollInterval, options.signal);
+        options.onPoll?.();
+        const res = await pollDevice(fetchImpl, gatewayUrl, start.deviceCode, {
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+        });
+        if (res.status === 'authorized') {
+            // 3. Decode the signed identity and cache the descriptive email returned
+            // by the same one-shot poll. Email is presentation metadata, not a JWT
+            // authorization claim.
+            const { userId } = decodeCliJwt(res.token);
+            saveAuth({
+                issuer: gatewayUrl,
+                token: res.token,
+                expiresAt: res.expiresAt,
+                userId: userId ?? 'unknown',
+                email: res.email ?? undefined,
+            });
+            return res.token;
+        }
+        if (res.status === 'expired') {
+            throw new Error('Device code expired before approval. Run `storystick login` again.');
+        }
+        if (res.status === 'not-found') {
+            // Shouldn't happen unless the DB was wiped mid-flow. Treat like expired.
+            throw new Error('Device code was not found on the server. Run `storystick login` again.');
+        }
+        // status === 'pending' → keep polling
+    }
+}
+// ─────────────────────────────────────────────────────────────
+// HTTP helpers
+// ─────────────────────────────────────────────────────────────
+async function startDevice(fetchImpl, gatewayUrl, deviceName, options) {
+    const body = {};
+    if (deviceName)
+        body.deviceName = deviceName;
+    const response = await fetchWithDeadline(`${gatewayUrl}/api/auth/device/start`, {
+        method: 'POST',
+        redirect: 'error',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    }, { fetchImpl, signal: options.signal, timeoutMs: options.timeoutMs });
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`Could not start device login (HTTP ${response.status}): ${text.slice(0, 200)}`);
+    }
+    return (await response.json());
+}
+async function pollDevice(fetchImpl, gatewayUrl, deviceCode, options) {
+    const response = await fetchWithDeadline(`${gatewayUrl}/api/auth/device/poll`, {
+        method: 'POST',
+        redirect: 'error',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ deviceCode }),
+    }, { fetchImpl, signal: options.signal, timeoutMs: options.timeoutMs });
+    if (response.status === 429) {
+        // Rate-limited by the server — shouldn't happen at 3s cadence, but treat
+        // as a transient signal rather than a fatal error.
+        return { status: 'pending' };
+    }
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`Poll failed (HTTP ${response.status}): ${text.slice(0, 200)}`);
+    }
+    return (await response.json());
+}
+// ─────────────────────────────────────────────────────────────
+// Small helpers
+// ─────────────────────────────────────────────────────────────
+function buildDisplayUrl(hubUrl, userCode) {
+    // Use `?userCode=` (not `?code=`) because @convex-dev/auth/react reserves
+    // the `code` query param for its OAuth provider callback flow. A URL with
+    // `?code=` triggers Convex-Auth's signIn pipeline, strips the param, and
+    // bypasses the existing-session read — the user gets forced to sign in
+    // again even with a valid cookie. See ADR-041 + investigation 2026-04-22.
+    return `${hubUrl}/device?userCode=${encodeURIComponent(userCode)}`;
+}
+/**
+ * Decode a JWT payload WITHOUT verifying the signature — we trust the Hub
+ * here because we just received the token over HTTPS from it, and the data
+ * we pull out (`userId`) is non-security-sensitive cache metadata. A tampered
+ * token would fail verification on the next API call anyway.
+ */
+function decodeCliJwt(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length < 2)
+            return { userId: null };
+        const payloadJson = base64UrlDecode(parts[1]);
+        const payload = JSON.parse(payloadJson);
+        return {
+            userId: typeof payload.userId === 'string' ? payload.userId : null,
+        };
+    }
+    catch {
+        return { userId: null };
+    }
+}
+function base64UrlDecode(b64url) {
+    const b64 = b64url.replace(/-/g, '+').replace(/_/g, '/').padEnd(b64url.length + ((4 - (b64url.length % 4)) % 4), '=');
+    return Buffer.from(b64, 'base64').toString('utf-8');
+}
+function fsyncDirectoryBestEffort(directory) {
+    let handle;
+    try {
+        handle = openSync(directory, 'r');
+        fsyncSync(handle);
+    }
+    catch {
+        // Some filesystems do not support directory fsync. The file itself has
+        // already been fsynced and atomically renamed.
+    }
+    finally {
+        if (handle !== undefined)
+            closeSync(handle);
+    }
+}

package/dist/bootstrap-client.d.ts

@@ -0,0 +1,52 @@
+type BootstrapOriginMode = 'default-if-empty' | 'append';
+export type CliBootstrapIntent = {
+    kind: 'create';
+    projectName: string;
+    teamShortId?: string;
+    newTeamName?: string;
+    initialLocale: string;
+    initialLocaleLabel: string;
+    initialAllowedOrigins: string[];
+    originMode: 'append';
+} | {
+    kind: 'link';
+    requestedShortId: string;
+    initialAllowedOrigins: string[];
+    originMode: BootstrapOriginMode;
+};
+export interface CliBootstrapReceipt {
+    version: 1;
+    operationId: string;
+    kind: 'create' | 'link';
+    state: 'project_ready' | 'credentials_issued' | 'connection_acknowledged';
+    team?: {
+        shortId: string;
+        name: string;
+    };
+    projectShortId: string;
+    keyPairVersion: number;
+    allowedOrigins: string[];
+    createdAt: number;
+    updatedAt: number;
+    connectionAcknowledgedAt?: number;
+}
+export interface CliBootstrapOptions {
+    rootDir: string;
+    signal?: AbortSignal;
+    onAuthPrompt?: (data: {
+        verificationUrl: string;
+        userCode: string;
+        expiresIn: number;
+    }) => void;
+}
+export declare function prepareCliBootstrap(operationId: string, intent: CliBootstrapIntent, options: CliBootstrapOptions): Promise<{
+    receipt: CliBootstrapReceipt;
+    credentials?: {
+        apiKey: string;
+        publishableKey: string;
+    };
+}>;
+export declare function acknowledgeCliBootstrap(operationId: string, intent: CliBootstrapIntent, keyPairVersion: number, options: CliBootstrapOptions): Promise<{
+    receipt: CliBootstrapReceipt;
+}>;
+export {};

package/dist/bootstrap-client.js

@@ -0,0 +1,19 @@
+import { callHubApi } from './hub-client.js';
+export async function prepareCliBootstrap(operationId, intent, options) {
+    return await callHubApi('/api/cli/bootstrap/prepare', {
+        method: 'POST',
+        body: { operationId, intent },
+        rootDir: options.rootDir,
+        signal: options.signal,
+        onAuthPrompt: options.onAuthPrompt,
+    });
+}
+export async function acknowledgeCliBootstrap(operationId, intent, keyPairVersion, options) {
+    return await callHubApi('/api/cli/bootstrap/ack', {
+        method: 'POST',
+        body: { operationId, intent, keyPairVersion },
+        rootDir: options.rootDir,
+        signal: options.signal,
+        onAuthPrompt: options.onAuthPrompt,
+    });
+}

package/dist/cli-error.d.ts

@@ -0,0 +1,54 @@
+/**
+ * CLI-side error class. Single home for the error shape every CLI throw
+ * funnels into (ADR-072 §D3 + lock A6 — no re-export from hub-client).
+ *
+ * `cause` (lock L4) preserves the original error for downstream
+ * exit-code-2 detection in Batch 7 (e.g. a `TypeError` from `fetch` with
+ * `cause.code === 'ECONNREFUSED'` survives one wrapping into
+ * `StorystickError`).
+ *
+ * `docUrl` (lock F4) reserves the field shape for ADR-077; left
+ * undefined everywhere in v0.
+ */
+export declare class StorystickError extends Error {
+    /** Hub error code (e.g. `UNAUTHENTICATED`, `FORBIDDEN`, `HTTP_500`). */
+    readonly code?: string;
+    /** HTTP status when the error came from a Hub / Pattern D response. */
+    readonly status?: number;
+    readonly retryAfterMs?: number;
+    /** Structured server context for machine-readable recovery UI. */
+    readonly payload?: unknown;
+    /** Stable error category from the shared catalogue. */
+    readonly category?: string;
+    /** Whether retrying after user action can recover. */
+    readonly recoverable?: boolean;
+    /** Whether the same operation may be retried without user action. */
+    readonly retryable?: boolean;
+    /** Stable localization key and interpolation parameters. */
+    readonly messageKey?: string;
+    readonly params?: Record<string, unknown>;
+    /** Support correlation id returned by the gateway. */
+    readonly ref?: string;
+    /** Original error (e.g. fetch's TypeError with cause.code = 'ECONNREFUSED'). */
+    readonly cause?: unknown;
+    /** Documentation URL (reserved per F4 — undefined in v0). */
+    readonly docUrl?: string;
+    constructor(message: string, opts?: {
+        code?: string;
+        status?: number;
+        retryAfterMs?: number;
+        payload?: unknown;
+        category?: string;
+        recoverable?: boolean;
+        retryable?: boolean;
+        messageKey?: string;
+        params?: Record<string, unknown>;
+        ref?: string;
+        cause?: unknown;
+        docUrl?: string;
+    });
+}
+/** Prefix or otherwise replace the message without dropping wire metadata. */
+export declare function rewrapStorystickError(message: string, cause: unknown): StorystickError;
+/** Parse both the canonical `{error:{...}}` envelope and the legacy flat form. */
+export declare function storystickErrorFromResponse(response: Response, fallbackMessage?: string): Promise<StorystickError>;

package/dist/cli-error.js

@@ -0,0 +1,107 @@
+/**
+ * CLI-side error class. Single home for the error shape every CLI throw
+ * funnels into (ADR-072 §D3 + lock A6 — no re-export from hub-client).
+ *
+ * `cause` (lock L4) preserves the original error for downstream
+ * exit-code-2 detection in Batch 7 (e.g. a `TypeError` from `fetch` with
+ * `cause.code === 'ECONNREFUSED'` survives one wrapping into
+ * `StorystickError`).
+ *
+ * `docUrl` (lock F4) reserves the field shape for ADR-077; left
+ * undefined everywhere in v0.
+ */
+export class StorystickError extends Error {
+    /** Hub error code (e.g. `UNAUTHENTICATED`, `FORBIDDEN`, `HTTP_500`). */
+    code;
+    /** HTTP status when the error came from a Hub / Pattern D response. */
+    status;
+    retryAfterMs;
+    /** Structured server context for machine-readable recovery UI. */
+    payload;
+    /** Stable error category from the shared catalogue. */
+    category;
+    /** Whether retrying after user action can recover. */
+    recoverable;
+    /** Whether the same operation may be retried without user action. */
+    retryable;
+    /** Stable localization key and interpolation parameters. */
+    messageKey;
+    params;
+    /** Support correlation id returned by the gateway. */
+    ref;
+    /** Original error (e.g. fetch's TypeError with cause.code = 'ECONNREFUSED'). */
+    cause;
+    /** Documentation URL (reserved per F4 — undefined in v0). */
+    docUrl;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = 'StorystickError';
+        this.code = opts.code;
+        this.status = opts.status;
+        this.retryAfterMs = opts.retryAfterMs;
+        this.payload = opts.payload;
+        this.category = opts.category;
+        this.recoverable = opts.recoverable;
+        this.retryable = opts.retryable;
+        this.messageKey = opts.messageKey;
+        this.params = opts.params;
+        this.ref = opts.ref;
+        this.cause = opts.cause;
+        this.docUrl = opts.docUrl;
+    }
+}
+/** Prefix or otherwise replace the message without dropping wire metadata. */
+export function rewrapStorystickError(message, cause) {
+    const source = cause instanceof StorystickError ? cause : undefined;
+    return new StorystickError(message, {
+        code: source?.code,
+        status: source?.status,
+        retryAfterMs: source?.retryAfterMs,
+        payload: source?.payload,
+        category: source?.category,
+        recoverable: source?.recoverable,
+        retryable: source?.retryable,
+        messageKey: source?.messageKey,
+        params: source?.params,
+        ref: source?.ref,
+        docUrl: source?.docUrl,
+        cause,
+    });
+}
+/** Parse both the canonical `{error:{...}}` envelope and the legacy flat form. */
+export async function storystickErrorFromResponse(response, fallbackMessage = response.statusText || 'Request failed') {
+    const raw = await response.text().catch(() => '');
+    let body = {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            body = parsed;
+    }
+    catch {
+        // Non-JSON response: use HTTP fallbacks below.
+    }
+    const details = body.error && typeof body.error === 'object' ? body.error : body;
+    const retryAfter = response.headers.get('Retry-After');
+    const delay = retryAfter === null ? NaN : /^\d+(\.\d+)?$/.test(retryAfter) ? Number(retryAfter) * 1000 : Date.parse(retryAfter) - Date.now();
+    return new StorystickError(typeof details.message === 'string' ? details.message : typeof body.error === 'string' ? body.error
+        : raw.trim() ? `${fallbackMessage} — ${raw.slice(0, 200).trim()}` : fallbackMessage, {
+        code: typeof details.code === 'string'
+            ? details.code
+            : `HTTP_${response.status}`,
+        status: response.status,
+        retryAfterMs: Number.isFinite(delay) ? Math.max(0, delay) : undefined,
+        payload: details.payload,
+        category: typeof details.category === 'string' ? details.category : undefined,
+        recoverable: typeof details.recoverable === 'boolean'
+            ? details.recoverable
+            : undefined,
+        retryable: typeof details.retryable === 'boolean' ? details.retryable : undefined,
+        messageKey: typeof details.messageKey === 'string' ? details.messageKey : undefined,
+        params: details.params &&
+            typeof details.params === 'object' &&
+            !Array.isArray(details.params)
+            ? details.params
+            : undefined,
+        ref: typeof details.ref === 'string' ? details.ref : undefined,
+    });
+}