@xochi/client 0.0.0-stage → 0.1.1

package/dist/cjs/transport/client.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Transport for the Xochi Worker API (`<baseUrl>/api/*`).
+ *
+ * - Quote caching (TTL) and request deduplication
+ * - Retry with exponential backoff, closed to transient gateway statuses
+ * - A per-attempt timeout
+ * - Status polling for in-flight intents (no WebSocket)
+ *
+ * Everything host-specific is injected: the `fetch` implementation, the bearer
+ * token, what to do when the server says a credential is no longer good, and
+ * where log lines go. Nothing here reads a global config, storage or the DOM.
+ *
+ * The Worker speaks the snake_case wire contract; responses are decoded to the
+ * camelCase app types by the same decoders the state machine reads.
+ */
+import type { PreparedClaim } from "@xochi/signer";
+import { type ExecuteRequest, type ExecuteResponse, type IntentRecord, type WithheldIntentRecord, type IntentStatusResult, type QuoteRequest, type QuoteResponse } from "../machine/wire.js";
+export interface TransportTimeouts {
+    /**
+     * Quote cache time-to-live. Must stay below the worker's 30s quote window: at
+     * 30s a cache hit near expiry handed back an about-to-expire quote, and the
+     * ~25s scheduled refresh re-hit the cache and returned the same expiring quote
+     * (every quote dead-ended at "expired"). 15s guarantees the refresh misses.
+     */
+    quoteCacheTtlMs: number;
+    /** Per-attempt timeout for quotes, status and reads. */
+    requestTimeoutMs: number;
+    /**
+     * Execute timeout. Execute runs synchronously through the origin pull + a
+     * ~25s server-side receipt confirmation + settlement, so the request timeout
+     * aborted it while the intent was still settling. 120s guards the slow
+     * cross-chain path.
+     */
+    executeTimeoutMs: number;
+}
+export interface RetryPolicy {
+    /** Total attempts for an idempotent request. */
+    maxAttempts: number;
+    /** First exponential backoff step. */
+    baseDelayMs: number;
+    /** Clamp on a server-supplied `Retry-After` used for internal pacing. */
+    maxDelayMs: number;
+}
+export declare const DEFAULT_TIMEOUTS: TransportTimeouts;
+export declare const DEFAULT_RETRY: RetryPolicy;
+/**
+ * A credential failure the server named. `expired`: a 401 whose body says the
+ * token expired (prompt a fresh login). `invalid`: a 401/403 carrying
+ * `error_category` `auth_invalid` or `wallet_auth_required` on a request that
+ * sent a token (drop the session so the next attempt re-authenticates). A 401
+ * or 403 that names neither is a business rule, not a credential failure.
+ */
+export interface AuthExpiredEvent {
+    reason: "expired" | "invalid";
+    status: number;
+    errorCategory?: string;
+}
+export type TransportLogLevel = "debug" | "warn" | "error";
+export type TransportLogger = (level: TransportLogLevel, message: string, ...data: unknown[]) => void;
+export interface XochiClientOptions {
+    /** API origin, e.g. `https://api.xochi.fi`. Paths are `/api/...` under it. */
+    baseUrl: string;
+    /** Defaults to `globalThis.fetch`. */
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+    /** Bearer token for authenticated calls; absent or null sends none. */
+    getAuthToken?: () => string | null | undefined;
+    /** Called when the server names a credential failure (see AuthExpiredEvent). */
+    onAuthExpired?: (event: AuthExpiredEvent) => void;
+    /** Defaults to warn/error on the console, debug dropped. */
+    log?: TransportLogger;
+    timeouts?: Partial<TransportTimeouts>;
+    retry?: Partial<RetryPolicy>;
+}
+/**
+ * A structured API failure. Carries the numeric HTTP status and, for
+ * backpressure responses (429/503), an ABSOLUTE unix-seconds retry target so the
+ * UI can render a countdown and disable Retry until it elapses. The message is
+ * `HTTP {status}: {body excerpt}` so a code-less consumer can still fall back to
+ * matching on it; the excerpt is capped and read-token redacted (README
+ * "Transport" states the rule).
+ *
+ * A failed execute may still carry the intent read capability (xochi#563: the
+ * server serves it on a 502 when funds may have moved). It is never a property
+ * of the error: take it with `takeApiErrorReadToken`.
+ */
+export declare class ApiError extends Error {
+    readonly code: number;
+    readonly retryAfter?: number;
+    /**
+     * True only on the Worker's not-accepted answer to `execute`
+     * (`isNotAcceptedExecuteBody`), whose `retryAfter` is the server's wait;
+     * false on every other failure, which is never resent. Never true together
+     * with `inDoubt`: an answer that also says funds may have moved is not a
+     * not-accepted answer. Hand it to the machine as `ErrorReport.notAccepted`
+     * (rules: README "Transport").
+     */
+    readonly notAccepted: boolean;
+    /**
+     * Whether this failed `execute` answer cannot vouch that nothing moved for
+     * the executed intent (`isInDoubtExecuteAnswer`): false only on the three
+     * Worker answers that speak for the intent itself, true on every other
+     * execute failure, a refusal of this request alone included (another
+     * request may hold the intent). For the host's own copy and logs; the
+     * machine never reads it (README "Transport"). False on every other call.
+     */
+    readonly inDoubt: boolean;
+    constructor(message: string, code: number, retryAfter?: number, notAccepted?: boolean, inDoubt?: boolean);
+}
+/**
+ * Take the `read_token` of the intent a failed `execute` named, once: a second
+ * call returns undefined. The error is an `ApiError` (a 502 when funds may have
+ * moved) or the `Invalid response format` error of a 2xx execute body whose
+ * other fields broke the contract. Keep it with the intent and poll with it,
+ * exactly as for a successful execute; take it before the error goes to any
+ * reporter. Undefined for any other error, and for a token naming another
+ * intent.
+ */
+export declare function takeApiErrorReadToken(error: unknown): string | undefined;
+/**
+ * Parse a Retry-After header (our API sends integer seconds) into milliseconds,
+ * clamped to [0, maxDelayMs] so a malformed or hostile value can't stall the
+ * client. Returns null when absent/unparseable so the caller falls back to its
+ * own exponential backoff.
+ */
+export declare function parseRetryAfterMs(headerValue: string | null, maxDelayMs?: number): number | null;
+/**
+ * Ceiling on the DERIVED display wait (seconds). Distinct from the internal
+ * backoff clamp: this bounds only the user-facing countdown so a
+ * buggy-but-trusted upstream value (e.g. an absolute epoch mistakenly sent in a
+ * delta-only Retry-After header) cannot produce a multi-decade countdown that
+ * disables Retry until a reload. 10 minutes is far past any legitimate
+ * backpressure window.
+ */
+export declare const MAX_RETRY_WAIT_SEC = 600;
+/**
+ * Resolve the display countdown target (ABSOLUTE unix SECONDS) for a
+ * backpressure response. Distinct from parseRetryAfterMs, which returns clamped
+ * milliseconds for internal retry pacing: a display countdown reflects the full
+ * server-requested wait, bounded only by MAX_RETRY_WAIT_SEC.
+ *
+ * Sources, in priority order:
+ *  - `Retry-After` header: DELTA seconds, converted to absolute (now + delta).
+ *  - `X-RateLimit-Reset` header: already ABSOLUTE unix seconds.
+ *  - `retryAfter` in a JSON body (429 response): already ABSOLUTE unix seconds.
+ *
+ * Returns undefined when no source is present or parseable (so no countdown is
+ * shown and Retry stays enabled).
+ */
+export declare function resolveRetryAfterSeconds(headers: Headers, body: string): number | undefined;
+/**
+ * `POST /api/stealth/claim/prepare` body: the sponsored UserOperation, its hash
+ * and the EntryPoint/chain it was hashed under. Verify it with
+ * `checkPreparedClaim` before signing `userOpHash`.
+ */
+export interface PreparedStealthClaim extends PreparedClaim {
+    success: boolean;
+}
+/** `POST /api/stealth/claim/submit` 200 body. */
+export interface SubmittedStealthClaim {
+    success: boolean;
+    txHash?: string;
+    opHash?: string;
+    blockNumber?: number;
+}
+/**
+ * A single-attempt call's outcome. `errorCategory` is the server's stable key
+ * when it named one (`claim_pending` on a 503 means the op was accepted and not
+ * mined yet: resubmit the SAME body to poll it, never prepare or sign again).
+ */
+export type CallResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+    status?: number;
+    errorCategory?: string;
+    body?: unknown;
+};
+/**
+ * Options for the per-intent reads. `readToken` is the `read_token` the execute
+ * of this intent returned (`ExecuteResponse.readToken`, xochi#563); it is sent
+ * as the `X-Xochi-Read-Token` header so a stealth intent reads with its
+ * on-chain legs (xochi#565, merged as `0317e84`, once deployed). Absent, the
+ * read is anonymous and those legs are omitted; the server answers a wrong
+ * token exactly like an absent one. A token read of a shielded intent gets
+ * only the status-only view, as an anonymous read does (`legsWithheld`: no
+ * Aztec identifiers, tx hashes, tokens, amounts, fees or timestamps;
+ * `substatus` only when it is `not_executed`); only a SIWE session for the
+ * intent's wallet reads its full record (SPEC.md §5.1).
+ */
+export interface IntentReadOptions {
+    readToken?: string;
+}
+/**
+ * An intent read or an `execute` answered by a redirect it may not follow, or
+ * by a response from another origin or naming none (rules: README
+ * "Transport"). `getIntent`, `getIntentHistory` and `execute` reject with it
+ * (an execute refused this way is in doubt); `getIntentStatus` reports it once
+ * per intent and reads again without the token, or returns null when that
+ * read is refused too.
+ */
+export declare class RedirectRefused extends Error {
+    constructor(path: string, reason?: string);
+}
+export interface XochiClient {
+    /** Request a quote. Cached for the TTL (pull-bearing quotes never) and deduplicated. */
+    getQuote(request: QuoteRequest, opts?: {
+        forceRefresh?: boolean;
+    }): Promise<QuoteResponse>;
+    invalidateQuote(request: QuoteRequest): void;
+    clearQuoteCache(): void;
+    /** Execute a signed intent. Single attempt: a failure is in doubt, resolve it by polling status. */
+    execute(request: ExecuteRequest): Promise<ExecuteResponse>;
+    /**
+     * One intent record, or null on a 404. A stealth intent read without its
+     * `readToken`, and a shielded one read without an owner session (token or
+     * not: `IntentReadOptions`), is the status-only
+     * `WithheldIntentRecord` (`legsWithheld: true`); narrow on it before reading
+     * any traded value.
+     */
+    getIntent(intentId: string, opts?: IntentReadOptions): Promise<IntentRecord | WithheldIntentRecord | null>;
+    getIntentStatus(intentId: string, opts?: IntentReadOptions): Promise<IntentStatusResult>;
+    getIntentHistory(wallet: string, limit?: number): Promise<IntentRecord[]>;
+    prepareStealthClaim(body: {
+        counterfactualAddress: string;
+        recipientAddress: string;
+    }): Promise<CallResult<PreparedStealthClaim>>;
+    submitStealthClaim(body: {
+        userOpHash: string;
+        signature: string;
+    }): Promise<CallResult<SubmittedStealthClaim>>;
+}
+export declare function createXochiClient(options: XochiClientOptions): XochiClient;