@totalis/hip4-client 0.0.0-stage → 0.73.0

package/dist/money.js

@@ -0,0 +1,66 @@
+const bps = 10000n;
+/**
+ * Spendable Totalis cash from `GET /v1/me/balances`, in USDC base units, as
+ * the SDK plans entries and withdrawals with it. `null` means unknown (the
+ * component is not `CURRENT`), never 0: show it as unknown and read again.
+ * - `vault`: free vault cash (`VAULT_FREE`).
+ * - `wallet`: wallet USDC (`WALLET_USDC`) less `pending.wallet_reserved`
+ *   (open withdrawals, stake fundings and wallet deposits not yet committed),
+ *   floored at 0.
+ * - `total`: the venue's spendable `amount`; it subtracts withdrawals and
+ *   stake fundings but not a pending wallet deposit, which moves into the
+ *   vault, so it can exceed `vault + wallet` while a deposit is pending.
+ */
+export function spendableCash(balance) {
+    const component = (kind) => {
+        const entry = balance.components.find((candidate) => candidate.kind === kind);
+        return entry === undefined || entry.state !== "CURRENT" || entry.amount === null ? null : BigInt(entry.amount);
+    };
+    const walletUsdc = component("WALLET_USDC");
+    // As the venue computes it: reservations beyond the wallet leave nothing available, never less.
+    const wallet = walletUsdc === null ? null : walletUsdc - BigInt(balance.pending.wallet_reserved);
+    return {
+        vault: component("VAULT_FREE"),
+        wallet: wallet === null ? null : wallet > 0n ? wallet : 0n,
+        total: balance.state === "CURRENT" && balance.amount !== null ? BigInt(balance.amount) : null,
+    };
+}
+/**
+ * What the owner receives from a gross close amount (a settlement payout or a
+ * sell-back price), as the vault pays it: the profit fee is
+ * `floor((amount - netStake) * feeBps / 10000)` on the part above the
+ * position's net stake, and nothing at or below it. `feeBps` and `netStake`
+ * are the position's own (`fee_bps`, `net_stake`), fixed when it opened.
+ */
+export function netOfProfitFee(amount, netStake, feeBps) {
+    const gross = BigInt(amount);
+    const profit = gross - BigInt(netStake);
+    return profit > 0n ? gross - profit * BigInt(feeBps) / bps : gross;
+}
+/** A quote's net stake: the stake less the entry fee, `floor(stake * taker_fee_bps / 10000)`. */
+export function netStake(terms) {
+    const stake = BigInt(terms.stake);
+    return stake - stake * BigInt(terms.taker_fee_bps) / bps;
+}
+/**
+ * What the taker receives if every leg wins, net of the profit fee: the
+ * figure to show next to an entry quote, whose `payout` is gross. A fractional
+ * or partial result pays less; `netOfProfitFee` applies to whatever the
+ * position settles at. Example: stake 3 USDC at 20 bps entry fee and payout
+ * 9.18 USDC at 100 bps profit fee nets 9.118140 USDC.
+ */
+export function netPayout(quote) {
+    const terms = "entry" in quote ? quote.entry : quote;
+    return netOfProfitFee(terms.payout, netStake(terms), terms.fee_bps);
+}
+/**
+ * What the owner receives from a cash-out quote. A `TRANSFER` pays its price
+ * in full; a `SELL_BACK` withholds the position's profit fee on the price
+ * above its net stake. `position` is the position read (`GET
+ * /v1/me/positions/{position_id}`); `null` when its `net_stake` is unknown.
+ */
+export function netCashout(bid, position) {
+    if (bid.kind === "TRANSFER")
+        return BigInt(bid.transfer.price);
+    return position.net_stake === null ? null : netOfProfitFee(bid.sell_back.price, position.net_stake, position.fee_bps);
+}

package/dist/operator.d.ts

@@ -0,0 +1,4 @@
+import { type ClientOptions } from "openapi-fetch";
+import type { paths } from "./generated/operator.js";
+export type { components, operations, paths } from "./generated/operator.js";
+export declare function createOperatorClient(privateOrigin: string, options?: Omit<ClientOptions, "baseUrl">): import("openapi-fetch").Client<paths, `${string}/${string}`>;

package/dist/operator.js

@@ -0,0 +1,4 @@
+import createOpenApiClient from "openapi-fetch";
+export function createOperatorClient(privateOrigin, options = {}) {
+    return createOpenApiClient({ ...options, baseUrl: privateOrigin });
+}

package/dist/pagination.d.ts

@@ -0,0 +1,20 @@
+/** A list response in the TT-1771 shape: items plus top-level `next_cursor` and `has_more`. */
+export type Page = {
+    readonly next_cursor: string | null;
+    readonly has_more: boolean;
+};
+/** Spread into the query of a list read; the first page omits `cursor`. */
+export type PageQuery = {
+    cursor?: string;
+};
+/**
+ * Read a list page by page: the first request omits `cursor`, each later one
+ * sends the previous `next_cursor` unchanged, until `has_more` is false. A page
+ * may be empty while `has_more` is true.
+ *
+ * ```ts
+ * for await (const page of pages((query) => client.GET("/v1/me/positions", { params: { query: { ...query, limit: 100 } } }).then(unwrap))) …
+ * ```
+ */
+export declare function pages<P extends Page>(read: (query: PageQuery) => Promise<P>): AsyncGenerator<P, void>;
+export declare function items<P extends Page, Item>(read: (query: PageQuery) => Promise<P>, select: (page: P) => readonly Item[]): AsyncGenerator<Item, void>;

package/dist/pagination.js

@@ -0,0 +1,27 @@
+/**
+ * Read a list page by page: the first request omits `cursor`, each later one
+ * sends the previous `next_cursor` unchanged, until `has_more` is false. A page
+ * may be empty while `has_more` is true.
+ *
+ * ```ts
+ * for await (const page of pages((query) => client.GET("/v1/me/positions", { params: { query: { ...query, limit: 100 } } }).then(unwrap))) …
+ * ```
+ */
+export async function* pages(read) {
+    const seen = new Set();
+    let query = {};
+    for (;;) {
+        const page = await read(query);
+        yield page;
+        if (!page.has_more)
+            return;
+        if (page.next_cursor === null || seen.has(page.next_cursor))
+            throw new Error("list says has_more without a new next_cursor");
+        seen.add(page.next_cursor);
+        query = { cursor: page.next_cursor };
+    }
+}
+export async function* items(read, select) {
+    for await (const page of pages(read))
+        yield* select(page);
+}

package/dist/partner.d.ts

@@ -0,0 +1,71 @@
+import { type ApiClientOptions, type PublicEnvironment } from "./base.js";
+import type { components } from "./generated/client.js";
+import { type SignerInput } from "./signer.js";
+export type WalletAdmission = components["schemas"]["WalletAdmission"];
+/** Your partner's fees, terms, balance and payouts (TT-2420). Amounts are atomic USDC strings. */
+export type PartnerReport = components["schemas"]["PartnerReport"];
+/** A wallet's signed consent to one partner opening its account (TT-1688). */
+export type AdmissionConsent = {
+    readonly expires_at: string;
+    readonly signature: string;
+};
+/**
+ * The exact message a wallet signs (personal_sign) to let `partner`, your
+ * partner slug, open its Totalis account. The venue rebuilds the same text from
+ * your server key and refuses a consent for another partner, wallet,
+ * environment or chain, or one expired or more than a day ahead.
+ */
+export declare function admissionConsentMessage(terms: {
+    readonly partner: string;
+    readonly wallet: string;
+    readonly environment: PublicEnvironment;
+    readonly chainId: string;
+    readonly expiresAt: string;
+}): string;
+/**
+ * Have the wallet consent to your partner opening its account, in your
+ * frontend before sign-up. Send the result to your server for `admitWallet`.
+ * `chainId` is `GET /v1/deployment` `chain_id`. The consent lasts an hour by
+ * default (at most a day).
+ */
+export declare function signAdmissionConsent(request: {
+    readonly signer: SignerInput;
+    readonly partner: string;
+    readonly environment: PublicEnvironment;
+    readonly chainId: string;
+    readonly lifetimeSeconds?: number;
+}): Promise<{
+    readonly address: string;
+    readonly consent: AdmissionConsent;
+}>;
+export type PartnerServerOptions = Omit<ApiClientOptions, "accessToken" | "partnerKey"> & {
+    readonly environment: PublicEnvironment;
+    /** The partner's secret server key (`tpk_v1_…`). Keep it on your server; never ship it to a browser. */
+    readonly serverKey: string;
+};
+/**
+ * The partner's server calls (TT-1678). During the invite-only launch a new
+ * wallet gets an account only through a partner: admit it here with the
+ * wallet's consent (`signAdmissionConsent` in your frontend), and its next
+ * wallet sign-in creates the account, attributed to you. `report` reads your
+ * fees, terms and payouts (TT-2420). Refuses to run in a browser, where the
+ * server key would be exposed.
+ */
+export declare function createPartnerServer(options: PartnerServerOptions): {
+    /**
+     * Admit a consenting wallet. Admitting it again returns the first admission;
+     * another partner's wallet is STATE_CONFLICT, and a consent that does not
+     * verify is INVALID_SIGNATURE.
+     */
+    admitWallet(address: string, consent: AdmissionConsent, idempotencyKey?: string): Promise<WalletAdmission>;
+    /**
+     * Your report: fees per UTC day for `[from, to)` (YYYY-MM-DD, at most 366
+     * days; omit both for the 30 days through today), with your terms and,
+     * all time, what you earned, were paid and are owed, and every payout.
+     */
+    report(range?: {
+        readonly from: string;
+        readonly to: string;
+    }): Promise<PartnerReport>;
+};
+export type PartnerServer = ReturnType<typeof createPartnerServer>;

package/dist/partner.js

@@ -0,0 +1,66 @@
+import { audienceClient } from "./base.js";
+import { unwrap, uuidv7 } from "./request.js";
+import { toTotalisSigner } from "./signer.js";
+/** The key environment a consent names, from the SDK's environment. */
+const keyEnvironment = { production: "production", staging: "staging", local: "development" };
+/**
+ * The exact message a wallet signs (personal_sign) to let `partner`, your
+ * partner slug, open its Totalis account. The venue rebuilds the same text from
+ * your server key and refuses a consent for another partner, wallet,
+ * environment or chain, or one expired or more than a day ahead.
+ */
+export function admissionConsentMessage(terms) {
+    return `Allow ${terms.partner} to open a Totalis account for this wallet.\nThis does not authorize a financial action.\n\n`
+        + `Wallet: ${terms.wallet.toLowerCase()}\nPartner: ${terms.partner}\nEnvironment: ${keyEnvironment[terms.environment]}\nChain ID: ${terms.chainId}\nExpires At: ${terms.expiresAt}`;
+}
+/**
+ * Have the wallet consent to your partner opening its account, in your
+ * frontend before sign-up. Send the result to your server for `admitWallet`.
+ * `chainId` is `GET /v1/deployment` `chain_id`. The consent lasts an hour by
+ * default (at most a day).
+ */
+export async function signAdmissionConsent(request) {
+    const signer = toTotalisSigner(request.signer);
+    const address = (await signer.address()).toLowerCase();
+    // The venue verifies the expiry exactly as sent; whole seconds keep it short.
+    const expiresAt = new Date(Math.floor(Date.now() / 1000) * 1000 + (request.lifetimeSeconds ?? 3600) * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+    const message = admissionConsentMessage({ partner: request.partner, wallet: address, environment: request.environment, chainId: request.chainId, expiresAt });
+    return { address, consent: { expires_at: expiresAt, signature: await signer.signMessage(message) } };
+}
+/**
+ * The partner's server calls (TT-1678). During the invite-only launch a new
+ * wallet gets an account only through a partner: admit it here with the
+ * wallet's consent (`signAdmissionConsent` in your frontend), and its next
+ * wallet sign-in creates the account, attributed to you. `report` reads your
+ * fees, terms and payouts (TT-2420). Refuses to run in a browser, where the
+ * server key would be exposed.
+ */
+export function createPartnerServer(options) {
+    if (typeof globalThis.document !== "undefined") {
+        throw new Error("createPartnerServer runs on your server; a browser would expose the tpk_ server key");
+    }
+    const { environment, serverKey, ...clientOptions } = options;
+    if (!serverKey.startsWith("tpk_v1_"))
+        throw new Error("serverKey is not a tpk_v1 partner server key");
+    const client = audienceClient(environment, { ...clientOptions, accessToken: serverKey });
+    return {
+        /**
+         * Admit a consenting wallet. Admitting it again returns the first admission;
+         * another partner's wallet is STATE_CONFLICT, and a consent that does not
+         * verify is INVALID_SIGNATURE.
+         */
+        async admitWallet(address, consent, idempotencyKey = uuidv7()) {
+            return unwrap(await client.POST("/v1/partner/wallet-admissions", {
+                params: { header: { "Idempotency-Key": idempotencyKey } }, body: { address, consent },
+            }));
+        },
+        /**
+         * Your report: fees per UTC day for `[from, to)` (YYYY-MM-DD, at most 366
+         * days; omit both for the 30 days through today), with your terms and,
+         * all time, what you earned, were paid and are owed, and every payout.
+         */
+        async report(range) {
+            return unwrap(await client.GET("/v1/partner/report", { params: { query: range ?? {} } }));
+        },
+    };
+}

package/dist/realtime.d.ts

@@ -0,0 +1,19 @@
+export { publicStreamServers, streamServerUrl } from "./base.js";
+import type { PublicEnvironment } from "./base.js";
+export type { components } from "./generated/realtime.js";
+export type { CloseReason as RealtimeCloseReason } from "./generated/errors.js";
+import type { components } from "./generated/realtime.js";
+export { marketStreamProtocol, marketStreamUrl, realtimeCredentialProtocol, realtimeProtocol, realtimeUrl, StreamClosedError, TotalisStream, type RealtimeCursor, type StreamEvent, type StreamEventFrame, type StreamEventOf, type StreamEventType, type StreamFrame, type StreamOptions, type StreamSnapshot, type StreamStatus, type StreamSubscription, type WebSocketFactory, } from "./stream.js";
+export type RealtimeSubscribe = components["schemas"]["Subscribe"];
+export type RealtimeSubscriptionResponse = components["schemas"]["SubscriptionResponse"];
+export type RealtimeSnapshot = components["schemas"]["SnapshotFrame"];
+export type RealtimeEvent = components["schemas"]["EventFrame"];
+export type RealtimeReset = components["schemas"]["ResetFrame"];
+export type RealtimeDrain = components["schemas"]["DrainFrame"];
+export type RealtimeMarketRefresh = components["schemas"]["MarketRefresh"];
+export type RealtimePublication = components["schemas"]["PublicationFrame"];
+export type RealtimeReadInvalidation = components["schemas"]["ReadInvalidatedFrame"];
+export type RealtimeFrame = RealtimeReadInvalidation | RealtimePublication | RealtimeSubscriptionResponse | RealtimeSnapshot | RealtimeEvent | RealtimeReset | RealtimeDrain | RealtimeMarketRefresh;
+type WebSocketConstructor = new (url: string, protocols?: string | string[]) => WebSocket;
+/** A raw socket with the reviewed subprotocols. `TotalisStream` adds the subscribe frame, replay and reconnect. */
+export declare function createRealtimeSocket(environment: PublicEnvironment, accessToken: string, Socket?: WebSocketConstructor): WebSocket;

package/dist/realtime.js

@@ -0,0 +1,10 @@
+export { publicStreamServers, streamServerUrl } from "./base.js";
+import { realtimeCredentialProtocol, realtimeProtocol, realtimeUrl } from "./stream.js";
+export { marketStreamProtocol, marketStreamUrl, realtimeCredentialProtocol, realtimeProtocol, realtimeUrl, StreamClosedError, TotalisStream, } from "./stream.js";
+/** A raw socket with the reviewed subprotocols. `TotalisStream` adds the subscribe frame, replay and reconnect. */
+export function createRealtimeSocket(environment, accessToken, Socket = WebSocket) {
+    return new Socket(realtimeUrl(environment), [
+        realtimeProtocol,
+        realtimeCredentialProtocol(accessToken),
+    ]);
+}

package/dist/request.d.ts

@@ -0,0 +1,115 @@
+import { type ErrorCode, type Retry } from "./generated/errors.js";
+/** A lowercase RFC 9562 UUIDv7: the venue requires it for request IDs and idempotency keys. */
+export declare function uuidv7(now?: number): string;
+/** 32 random bytes as 0x-hex, for salts and nonces. */
+export declare function randomBytes32(): `0x${string}`;
+/**
+ * The envelope core exits and maker onboarding still carry. Every other
+ * command is sent bare. Build it once and resend it unchanged.
+ */
+export declare function envelope<Command>(command: Command, requestId?: string): {
+    schema_version: 1;
+    request_id: string;
+    sent_at: string;
+    command: Command;
+};
+type FieldViolation = {
+    readonly code: string;
+    readonly field: string;
+};
+/**
+ * A registered error from the venue (TT-1770). `retry` says what to do:
+ * NEVER stop; BACKOFF resend the same request (the SDK already did, until its
+ * attempts ran out); REFRESH re-read state, then decide on a new request.
+ */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: ErrorCode | `HTTP_${number}`;
+    readonly retry: Retry;
+    readonly requestId?: string | undefined;
+    readonly fieldViolations: readonly FieldViolation[];
+    readonly retryAfterMs?: number | undefined;
+    readonly name = "ApiError";
+    /** For a flow command answered BACKOFF after every resend, or whose resend was refused after an earlier send's answer was lost and the outcome could not be read: send the identical request again later. */
+    resend?: () => Promise<unknown>;
+    constructor(status: number, code: ErrorCode | `HTTP_${number}`, retry: Retry, message: string, requestId?: string | undefined, fieldViolations?: readonly FieldViolation[], retryAfterMs?: number | undefined);
+    static from(response: Response, body: unknown): ApiError;
+}
+/**
+ * The request may or may not have reached the venue. Flows attach `resend()`,
+ * which sends the identical request (same bytes, same idempotency key) and
+ * returns its result: the venue replays a command it already accepted.
+ */
+export declare class NetworkError extends Error {
+    readonly request: {
+        readonly method: string;
+        readonly url: string;
+    };
+    readonly name = "NetworkError";
+    resend?: () => Promise<unknown>;
+    constructor(request: {
+        readonly method: string;
+        readonly url: string;
+    }, options: {
+        cause: unknown;
+    });
+}
+/** Retry-After in milliseconds: delta-seconds or an HTTP date. */
+export declare function retryAfterMs(response: Response, now?: number): number | undefined;
+/** Exponential backoff with equal jitter: half the capped delay, plus up to half again at random. */
+export declare function backoffDelay(retry: number, baseDelayMs: number, maxDelayMs: number): number;
+export type RetryPolicy = {
+    /** Total sends, including the first. Default 5. */
+    readonly attempts?: number;
+    readonly baseDelayMs?: number;
+    readonly maxDelayMs?: number;
+    /** The longest Retry-After waited out before a resend. Default 30 s; a longer one is returned as is, so the caller's error carries `retryAfterMs`. */
+    readonly maxRetryAfterMs?: number;
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+};
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Wrap fetch so each request is built once and resent byte for byte, with the
+ * same Idempotency-Key, after a network failure or a BACKOFF error (honouring
+ * a Retry-After up to `maxRetryAfterMs`; a longer one is not waited out). A
+ * network failure is only retried when resending is safe: a read, a DELETE,
+ * or a command that carries an Idempotency-Key. REFRESH and NEVER responses
+ * are returned untouched for the caller to surface.
+ */
+export type Fetch = (request: Request) => Promise<Response>;
+export declare function retryingFetch(fetchImpl?: Fetch, policy?: RetryPolicy): Fetch;
+/**
+ * One send with no resends, for callers that own their retries. A request
+ * lost before the response, or a body cut off while it is read, throws
+ * NetworkError; the body is read here so the caller parses it from memory.
+ */
+export declare function singleFetch(fetchImpl?: Fetch): Fetch;
+/**
+ * openapi-fetch's response typing maps over plain arrays only, so the
+ * generated readonly arrays come back as array-like objects. Restore them.
+ */
+export type Repaired<T> = T extends string | number | boolean | bigint | null | undefined ? T : T extends {
+    readonly [index: number]: infer Item;
+    readonly length: number;
+} ? readonly Repaired<Item>[] : T extends object ? {
+    readonly [K in keyof T]: Repaired<T[K]>;
+} : T;
+/** A failure whose command may still be resent unchanged: lost responses, or BACKOFF past the resend budget. */
+export declare function resendable(error: unknown): error is NetworkError | ApiError;
+/**
+ * Send a command built once. If every response is lost, or BACKOFF outlasts
+ * the resends, the error carries `resend()` for the identical request, so the
+ * caller can finish it instead of signing a second command.
+ */
+export declare function sendOnce<Data>(send: () => Promise<{
+    data?: Data;
+    error?: unknown;
+    response: Response;
+}>): Promise<Repaired<Data>>;
+/** The data of an openapi-fetch result, or its registered error thrown as ApiError. */
+export declare function unwrap<Data>(result: {
+    data?: Data;
+    error?: unknown;
+    response: Response;
+}): Repaired<Data>;
+export {};

package/dist/request.js

@@ -0,0 +1,190 @@
+import { errorRegistry } from "./generated/errors.js";
+/** A lowercase RFC 9562 UUIDv7: the venue requires it for request IDs and idempotency keys. */
+export function uuidv7(now = Date.now()) {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    for (let index = 0; index < 6; index++)
+        bytes[index] = Math.floor(now / 2 ** (8 * (5 - index))) & 0xff;
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** 32 random bytes as 0x-hex, for salts and nonces. */
+export function randomBytes32() {
+    return `0x${Array.from(crypto.getRandomValues(new Uint8Array(32)), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+/**
+ * The envelope core exits and maker onboarding still carry. Every other
+ * command is sent bare. Build it once and resend it unchanged.
+ */
+export function envelope(command, requestId = uuidv7()) {
+    return { schema_version: 1, request_id: requestId, sent_at: new Date().toISOString(), command };
+}
+/**
+ * A registered error from the venue (TT-1770). `retry` says what to do:
+ * NEVER stop; BACKOFF resend the same request (the SDK already did, until its
+ * attempts ran out); REFRESH re-read state, then decide on a new request.
+ */
+export class ApiError extends Error {
+    status;
+    code;
+    retry;
+    requestId;
+    fieldViolations;
+    retryAfterMs;
+    name = "ApiError";
+    /** For a flow command answered BACKOFF after every resend, or whose resend was refused after an earlier send's answer was lost and the outcome could not be read: send the identical request again later. */
+    resend;
+    constructor(status, code, retry, message, requestId, fieldViolations = [], retryAfterMs) {
+        super(`${code}: ${message}`);
+        this.status = status;
+        this.code = code;
+        this.retry = retry;
+        this.requestId = requestId;
+        this.fieldViolations = fieldViolations;
+        this.retryAfterMs = retryAfterMs;
+    }
+    static from(response, body) {
+        const detail = body?.error;
+        const code = detail?.code ?? `HTTP_${response.status}`;
+        const retry = detail?.retry ?? (code in errorRegistry ? errorRegistry[code].retry : undefined) ?? (transient(response.status) ? "BACKOFF" : "NEVER");
+        return new ApiError(response.status, code, retry, detail?.message ?? response.statusText, detail?.request_id, detail?.field_violations, retryAfterMs(response));
+    }
+}
+/**
+ * The request may or may not have reached the venue. Flows attach `resend()`,
+ * which sends the identical request (same bytes, same idempotency key) and
+ * returns its result: the venue replays a command it already accepted.
+ */
+export class NetworkError extends Error {
+    request;
+    name = "NetworkError";
+    resend;
+    constructor(request, options) {
+        super(`${request.method} ${request.url} failed without a response`, options);
+        this.request = request;
+    }
+}
+const transient = (status) => status === 429 || status === 502 || status === 503 || status === 504;
+/** Retry-After in milliseconds: delta-seconds or an HTTP date. */
+export function retryAfterMs(response, now = Date.now()) {
+    const header = response.headers.get("Retry-After")?.trim();
+    if (!header)
+        return undefined;
+    if (/^[0-9]+$/.test(header))
+        return Number(header) * 1000;
+    const date = Date.parse(header);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - now);
+}
+/** Exponential backoff with equal jitter: half the capped delay, plus up to half again at random. */
+export function backoffDelay(retry, baseDelayMs, maxDelayMs) {
+    return Math.min(maxDelayMs, baseDelayMs * 2 ** retry) * (0.5 + Math.random() / 2);
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+    });
+}
+async function wantsBackoff(response) {
+    if (response.ok)
+        return false;
+    const body = await response.clone().json().catch(() => undefined);
+    const retry = body?.error?.retry;
+    return retry === undefined ? transient(response.status) : retry === "BACKOFF";
+}
+export function retryingFetch(fetchImpl = (request) => globalThis.fetch(request), policy = {}) {
+    const { attempts = 5, baseDelayMs = 250, maxDelayMs = 10_000, maxRetryAfterMs = 30_000, sleep: wait = sleep } = policy;
+    return async (original) => {
+        const body = original.body === null ? null : new Uint8Array(await original.arrayBuffer());
+        const replayable = ["GET", "HEAD", "DELETE"].includes(original.method) || original.headers.has("Idempotency-Key");
+        const build = () => new Request(original.url, {
+            method: original.method, headers: original.headers, body, signal: original.signal,
+            credentials: original.credentials, cache: original.cache, redirect: original.redirect,
+            mode: original.mode, integrity: original.integrity, referrer: original.referrer,
+            referrerPolicy: original.referrerPolicy, keepalive: original.keepalive,
+        });
+        for (let attempt = 1;; attempt++) {
+            const backoff = backoffDelay(attempt - 1, baseDelayMs, maxDelayMs);
+            let response;
+            try {
+                response = await fetchImpl(build());
+            }
+            catch (cause) {
+                if (original.signal.aborted)
+                    throw cause;
+                if (!replayable || attempt >= attempts)
+                    throw new NetworkError(original, { cause });
+                await wait(backoff, original.signal);
+                continue;
+            }
+            if (attempt >= attempts || !(await wantsBackoff(response)))
+                return response;
+            const after = retryAfterMs(response);
+            if (after !== undefined && after > maxRetryAfterMs)
+                return response;
+            await response.body?.cancel();
+            await wait(after ?? backoff, original.signal);
+        }
+    };
+}
+/**
+ * One send with no resends, for callers that own their retries. A request
+ * lost before the response, or a body cut off while it is read, throws
+ * NetworkError; the body is read here so the caller parses it from memory.
+ */
+export function singleFetch(fetchImpl = (request) => globalThis.fetch(request)) {
+    return async (request) => {
+        let response;
+        try {
+            response = await fetchImpl(request);
+        }
+        catch (cause) {
+            if (request.signal.aborted)
+                throw cause;
+            throw new NetworkError(request, { cause });
+        }
+        try {
+            return new Response(response.body === null ? null : await response.arrayBuffer(), response);
+        }
+        catch (cause) {
+            if (request.signal.aborted)
+                throw cause;
+            throw new NetworkError(request, { cause });
+        }
+    };
+}
+/** A failure whose command may still be resent unchanged: lost responses, or BACKOFF past the resend budget. */
+export function resendable(error) {
+    return error instanceof NetworkError || (error instanceof ApiError && error.retry === "BACKOFF");
+}
+/**
+ * Send a command built once. If every response is lost, or BACKOFF outlasts
+ * the resends, the error carries `resend()` for the identical request, so the
+ * caller can finish it instead of signing a second command.
+ */
+export async function sendOnce(send) {
+    try {
+        return unwrap(await send());
+    }
+    catch (error) {
+        if (resendable(error))
+            error.resend = () => sendOnce(send);
+        throw error;
+    }
+}
+/** The data of an openapi-fetch result, or its registered error thrown as ApiError. */
+export function unwrap(result) {
+    if (result.error !== undefined || !result.response.ok)
+        throw ApiError.from(result.response, result.error);
+    return result.data;
+}

package/dist/signer.d.ts

@@ -0,0 +1,51 @@
+import { type Hex, type TypedData } from "./typed-data.js";
+/**
+ * The one signer shape the SDK uses. It never holds a key: every call goes to
+ * the wallet it adapts. Takers sign with their account's `signer`, makers with
+ * their quote signer, and API key issuance with the account's `owner`.
+ */
+export type TotalisSigner = {
+    address(): Promise<Hex>;
+    signTypedData(typedData: TypedData): Promise<Hex>;
+    /** EIP-191 personal_sign of a UTF-8 message. */
+    signMessage(message: string): Promise<Hex>;
+};
+/** A viem account (`privateKeyToAccount`, `toAccount`, a JSON-RPC account). */
+export type ViemAccountLike = {
+    readonly address: string;
+    signTypedData(parameters: TypedData): Promise<string>;
+    signMessage(parameters: {
+        message: string;
+    }): Promise<string>;
+};
+/** A viem wallet client. Its hoisted `account` is used, else its first address. */
+export type ViemWalletClientLike = {
+    readonly account?: {
+        readonly address: string;
+    } | undefined;
+    getAddresses(): Promise<readonly string[]>;
+    signTypedData(parameters: never): Promise<string>;
+    signMessage(parameters: never): Promise<string>;
+};
+/** An EIP-1193 provider (`window.ethereum`, a WalletConnect or embedded-wallet provider). */
+export type Eip1193ProviderLike = {
+    request(arguments_: never): Promise<unknown>;
+};
+type EthersTypes = Record<string, readonly {
+    name: string;
+    type: string;
+}[]>;
+/** An ethers v6 `Signer` (v5's `_signTypedData` also works). */
+export type EthersSignerLike = {
+    getAddress(): Promise<string>;
+    signMessage(message: string): Promise<string>;
+    signTypedData?(domain: TypedData["domain"], types: EthersTypes, value: Record<string, unknown>): Promise<string>;
+    _signTypedData?(domain: TypedData["domain"], types: EthersTypes, value: Record<string, unknown>): Promise<string>;
+};
+export type SignerInput = TotalisSigner | ViemAccountLike | ViemWalletClientLike | Eip1193ProviderLike | EthersSignerLike;
+/**
+ * Adapt a viem account or wallet client, an EIP-1193 provider, or an ethers
+ * signer. Signatures come back canonical (lowercase, v in {27, 28}).
+ */
+export declare function toTotalisSigner(input: SignerInput): TotalisSigner;
+export {};