@0xmonaco/core 1.0.93 → 1.0.94

package/dist/api/compliance/api.d.ts

@@ -1,15 +1,15 @@
 /**
  * Compliance API Implementation
  *
- * Reports whether Monaco is available in the caller's region. Every other
- * endpoint refuses callers from a restricted region with HTTP 451
- * `REGION_RESTRICTED`; this one always answers. Public — no authentication
- * required.
+ * Reports whether trading is available in the caller's region. A caller from a
+ * restricted region keeps every read, signing in and withdrawing; every other
+ * write is refused with HTTP 451 `REGION_RESTRICTED`. This endpoint always
+ * answers. Public — no authentication required.
  *
  * @example
  * ```typescript
  * const { restricted } = await sdk.compliance.getRegionStatus();
- * if (restricted) showRegionNotice();
+ * if (restricted) disableTrading();
  * ```
  */
 import type { ComplianceAPI, GetRegionStatusResponse } from "@0xmonaco/types";

package/dist/api/compliance/api.js

@@ -1,15 +1,15 @@
 /**
  * Compliance API Implementation
  *
- * Reports whether Monaco is available in the caller's region. Every other
- * endpoint refuses callers from a restricted region with HTTP 451
- * `REGION_RESTRICTED`; this one always answers. Public — no authentication
- * required.
+ * Reports whether trading is available in the caller's region. A caller from a
+ * restricted region keeps every read, signing in and withdrawing; every other
+ * write is refused with HTTP 451 `REGION_RESTRICTED`. This endpoint always
+ * answers. Public — no authentication required.
  *
  * @example
  * ```typescript
  * const { restricted } = await sdk.compliance.getRegionStatus();
- * if (restricted) showRegionNotice();
+ * if (restricted) disableTrading();
  * ```
  */
 import { BaseAPI } from "../base";

package/dist/api/websocket/websocket.js

@@ -6,6 +6,7 @@ import { keysToCamelCase } from "./utils";
 // Connection constants
 const CONNECTION_TIMEOUT = 10000;
 const HEARTBEAT_INTERVAL = 15000;
+const IDLE_TIMEOUT = 30000;
 const MAX_RECONNECT_DELAY = 30000;
 const RECONNECT_BASE_DELAY = 1000;
 /**
@@ -576,6 +577,68 @@ function parseTradeEventData(raw) {
         executedAt: readString(raw, "executed_at"),
     };
 }
+/**
+ * Parse one orderbook frame: a live `orderbook_update` event, or the row of an
+ * `orderbook` snapshot, which has the same shape.
+ */
+function parseOrderbookEvent(rawData) {
+    const data = rawData;
+    const orderbookData = data.data;
+    return {
+        // `trading_pair_id` is the pair UUID; `symbol` is the display string
+        // (e.g. "AMZN/USDC"). `tradingPairId` must carry the UUID.
+        tradingPairId: data.trading_pair_id,
+        tradingMode: data.trading_mode,
+        bids: (orderbookData?.bids || []).map((level) => ({
+            price: level.price,
+            quantity: level.quantity,
+            orderCount: level.order_count || 0,
+        })),
+        asks: (orderbookData?.asks || []).map((level) => ({
+            price: level.price,
+            quantity: level.quantity,
+            orderCount: level.order_count || 0,
+        })),
+        // Rust sends `null` for an empty side; normalize the nullable
+        // `Option` to `undefined` so it matches the `string | undefined` type
+        // rather than leaking `null` past the cast.
+        bestBid: orderbookData?.best_bid ?? undefined,
+        bestAsk: orderbookData?.best_ask ?? undefined,
+        bidVolume: orderbookData?.bid_volume || undefined,
+        askVolume: orderbookData?.ask_volume || undefined,
+        priceChange: orderbookData?.price_change
+            ? {
+                side: orderbookData.price_change.side,
+                // Normalize nullable Rust `Option` prices to `undefined` (a
+                // level-add has no old price, a level-remove no new price) so
+                // neither leaks `null` past the `string | undefined` type.
+                oldPrice: orderbookData.price_change.old_price ?? undefined,
+                newPrice: orderbookData.price_change.new_price ?? undefined,
+                levelRemoved: orderbookData.price_change.level_removed || false,
+                levelAdded: orderbookData.price_change.level_added || false,
+            }
+            : undefined,
+        baseDecimals: data.base_decimals || 0,
+        quoteDecimals: data.quote_decimals || 0,
+        timestamp: data.timestamp || new Date().toISOString(),
+        sequence: data.sequence_number || 0,
+    };
+}
+/**
+ * Parse the one row of an `orderbook` snapshot: the channel's current book in
+ * the live frame's shape, read the same way.
+ *
+ * The live parser casts; here a row that is not an object, or carries no `data`
+ * object, throws, so {@link snapshotFrameHandler} withholds the frame rather
+ * than handing over an empty book. The engine's book read carries no sequence,
+ * so the row's `sequence` is 0.
+ */
+function parseOrderbookSnapshotRow(raw) {
+    if (!isRecord(raw) || !isRecord(raw.data)) {
+        throw new Error("Invalid orderbook snapshot row: must be an object with a data object");
+    }
+    return parseOrderbookEvent(raw);
+}
 /**
  * Parse one `ohlcv` snapshot row: the live candle frame's `data` body.
  *
@@ -992,6 +1055,17 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
         ? options.reconnectBaseDelayMs
         : RECONNECT_BASE_DELAY;
     const connectionTimeout = Number.isFinite(options.connectionTimeoutMs) && options.connectionTimeoutMs > 0 ? options.connectionTimeoutMs : CONNECTION_TIMEOUT;
+    const idleTimeout = Number.isFinite(options.idleTimeoutMs) && options.idleTimeoutMs > 0 ? options.idleTimeoutMs : IDLE_TIMEOUT;
+    // A connection is dropped one tick after the idle window opens with a Ping
+    // unanswered, so a third of the window leaves room for a second Ping and its
+    // Pong: one lost Pong never trips a live connection.
+    const heartbeatInterval = Math.min(HEARTBEAT_INTERVAL, idleTimeout / 3);
+    // When the current socket last delivered anything. The server's own
+    // transport-level ping never reaches JavaScript, so this is the only
+    // liveness signal the client has.
+    let lastMessageAt = 0;
+    // When the current socket's last Ping went out; 0 before the first.
+    let lastPingAt = 0;
     // Close code of the connection loss the next successful reopen recovers
     // from; null when no resync is owed (first connect, clean disconnect).
     let pendingResyncCode = null;
@@ -1124,11 +1198,30 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
     };
     const startHeartbeat = () => {
         stopHeartbeat();
+        lastMessageAt = Date.now();
+        lastPingAt = 0;
         heartbeatTimer = setInterval(() => {
-            if (ws?.readyState === WebSocket.OPEN) {
-                ws.send(JSON.stringify({ type: "Ping" }));
+            const socket = ws;
+            if (socket?.readyState !== WebSocket.OPEN)
+                return;
+            // An open socket that has delivered nothing, not even the Pong to an
+            // earlier Ping, is dead: the browser still reports it OPEN, so without
+            // this the app freezes on its last data with no reconnect. Only an
+            // unanswered Ping counts: a background tab's throttled timer can tick
+            // long after the last Pong, and that gap is not silence.
+            if (lastPingAt > lastMessageAt && Date.now() - lastMessageAt >= idleTimeout) {
+                socket.close(1000, "Idle timeout");
+                // Its close event may take long to land on a dead network, so the
+                // loss is handled now as an abnormal close. The late event then
+                // belongs to an abandoned socket and is ignored. The server follows
+                // SESSION_INVALID with a 1008 close, so when that close is what got
+                // lost, the loss is read as the 1008 it announced.
+                handleSocketLoss(lastAuthError?.code === "SESSION_INVALID" ? 1008 : 1006);
+                return;
             }
-        }, HEARTBEAT_INTERVAL);
+            lastPingAt = Date.now();
+            socket.send(JSON.stringify({ type: "Ping" }));
+        }, heartbeatInterval);
     };
     const stopReconnect = () => {
         if (reconnectTimer) {
@@ -1380,6 +1473,83 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
             }
         }
     };
+    /**
+     * The current socket's connection is gone, by its close event or because it
+     * went silent: decide whether to reconnect, ask for fresh credentials, or
+     * report a terminal disconnect.
+     */
+    const handleSocketLoss = (code) => {
+        ws = null;
+        stopHeartbeat();
+        // The server dropped every subscription with the connection.
+        resetSubscriptionAcks();
+        // Terminal authentication loss: the server revoked the session
+        // (SESSION_INVALID, then 1008) or rejected this connection's
+        // handshake (AUTH_FAILED, then a close). Reconnecting would replay
+        // the same rejected credentials into the same rejection forever, so
+        // drop them, skip the reconnect, and let the app supply a fresh
+        // session. Handlers stay registered so that session resubscribes
+        // them. A 1008 without SESSION_INVALID (the message-rate cap) is a
+        // back-off-and-retry and falls through to the reconnect below, as
+        // does a close after the app already replaced the rejected session
+        // (e.g. re-authenticating from onError): the fresh session is what
+        // the reconnect uses.
+        const authError = lastAuthError;
+        // A handshake stamped outside the server's window is a clock
+        // problem, not a dead session: reconnect and re-sign, a bounded
+        // number of times, instead of discarding the credentials.
+        const skewRetry = autoReconnect && authError?.code === "AUTH_FAILED" && SKEW_REJECTION.test(authError.message) && skewAuthRetries < MAX_SKEW_AUTH_RETRIES;
+        if (skewRetry)
+            skewAuthRetries++;
+        const authLoss = !skewRetry &&
+            authError !== null &&
+            authError.session !== undefined &&
+            (authError.code === "AUTH_FAILED" || authError.code === "ACCOUNT_DEACTIVATED" || authError.code === "ACCOUNT_RESTRICTED" || code === 1008);
+        const terminalAuthLoss = authLoss && session === authError.session;
+        if (terminalAuthLoss) {
+            session = undefined;
+            // The reopen with a fresh session still owes the app a resync —
+            // nothing was delivered while the session was dead — whether or
+            // not automatic reconnect is on, since that reopen is driven by
+            // the new session, not by the reconnect loop.
+            if (pendingResyncCode === null) {
+                pendingResyncCode = code;
+            }
+            emitStatus("disconnected");
+            options.onReauthenticationRequired?.({ code: authError.code, message: authError.message, closeCode: code });
+            return;
+        }
+        // The app already handed over a replacement session on this socket.
+        // Had it arrived after the close, setSessionKeypair would have
+        // connected with it; honour that even with automatic reconnect off
+        // (with it on, the reconnect below uses the new session).
+        if (authLoss && session !== undefined && !autoReconnect) {
+            if (pendingResyncCode === null) {
+                pendingResyncCode = code;
+            }
+            emitStatus("disconnected");
+            connect().catch((err) => {
+                console.warn("WebSocket: Failed to connect with the replacement session:", err);
+            });
+            return;
+        }
+        // Reconnect on abnormal close. 1013 is the server's slow-client
+        // shed: the stream has a gap, so the reopen owes the app a resync.
+        // Keep the first owed code (upgrading to 1013 if it arrives later):
+        // failures of the reconnect attempts themselves must not launder
+        // the slow-client signal into a generic 1006.
+        if (autoReconnect && code !== 1000) {
+            if (pendingResyncCode === null || code === 1013) {
+                pendingResyncCode = code;
+            }
+            scheduleReconnect();
+        }
+        // "disconnected" is terminal: suppressed while a retry is armed
+        // (scheduleReconnect emitted "reconnecting" instead).
+        if (!reconnectTimer) {
+            emitTerminalDisconnected();
+        }
+    };
     const connect = () => {
         return new Promise((resolve, reject) => {
             // Use WebSocket's built-in readyState instead of manual tracking
@@ -1441,6 +1611,7 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
                 socket.onmessage = (event) => {
                     if (ws !== socket)
                         return;
+                    lastMessageAt = Date.now();
                     try {
                         const msg = JSON.parse(event.data);
                         // Handle pong silently
@@ -1464,76 +1635,7 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
                         resolve();
                         return;
                     }
-                    ws = null;
-                    stopHeartbeat();
-                    // The server dropped every subscription with the connection.
-                    resetSubscriptionAcks();
-                    // Terminal authentication loss: the server revoked the session
-                    // (SESSION_INVALID, then 1008) or rejected this connection's
-                    // handshake (AUTH_FAILED, then a close). Reconnecting would replay
-                    // the same rejected credentials into the same rejection forever, so
-                    // drop them, skip the reconnect, and let the app supply a fresh
-                    // session. Handlers stay registered so that session resubscribes
-                    // them. A 1008 without SESSION_INVALID (the message-rate cap) is a
-                    // back-off-and-retry and falls through to the reconnect below, as
-                    // does a close after the app already replaced the rejected session
-                    // (e.g. re-authenticating from onError): the fresh session is what
-                    // the reconnect uses.
-                    const authError = lastAuthError;
-                    // A handshake stamped outside the server's window is a clock
-                    // problem, not a dead session: reconnect and re-sign, a bounded
-                    // number of times, instead of discarding the credentials.
-                    const skewRetry = autoReconnect && authError?.code === "AUTH_FAILED" && SKEW_REJECTION.test(authError.message) && skewAuthRetries < MAX_SKEW_AUTH_RETRIES;
-                    if (skewRetry)
-                        skewAuthRetries++;
-                    const authLoss = !skewRetry &&
-                        authError !== null &&
-                        authError.session !== undefined &&
-                        (authError.code === "AUTH_FAILED" || authError.code === "ACCOUNT_DEACTIVATED" || authError.code === "ACCOUNT_RESTRICTED" || event.code === 1008);
-                    const terminalAuthLoss = authLoss && session === authError.session;
-                    if (terminalAuthLoss) {
-                        session = undefined;
-                        // The reopen with a fresh session still owes the app a resync —
-                        // nothing was delivered while the session was dead — whether or
-                        // not automatic reconnect is on, since that reopen is driven by
-                        // the new session, not by the reconnect loop.
-                        if (pendingResyncCode === null) {
-                            pendingResyncCode = event.code;
-                        }
-                        emitStatus("disconnected");
-                        options.onReauthenticationRequired?.({ code: authError.code, message: authError.message, closeCode: event.code });
-                        return;
-                    }
-                    // The app already handed over a replacement session on this socket.
-                    // Had it arrived after the close, setSessionKeypair would have
-                    // connected with it; honour that even with automatic reconnect off
-                    // (with it on, the reconnect below uses the new session).
-                    if (authLoss && session !== undefined && !autoReconnect) {
-                        if (pendingResyncCode === null) {
-                            pendingResyncCode = event.code;
-                        }
-                        emitStatus("disconnected");
-                        connect().catch((err) => {
-                            console.warn("WebSocket: Failed to connect with the replacement session:", err);
-                        });
-                        return;
-                    }
-                    // Reconnect on abnormal close. 1013 is the server's slow-client
-                    // shed: the stream has a gap, so the reopen owes the app a resync.
-                    // Keep the first owed code (upgrading to 1013 if it arrives later):
-                    // failures of the reconnect attempts themselves must not launder
-                    // the slow-client signal into a generic 1006.
-                    if (autoReconnect && event.code !== 1000) {
-                        if (pendingResyncCode === null || event.code === 1013) {
-                            pendingResyncCode = event.code;
-                        }
-                        scheduleReconnect();
-                    }
-                    // "disconnected" is terminal: suppressed while a retry is armed
-                    // (scheduleReconnect emitted "reconnecting" instead).
-                    if (!reconnectTimer) {
-                        emitTerminalDisconnected();
-                    }
+                    handleSocketLoss(event.code);
                 };
                 socket.onerror = () => clearTimeout(timeout);
                 // A retry's socket stays inside the outage "reconnecting" already
@@ -1626,7 +1728,7 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
             }
         }, onSnapshot && snapshotFrameHandler("orders", parseOrderSnapshotItem, onSnapshot));
     };
-    const subscribeOrderbook = (tradingPairId, tradingMode, magnitude, quotationMode, handler) => {
+    const subscribeOrderbook = (tradingPairId, tradingMode, magnitude, quotationMode, handler, onSnapshot) => {
         if (!tradingPairId || !tradingMode || magnitude === undefined || !quotationMode) {
             throw new Error(`orderbook subscription requires all params: tradingPairId="${tradingPairId}", tradingMode="${tradingMode}", magnitude=${magnitude} (valid: ${ALL_MAGNITUDES.join(", ")}), quotationMode="${quotationMode}" (valid: "BASE", "QUOTE")`);
         }
@@ -1636,53 +1738,12 @@ export function createMonacoWebSocket(baseUrl, options = {}, serverClock = new S
         const channel = `orderbook:${tradingPairId}:${tradingMode}:${magnitude}:${quotationMode.toLowerCase()}`;
         return subscribe(channel, (rawData) => {
             try {
-                const data = rawData;
-                const orderbookData = data.data;
-                const event = {
-                    // `trading_pair_id` is the pair UUID; `symbol` is the display string
-                    // (e.g. "AMZN/USDC"). `tradingPairId` must carry the UUID.
-                    tradingPairId: data.trading_pair_id,
-                    tradingMode: data.trading_mode,
-                    bids: (orderbookData?.bids || []).map((level) => ({
-                        price: level.price,
-                        quantity: level.quantity,
-                        orderCount: level.order_count || 0,
-                    })),
-                    asks: (orderbookData?.asks || []).map((level) => ({
-                        price: level.price,
-                        quantity: level.quantity,
-                        orderCount: level.order_count || 0,
-                    })),
-                    // Rust sends `null` for an empty side; normalize the nullable
-                    // `Option` to `undefined` so it matches the `string | undefined` type
-                    // rather than leaking `null` past the cast.
-                    bestBid: orderbookData?.best_bid ?? undefined,
-                    bestAsk: orderbookData?.best_ask ?? undefined,
-                    bidVolume: orderbookData?.bid_volume || undefined,
-                    askVolume: orderbookData?.ask_volume || undefined,
-                    priceChange: orderbookData?.price_change
-                        ? {
-                            side: orderbookData.price_change.side,
-                            // Normalize nullable Rust `Option` prices to `undefined` (a
-                            // level-add has no old price, a level-remove no new price) so
-                            // neither leaks `null` past the `string | undefined` type.
-                            oldPrice: orderbookData.price_change.old_price ?? undefined,
-                            newPrice: orderbookData.price_change.new_price ?? undefined,
-                            levelRemoved: orderbookData.price_change.level_removed || false,
-                            levelAdded: orderbookData.price_change.level_added || false,
-                        }
-                        : undefined,
-                    baseDecimals: data.base_decimals || 0,
-                    quoteDecimals: data.quote_decimals || 0,
-                    timestamp: data.timestamp || new Date().toISOString(),
-                    sequence: data.sequence_number || 0,
-                };
-                handler(event);
+                handler(parseOrderbookEvent(rawData));
             }
             catch (err) {
                 console.error("WebSocket: Error processing orderbook event", err);
             }
-        });
+        }, onSnapshot && snapshotFrameHandler("orderbook", parseOrderbookSnapshotRow, onSnapshot));
     };
     const subscribeOHLCV = (tradingPairId, tradingMode, interval, handler, priceType, onSnapshot) => {
         // Four-token channel selects the trade-derived candles (back-compat); the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/core",
-	"version": "1.0.93",
+	"version": "1.0.94",
 	"type": "module",
 	"homepage": "https://docs.0xmonaco.com/sdk/typescript",
 	"main": "./dist/index.js",
@@ -19,8 +19,8 @@
 		"viem": "^2.45.2"
 	},
 	"dependencies": {
-		"@0xmonaco/contracts": "1.0.93",
-		"@0xmonaco/types": "1.0.93",
+		"@0xmonaco/contracts": "1.0.94",
+		"@0xmonaco/types": "1.0.94",
 		"@noble/curves": "^1.9.1",
 		"@noble/hashes": "^2.4.0",
 		"http-status-codes": "^2.3.0"