@totalis/hip4-client 0.0.0-stage → 0.73.0

package/dist/signer.js

@@ -0,0 +1,90 @@
+import { address, canonicalSignature, domainTypes } from "./typed-data.js";
+function withoutDomainType(types) {
+    const { EIP712Domain: _, ...rest } = types;
+    return rest;
+}
+/** JSON for eth_signTypedData_v4: decimal strings for integers, and the domain type the method requires. */
+function typedDataJson(typedData) {
+    return JSON.stringify({
+        ...typedData,
+        types: {
+            EIP712Domain: domainTypes.EIP712Domain,
+            ...withoutDomainType(typedData.types),
+        },
+    }, (_, value) => (typeof value === "bigint" ? value.toString() : value));
+}
+function hexUtf8(message) {
+    return `0x${Array.from(new TextEncoder().encode(message), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+/** Wallets answer with `unknown`; accept only a hex string. */
+function hexString(value) {
+    if (typeof value !== "string" || !value.startsWith("0x"))
+        throw new TypeError("the wallet did not return a hex value");
+    return value;
+}
+function firstAddress(value) {
+    return Array.isArray(value) && value.length > 0 ? hexString(value[0]) : undefined;
+}
+/**
+ * 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 function toTotalisSigner(input) {
+    const has = (name) => name in input && typeof input[name] === "function";
+    let signer;
+    if ("address" in input && typeof input.address === "function") {
+        signer = input;
+    }
+    else if ("getAddress" in input) {
+        const sign = (input.signTypedData ?? input._signTypedData)?.bind(input);
+        if (sign === undefined)
+            throw new TypeError("the ethers signer cannot sign typed data");
+        signer = {
+            address: () => input.getAddress(),
+            signTypedData: (typedData) => sign(typedData.domain, withoutDomainType(typedData.types), typedData.message),
+            signMessage: (message) => input.signMessage(message),
+        };
+    }
+    else if ("getAddresses" in input) {
+        // A hoisted account (possibly local) signs itself; otherwise the wallet's first address signs over RPC.
+        const account = async () => input.account ?? (await input.getAddresses())[0] ?? Promise.reject(new Error("wallet client has no account"));
+        // viem's generic signatures are declared `never`; widen them once here.
+        const signTypedData = input.signTypedData.bind(input);
+        const signMessage = input.signMessage.bind(input);
+        signer = {
+            address: async () => {
+                const current = await account();
+                return typeof current === "string" ? current : current.address;
+            },
+            signTypedData: async (typedData) => hexString(await signTypedData({ account: await account(), ...typedData })),
+            signMessage: async (message) => hexString(await signMessage({ account: await account(), message })),
+        };
+    }
+    else if ("address" in input && typeof input.address === "string") {
+        const account = input;
+        signer = {
+            address: async () => account.address,
+            signTypedData: (typedData) => account.signTypedData(typedData),
+            signMessage: (message) => account.signMessage({ message }),
+        };
+    }
+    else if (has("request")) {
+        // The provider's generic request is declared `never`; widen it once here.
+        const request = input.request.bind(input);
+        const account = async () => firstAddress(await request({ method: "eth_accounts" })) ??
+            firstAddress(await request({ method: "eth_requestAccounts" })) ?? Promise.reject(new Error("provider has no account"));
+        signer = {
+            address: account,
+            signTypedData: async (typedData) => hexString(await request({ method: "eth_signTypedData_v4", params: [await account(), typedDataJson(typedData)] })),
+            signMessage: async (message) => hexString(await request({ method: "personal_sign", params: [hexUtf8(message), await account()] })),
+        };
+    }
+    else {
+        throw new TypeError("unsupported signer: pass a viem account or wallet client, an EIP-1193 provider, or an ethers signer");
+    }
+    return {
+        address: async () => address((await signer.address()).toLowerCase()),
+        signTypedData: async (typedData) => canonicalSignature(await signer.signTypedData(typedData)),
+        signMessage: async (message) => canonicalSignature(await signer.signMessage(message)),
+    };
+}

package/dist/stream.d.ts

@@ -0,0 +1,142 @@
+import { type AccessToken, type PublicEnvironment } from "./base.js";
+import type { components } from "./generated/realtime.js";
+type Schemas = components["schemas"];
+export type RealtimeCursor = Schemas["Cursor"];
+export type StreamEvent = Schemas["Event"];
+export type StreamEventType = StreamEvent["event_type"];
+export type StreamEventOf<T extends StreamEventType> = StreamEvent extends infer E ? E extends {
+    readonly event_type: infer K;
+} ? T extends K ? E : never : never : never;
+export type StreamSnapshot = Schemas["Snapshot"];
+export type StreamEventFrame = Schemas["EventFrame"];
+/** What a stream follows: the account (optionally with every open RFQ), or one maker. The client manages the cursor. */
+export type StreamSubscription = Omit<Schemas["AccountSubscription"], "cursor"> | Omit<Schemas["MakerSubscription"], "cursor">;
+/** A server frame: `channel` names what `data` carries. */
+export type StreamFrame = {
+    readonly channel: string;
+    readonly data?: unknown;
+};
+/**
+ * `live` means subscribed and caught up: the snapshot applied, or every
+ * replayed event applied (with publication freshness, at the first
+ * publication checkpoint, which the server sends only after its replay).
+ * Anything else means books and pending reads are stale.
+ */
+export type StreamStatus = "idle" | "connecting" | "live" | "disconnected" | "closed";
+/**
+ * Opens the socket. In a browser the credential travels as the
+ * `auth.<token>` subprotocol with the page's Origin; elsewhere (Node 22+, bots)
+ * as a bearer header, so `headers` carries Authorization and any extra headers.
+ */
+export type WebSocketFactory = (url: string, protocols: string[], headers: Record<string, string>) => WebSocket;
+export type StreamOptions = {
+    readonly environment?: PublicEnvironment;
+    /** The API origin; without `streamBaseUrl` the stream connects to it. */
+    readonly baseUrl?: string;
+    /** The WebSocket origin, such as `wss://hip4-ws.totalis.trade`. Defaults to `baseUrl`, else the environment's stream host. */
+    readonly streamBaseUrl?: string;
+    readonly accessToken: AccessToken;
+    /** `publication_freshness` (1 s heartbeats and publication checkpoints) defaults on for an account, off for a maker. */
+    readonly subscription: StreamSubscription;
+    /**
+     * Resume after this cursor, for example one a bot persisted from `event.cursor`:
+     * the stream replays the retained events after it, or resets to a snapshot.
+     */
+    readonly cursor?: RealtimeCursor;
+    readonly webSocket?: WebSocketFactory;
+    /** Extra handshake headers outside a browser, such as the Origin a browser session requires. */
+    readonly headers?: Record<string, string>;
+    readonly reconnect?: {
+        readonly baseDelayMs?: number;
+        readonly maxDelayMs?: number;
+    };
+    /** Reconnect after this long without a frame. Default 5000 ms with publication freshness, otherwise off. */
+    readonly silenceTimeoutMs?: number;
+};
+type Listeners = {
+    /** A new event, in order and deduplicated, with the frame that carried it. */
+    event: (event: StreamEvent, frame: StreamEventFrame) => void;
+    snapshot: (snapshot: StreamSnapshot) => void;
+    /** Local state built from earlier events is void; replace it from the snapshot that follows. */
+    reset: () => void;
+    status: (status: StreamStatus) => void;
+    /** Every parsed frame, including publication checkpoints, market refreshes and read invalidations. */
+    frame: (frame: StreamFrame) => void;
+    error: (error: unknown) => void;
+};
+/**
+ * The stream closed for good: the server's NEVER reason (for example
+ * SUBSCRIPTION_DENIED or STREAM_REPLACED), or `closed` after `close()`. It
+ * will not reconnect. `commandSent`: it cut off a follow of a command already
+ * sent, which may still execute.
+ */
+export declare class StreamClosedError extends Error {
+    readonly reason: string;
+    readonly closeCode: number;
+    readonly commandSent: boolean;
+    readonly name = "StreamClosedError";
+    constructor(reason: string, closeCode: number, commandSent?: boolean);
+}
+/** The account and maker stream subprotocol. */
+export declare const realtimeProtocol = "totalis.realtime.v2";
+export declare const marketStreamProtocol = "totalis.market.v2";
+export declare function realtimeUrl(environment: PublicEnvironment, baseUrl?: string, streamBaseUrl?: string): string;
+/**
+ * The public market stream URL. `path` is `fallback_stream` from
+ * `GET /v1/market-data/config` (a path, `/v1/market-stream`), joined to the
+ * stream origin rather than the API origin.
+ */
+export declare function marketStreamUrl(environment: PublicEnvironment, baseUrl?: string, streamBaseUrl?: string, path?: string): string;
+export declare function realtimeCredentialProtocol(accessToken: string): string;
+/**
+ * The authenticated realtime stream (`GET /v1/stream`) with snapshot, replay and
+ * reconnect. Delivery is at least once; this client orders and deduplicates by
+ * cursor and `event_id`, reconnects with jittered backoff from the last applied
+ * cursor, and follows each close reason's retry: BACKOFF resumes, REFRESH takes
+ * a fresh snapshot, NEVER stops. It works with the browser WebSocket and Node's.
+ */
+export declare class TotalisStream {
+    private readonly options;
+    status: StreamStatus;
+    /** The last applied cursor. Persist it to resume after a restart. */
+    cursor: RealtimeCursor | undefined;
+    private clockOffsetMs;
+    private closedWith;
+    private socket;
+    private attempt;
+    private nextDelayMs;
+    private timer;
+    private silence;
+    private reauthorized;
+    /** A REPLAY resume with publication freshness: live waits for the first publication frame, which follows the replayed events. */
+    private replaying;
+    private readonly seen;
+    private readonly listeners;
+    constructor(options: StreamOptions);
+    on<K extends keyof Listeners>(type: K, listener: Listeners[K]): () => void;
+    start(): this;
+    close(): void;
+    /** Why the stream closed for good, as an error; `commandSent` marks a follow of a command already sent. */
+    closeError(commandSent?: boolean): StreamClosedError;
+    /** The venue clock in ms, from the last subscription response or publication checkpoint's `server_time`. */
+    serverNow(): number;
+    /** Resolves once the stream is live (starting it if needed); rejects if it closes for good. */
+    live(signal?: AbortSignal): Promise<void>;
+    /** The first event the predicate accepts. Rejects if the stream closes for good or the signal aborts. */
+    next<E extends StreamEvent>(predicate: (event: StreamEvent) => event is E, signal?: AbortSignal): Promise<E>;
+    next(predicate: (event: StreamEvent) => boolean, signal?: AbortSignal): Promise<StreamEvent>;
+    private until;
+    private emit;
+    private setStatus;
+    private reset;
+    private apply;
+    private freshness;
+    private connect;
+    private subscribe;
+    private onFrame;
+    private goLive;
+    private onClose;
+    private disconnected;
+    private watchSilence;
+}
+export {};

package/dist/stream.js

@@ -0,0 +1,331 @@
+import { streamServerUrl } from "./base.js";
+import { errorRegistry } from "./generated/errors.js";
+import { backoffDelay } from "./request.js";
+const inBrowser = () => typeof globalThis.document !== "undefined";
+// Node's WebSocket (undici) and Bun accept `{ protocols, headers }` in place of protocols.
+const openWebSocket = (url, protocols, headers) => inBrowser() ? new WebSocket(url, protocols) : new WebSocket(url, { protocols, headers });
+/**
+ * The stream closed for good: the server's NEVER reason (for example
+ * SUBSCRIPTION_DENIED or STREAM_REPLACED), or `closed` after `close()`. It
+ * will not reconnect. `commandSent`: it cut off a follow of a command already
+ * sent, which may still execute.
+ */
+export class StreamClosedError extends Error {
+    reason;
+    closeCode;
+    commandSent;
+    name = "StreamClosedError";
+    constructor(reason, closeCode, commandSent = false) {
+        super(`stream closed: ${reason || closeCode}`);
+        this.reason = reason;
+        this.closeCode = closeCode;
+        this.commandSent = commandSent;
+    }
+}
+/** The account and maker stream subprotocol. */
+export const realtimeProtocol = "totalis.realtime.v2";
+export const marketStreamProtocol = "totalis.market.v2";
+export function realtimeUrl(environment, baseUrl, streamBaseUrl) {
+    return `${streamServerUrl(environment, baseUrl, streamBaseUrl)}/v1/stream`;
+}
+/**
+ * The public market stream URL. `path` is `fallback_stream` from
+ * `GET /v1/market-data/config` (a path, `/v1/market-stream`), joined to the
+ * stream origin rather than the API origin.
+ */
+export function marketStreamUrl(environment, baseUrl, streamBaseUrl, path = "/v1/market-stream") {
+    return `${streamServerUrl(environment, baseUrl, streamBaseUrl)}${path}`;
+}
+export function realtimeCredentialProtocol(accessToken) {
+    const bytes = new TextEncoder().encode(accessToken);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return `auth.${btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "")}`;
+}
+const sameStream = (a, b) => a.stream_id === b.stream_id && a.generation_id === b.generation_id;
+/**
+ * The authenticated realtime stream (`GET /v1/stream`) with snapshot, replay and
+ * reconnect. Delivery is at least once; this client orders and deduplicates by
+ * cursor and `event_id`, reconnects with jittered backoff from the last applied
+ * cursor, and follows each close reason's retry: BACKOFF resumes, REFRESH takes
+ * a fresh snapshot, NEVER stops. It works with the browser WebSocket and Node's.
+ */
+export class TotalisStream {
+    options;
+    status = "idle";
+    /** The last applied cursor. Persist it to resume after a restart. */
+    cursor;
+    clockOffsetMs = 0;
+    closedWith;
+    socket;
+    attempt = 0;
+    nextDelayMs;
+    timer;
+    silence;
+    reauthorized = false;
+    /** A REPLAY resume with publication freshness: live waits for the first publication frame, which follows the replayed events. */
+    replaying = false;
+    seen = [];
+    listeners = {
+        event: new Set(), snapshot: new Set(), reset: new Set(), status: new Set(), frame: new Set(), error: new Set(),
+    };
+    constructor(options) {
+        this.options = options;
+        this.cursor = options.cursor;
+    }
+    on(type, listener) {
+        this.listeners[type].add(listener);
+        return () => this.listeners[type].delete(listener);
+    }
+    start() {
+        if (this.status === "idle")
+            void this.connect();
+        return this;
+    }
+    close() {
+        this.setStatus("closed");
+        clearTimeout(this.timer);
+        clearTimeout(this.silence);
+        const socket = this.socket;
+        this.socket = undefined;
+        socket?.close(1000);
+    }
+    /** Why the stream closed for good, as an error; `commandSent` marks a follow of a command already sent. */
+    closeError(commandSent = false) {
+        return new StreamClosedError(this.closedWith?.reason ?? "closed", this.closedWith?.code ?? 1000, commandSent);
+    }
+    /** The venue clock in ms, from the last subscription response or publication checkpoint's `server_time`. */
+    serverNow() {
+        return Date.now() + this.clockOffsetMs;
+    }
+    /** Resolves once the stream is live (starting it if needed); rejects if it closes for good. */
+    live(signal) {
+        this.start();
+        return this.until(() => this.status === "live" ? true : undefined, signal).then(() => undefined);
+    }
+    next(predicate, signal) {
+        this.start();
+        let found;
+        const off = this.on("event", (event) => {
+            if (found === undefined && predicate(event))
+                found = event;
+        });
+        return this.until(() => found, signal).finally(off);
+    }
+    until(check, signal) {
+        return new Promise((resolve, reject) => {
+            const offs = [];
+            const done = (settle) => {
+                for (const off of offs)
+                    off();
+                signal?.removeEventListener("abort", abort);
+                settle();
+            };
+            const test = () => {
+                const value = check();
+                if (value !== undefined)
+                    done(() => resolve(value));
+                else if (this.status === "closed")
+                    done(() => reject(this.closeError()));
+            };
+            const abort = () => done(() => reject(signal?.reason));
+            if (signal?.aborted)
+                return reject(signal.reason);
+            signal?.addEventListener("abort", abort, { once: true });
+            offs.push(this.on("status", test), this.on("event", test));
+            test();
+        });
+    }
+    emit(type, ...args) {
+        for (const listener of [...this.listeners[type]]) {
+            try {
+                listener(...args);
+            }
+            catch (error) {
+                if (type !== "error")
+                    this.emit("error", error);
+            }
+        }
+    }
+    setStatus(status) {
+        if (this.status === status || this.status === "closed")
+            return;
+        this.status = status;
+        this.emit("status", status);
+    }
+    reset() {
+        this.cursor = undefined;
+        this.seen.length = 0;
+        this.emit("reset");
+    }
+    apply(event, frame) {
+        const cursor = this.cursor;
+        if (cursor !== undefined && sameStream(cursor, event.cursor) && BigInt(event.cursor.sequence) <= BigInt(cursor.sequence))
+            return;
+        if (this.seen.includes(event.event_id))
+            return;
+        this.seen.push(event.event_id);
+        if (this.seen.length > 1024)
+            this.seen.shift();
+        this.cursor = event.cursor;
+        this.emit("event", event, frame);
+    }
+    freshness() {
+        const { type, publication_freshness = type === "account" } = this.options.subscription;
+        return publication_freshness;
+    }
+    async connect() {
+        this.replaying = false;
+        this.setStatus("connecting");
+        const { accessToken, environment = "production", baseUrl, streamBaseUrl } = this.options;
+        let socket;
+        try {
+            const token = typeof accessToken === "function" ? await accessToken() : accessToken;
+            if (this.status === "closed")
+                return;
+            const open = this.options.webSocket ?? openWebSocket;
+            const url = realtimeUrl(environment, baseUrl, streamBaseUrl);
+            socket = inBrowser()
+                ? open(url, [realtimeProtocol, realtimeCredentialProtocol(token)], {})
+                : open(url, [realtimeProtocol], { ...this.options.headers, Authorization: `Bearer ${token}` });
+        }
+        catch (error) {
+            this.emit("error", error);
+            this.disconnected();
+            return;
+        }
+        this.socket = socket;
+        socket.onopen = () => socket.send(JSON.stringify(this.subscribe()));
+        socket.onmessage = (message) => {
+            if (socket !== this.socket)
+                return;
+            let frame;
+            try {
+                frame = JSON.parse(String(message.data));
+            }
+            catch (error) {
+                this.emit("error", error);
+                return;
+            }
+            if (typeof frame !== "object" || frame === null || !("channel" in frame) || typeof frame.channel !== "string") {
+                this.emit("error", new TypeError("stream frame without a channel"));
+                return;
+            }
+            this.onFrame(frame);
+        };
+        socket.onclose = (event) => {
+            if (socket === this.socket)
+                this.onClose(event.code, event.reason);
+        };
+        this.watchSilence();
+    }
+    subscribe() {
+        const { publication_freshness = this.options.subscription.type === "account", ...subscription } = this.options.subscription;
+        return {
+            method: "subscribe",
+            subscription: { ...subscription, ...(publication_freshness ? { publication_freshness } : {}), ...(this.cursor === undefined ? {} : { cursor: this.cursor }) },
+        };
+    }
+    onFrame(raw) {
+        this.watchSilence();
+        this.emit("frame", raw);
+        // The frames this client acts on, by their `channel`; any other channel is only emitted above.
+        const frame = raw;
+        switch (frame.channel) {
+            case "publication":
+                if (frame.data !== null)
+                    this.clockOffsetMs = Date.parse(frame.data.server_time) - Date.now();
+                if (this.replaying) {
+                    this.replaying = false;
+                    this.goLive();
+                }
+                break;
+            case "subscriptionResponse": {
+                const ready = frame.data;
+                this.clockOffsetMs = Date.parse(ready.server_time) - Date.now();
+                if (ready.resume === "REPLAY") {
+                    this.cursor = ready.cursor;
+                    // The replayed events follow this frame and nothing marks their end
+                    // except the server's first publication checkpoint after them.
+                    // Without publication freshness there is no such marker, so the
+                    // stream is live once subscribed and replayed events may still follow.
+                    if (this.freshness())
+                        this.replaying = true;
+                    else
+                        this.goLive();
+                }
+                else if (ready.resume === "RESET" || this.cursor !== undefined) {
+                    this.reset();
+                }
+                break;
+            }
+            case "snapshot": {
+                const snapshot = frame.data;
+                this.cursor = snapshot.cursor;
+                this.seen.length = 0;
+                this.emit("snapshot", snapshot);
+                this.goLive();
+                break;
+            }
+            case "event":
+                this.apply(frame.data, frame);
+                break;
+            case "reset":
+                this.reset();
+                break;
+            case "drain":
+                this.nextDelayMs = frame.data.retry_after_ms;
+                break;
+        }
+    }
+    goLive() {
+        this.attempt = 0;
+        this.reauthorized = false;
+        this.setStatus("live");
+    }
+    onClose(code, reason) {
+        this.socket = undefined;
+        clearTimeout(this.silence);
+        if (this.status === "closed")
+            return;
+        const retry = errorRegistry[reason]?.retry ?? "BACKOFF";
+        // A renewable session may retry a revoked credential once with a fresh token.
+        const renew = reason === "AUTHORIZATION_REVOKED" && typeof this.options.accessToken === "function" && !this.reauthorized;
+        if (retry === "NEVER" && !renew) {
+            this.closedWith = { reason, code };
+            this.close();
+            this.emit("error", this.closeError());
+            return;
+        }
+        if (renew)
+            this.reauthorized = true;
+        if (retry === "REFRESH" && this.cursor !== undefined)
+            this.reset();
+        this.disconnected();
+    }
+    disconnected() {
+        if (this.status === "closed")
+            return;
+        this.setStatus("disconnected");
+        const { baseDelayMs = 500, maxDelayMs = 30_000 } = this.options.reconnect ?? {};
+        // A drain's hint is the same for every socket it closes: wait at least that long, spread over as long again.
+        const delay = this.nextDelayMs === undefined ? backoffDelay(this.attempt, baseDelayMs, maxDelayMs) : this.nextDelayMs * (1 + Math.random());
+        this.nextDelayMs = undefined;
+        this.attempt++;
+        clearTimeout(this.timer);
+        this.timer = setTimeout(() => void this.connect(), delay);
+    }
+    watchSilence() {
+        const { silenceTimeoutMs = this.freshness() ? 5000 : undefined } = this.options;
+        clearTimeout(this.silence);
+        if (silenceTimeoutMs === undefined)
+            return;
+        this.silence = setTimeout(() => {
+            const socket = this.socket;
+            this.socket = undefined;
+            socket?.close(4000, "silent");
+            this.disconnected();
+        }, silenceTimeoutMs);
+    }
+}