@0xmonaco/core 1.0.37 → 1.0.38-develop.ebf8e8c

package/dist/api/websocket/types.d.ts

@@ -1,51 +1,15 @@
-import type { ConditionalOrderEvent, Interval, OHLCVEvent, OrderbookEvent, OrderbookQuotationMode, OrderEvent, SessionCredentials, TradeEvent, TradingMode, UserBalanceEvent, UserMovementEvent, WebSocketStatus } from "@0xmonaco/types";
-export type StatusHandler = (status: WebSocketStatus) => void;
+import type { ConditionalOrderEvent, Interval, LiquidationEvent, MonacoWebSocketConfig, OHLCVEvent, OrderbookEvent, OrderbookQuotationMode, OrderEvent, PositionEvent, SessionCredentials, TradeEvent, TradingMode, UserBalanceEvent, UserMovementEvent, WebSocketStatus } from "@0xmonaco/types";
+export type { ResyncHandler, StatusHandler, WebSocketResyncInfo } from "@0xmonaco/types";
 export type MessageHandler<T> = (data: T) => void;
 /**
- * Why the connection was re-established. Delivered by
- * {@link MonacoWebSocketOptions.onResync} after the client has reconnected,
- * re-authenticated, and re-subscribed — the point where the app should
- * refetch REST snapshots and reconcile by `(id, updatedAt)`.
+ * Options for {@link createMonacoWebSocket}. The reconnect/resync knobs and
+ * callbacks are shared with the main SDK config via {@link MonacoWebSocketConfig}
+ * (settable as `SDKConfig.ws`); the session keypair is factory-only because the
+ * SDK propagates it after {@link login} rather than at construction.
  */
-export interface WebSocketResyncInfo {
-    /** WebSocket close code of the connection that was lost. */
-    code: number;
-    /**
-     * True when the server closed with 1013 (try again later): the client fell
-     * behind a sequential stream (orders, conditional orders, liquidations,
-     * trades, movements) and the stream has a gap. There is no wire sequence
-     * number — the 1013 close is the gap signal, and a snapshot refetch is the
-     * only safe repair.
-     */
-    slowClient: boolean;
-}
-export type ResyncHandler = (info: WebSocketResyncInfo) => void;
-export interface MonacoWebSocketOptions {
+export interface MonacoWebSocketOptions extends MonacoWebSocketConfig {
     /** Session keypair for authenticated channels (orders, balances, etc.) */
     session?: SessionCredentials;
-    /** Enable auto-reconnect on disconnect (default: true) */
-    autoReconnect?: boolean;
-    /**
-     * Maximum reconnection attempts (default: unlimited). Retry delay is
-     * full-jitter exponential backoff capped at 30s, so unlimited retries are
-     * capped-rate, not a tight loop.
-     */
-    maxReconnectAttempts?: number;
-    /** Base delay for the exponential backoff in milliseconds (default: 1000) */
-    reconnectBaseDelayMs?: number;
-    /** How long a connection attempt may stay CONNECTING before it is failed
-     * and retried, in milliseconds (default: 10000) */
-    connectionTimeoutMs?: number;
-    /** Callback for connection status changes */
-    onStatusChange?: StatusHandler;
-    /**
-     * Called after every automatic reconnect once the live stream is resumed
-     * (re-authenticated and re-subscribed). Refetch REST snapshots here and
-     * reconcile by `(id, updatedAt)`, last-writer-wins; events that arrived
-     * while the snapshot was in flight are newer than the snapshot rows they
-     * duplicate.
-     */
-    onResync?: ResyncHandler;
 }
 export interface MonacoWebSocket {
     /** Connect to the WebSocket server */
@@ -74,4 +38,8 @@ export interface MonacoWebSocket {
     balances: (handler: MessageHandler<UserBalanceEvent>) => () => void;
     /** Subscribe to conditional TP/SL lifecycle events (requires authentication) */
     conditionalOrders: (handler: MessageHandler<ConditionalOrderEvent>, tradingPairId?: string) => () => void;
+    /** Subscribe to position state updates (requires authentication); omit `tradingPairId` for all pairs */
+    positions: (handler: MessageHandler<PositionEvent>, tradingPairId?: string) => () => void;
+    /** Subscribe to liquidation alerts (requires authentication); omit `tradingPairId` for all pairs */
+    liquidations: (handler: MessageHandler<LiquidationEvent>, tradingPairId?: string) => () => void;
 }

package/dist/api/websocket/websocket.js

@@ -18,7 +18,7 @@ function isRecord(value) {
 function readString(source, field) {
     const value = source[field];
     if (typeof value !== "string" || value.length === 0) {
-        throw new Error(`Invalid conditional order event: ${field} must be a non-empty string`);
+        throw new Error(`Invalid WebSocket event: ${field} must be a non-empty string`);
     }
     return value;
 }
@@ -27,14 +27,14 @@ function readOptionalString(source, field) {
     if (value === undefined || value === null)
         return undefined;
     if (typeof value !== "string") {
-        throw new Error(`Invalid conditional order event: ${field} must be a string`);
+        throw new Error(`Invalid WebSocket event: ${field} must be a string`);
     }
     return value;
 }
 function readBoolean(source, field) {
     const value = source[field];
     if (typeof value !== "boolean") {
-        throw new Error(`Invalid conditional order event: ${field} must be a boolean`);
+        throw new Error(`Invalid WebSocket event: ${field} must be a boolean`);
     }
     return value;
 }
@@ -43,14 +43,14 @@ function readOptionalNumber(source, field) {
     if (value === undefined || value === null)
         return undefined;
     if (typeof value !== "number" || !Number.isFinite(value)) {
-        throw new Error(`Invalid conditional order event: ${field} must be a finite number`);
+        throw new Error(`Invalid WebSocket event: ${field} must be a finite number`);
     }
     return value;
 }
 function readEnum(source, field, allowed) {
     const value = readString(source, field);
     if (!allowed.includes(value)) {
-        throw new Error(`Invalid conditional order event: ${field} must be one of ${allowed.join(", ")}`);
+        throw new Error(`Invalid WebSocket event: ${field} must be one of ${allowed.join(", ")}`);
     }
     return value;
 }
@@ -59,7 +59,7 @@ function readOptionalEnum(source, field, allowed) {
     if (value === undefined || value === null)
         return undefined;
     if (typeof value !== "string" || !allowed.includes(value)) {
-        throw new Error(`Invalid conditional order event: ${field} must be one of ${allowed.join(", ")}`);
+        throw new Error(`Invalid WebSocket event: ${field} must be one of ${allowed.join(", ")}`);
     }
     return value;
 }
@@ -105,6 +105,69 @@ function parseConditionalOrderEvent(rawData) {
         },
     };
 }
+function parsePositionEvent(rawData) {
+    if (!isRecord(rawData)) {
+        throw new Error("Invalid position event: payload must be an object");
+    }
+    if (!isRecord(rawData.data)) {
+        throw new Error("Invalid position event: data must be an object");
+    }
+    const data = keysToCamelCase(rawData.data);
+    return {
+        // event_type is the event-class discriminator, validated strictly so a
+        // mis-routed frame is rejected rather than parsed as a position. The value
+        // fields below (side/status/reason) stay lenient so an unexpected *value*
+        // never drops a risk-critical update.
+        eventType: readEnum(rawData, "event_type", ["position_update"]),
+        userId: readString(rawData, "user_id"),
+        data: {
+            positionId: readString(data, "positionId"),
+            marginAccountId: readString(data, "marginAccountId"),
+            tradingPairId: readString(data, "tradingPairId"),
+            side: readString(data, "side"),
+            status: readString(data, "status"),
+            size: readString(data, "size"),
+            entryPrice: readString(data, "entryPrice"),
+            markPrice: readOptionalString(data, "markPrice"),
+            unrealizedPnl: readOptionalString(data, "unrealizedPnl"),
+            liquidationPrice: readOptionalString(data, "liquidationPrice"),
+            isolatedMargin: readString(data, "isolatedMargin"),
+            leverage: readString(data, "leverage"),
+            reason: readString(data, "reason"),
+            updatedAt: readString(data, "updatedAt"),
+        },
+    };
+}
+function parseLiquidationEvent(rawData) {
+    if (!isRecord(rawData)) {
+        throw new Error("Invalid liquidation event: payload must be an object");
+    }
+    if (!isRecord(rawData.data)) {
+        throw new Error("Invalid liquidation event: data must be an object");
+    }
+    const data = keysToCamelCase(rawData.data);
+    return {
+        // event_type is the event-class discriminator, validated strictly so a
+        // mis-routed frame is rejected rather than parsed as a liquidation. The
+        // free-form value fields below (status/accountState) stay lenient so an
+        // unexpected *value* never drops a risk-critical alert.
+        eventType: readEnum(rawData, "event_type", ["liquidation_alert"]),
+        userId: readString(rawData, "user_id"),
+        data: {
+            liquidationId: readString(data, "liquidationId"),
+            marginAccountId: readString(data, "marginAccountId"),
+            positionId: readOptionalString(data, "positionId"),
+            tradingPairId: readOptionalString(data, "tradingPairId"),
+            status: readString(data, "status"),
+            accountState: readString(data, "accountState"),
+            liquidationPrice: readOptionalString(data, "liquidationPrice"),
+            markPrice: readOptionalString(data, "markPrice"),
+            estimatedShortfall: readString(data, "estimatedShortfall"),
+            message: readString(data, "message"),
+            triggeredAt: readString(data, "triggeredAt"),
+        },
+    };
+}
 /**
  * Create a Monaco WebSocket client
  */
@@ -618,6 +681,54 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
             }
         });
     };
+    /**
+     * Subscribe to authenticated user's position updates.
+     * Requires authentication - user is identified from the signed session-key
+     * handshake. Omit `tradingPairId` for all pairs, or pass one to filter.
+     * Lag policy is Conflate: a lagging subscriber is fast-forwarded, no gap
+     * signal.
+     */
+    const subscribePositions = (handler, tradingPairId) => {
+        if (!handler) {
+            throw new Error("positions subscription requires a handler");
+        }
+        if (tradingPairId !== undefined && tradingPairId.length === 0) {
+            throw new Error("positions tradingPairId cannot be empty");
+        }
+        const channel = tradingPairId ? `positions:${tradingPairId}` : "positions";
+        return subscribe(channel, (rawData) => {
+            try {
+                handler(parsePositionEvent(rawData));
+            }
+            catch (err) {
+                console.error("WebSocket: Error processing position event", err);
+            }
+        });
+    };
+    /**
+     * Subscribe to authenticated user's liquidation alerts.
+     * Requires authentication - user is identified from the signed session-key
+     * handshake. Omit `tradingPairId` for all pairs, or pass one to filter.
+     * Lag policy is Disconnect: a subscriber that falls behind is closed with
+     * `1013`; resync by refetching a snapshot (no wire sequence number).
+     */
+    const subscribeLiquidations = (handler, tradingPairId) => {
+        if (!handler) {
+            throw new Error("liquidations subscription requires a handler");
+        }
+        if (tradingPairId !== undefined && tradingPairId.length === 0) {
+            throw new Error("liquidations tradingPairId cannot be empty");
+        }
+        const channel = tradingPairId ? `liquidations:${tradingPairId}` : "liquidations";
+        return subscribe(channel, (rawData) => {
+            try {
+                handler(parseLiquidationEvent(rawData));
+            }
+            catch (err) {
+                console.error("WebSocket: Error processing liquidation event", err);
+            }
+        });
+    };
     return {
         connect,
         disconnect,
@@ -646,5 +757,7 @@ export function createMonacoWebSocket(baseUrl, options = {}) {
         userOrders: subscribeUserOrders,
         balances: subscribeBalances,
         conditionalOrders: subscribeConditionalOrders,
+        positions: subscribePositions,
+        liquidations: subscribeLiquidations,
     };
 }

package/dist/sdk.js

@@ -201,7 +201,10 @@ export class MonacoSDKImpl {
         this.trading = new TradingAPIImpl(apiUrl);
         this.orderbook = new OrderbookAPIImpl(apiUrl);
         this.trades = new TradesAPIImpl(apiUrl);
-        this.ws = createMonacoWebSocket(wsUrl);
+        // Thread the reconnect/resync knobs and callbacks from SDK config into the
+        // internally-built ws client. The session keypair is not passed here — it
+        // is propagated on login via propagateSession/setSessionKeypair.
+        this.ws = createMonacoWebSocket(wsUrl, cfg.ws);
         // Auto-connect WebSocket, log errors
         this.ws.connect().catch(console.error);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@0xmonaco/core",
-	"version": "1.0.37",
+	"version": "1.0.38-develop.ebf8e8c",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -23,8 +23,8 @@
 		"viem": "^2.45.2"
 	},
 	"dependencies": {
-		"@0xmonaco/contracts": "1.0.37",
-		"@0xmonaco/types": "1.0.37",
+		"@0xmonaco/contracts": "1.0.38-develop.ebf8e8c",
+		"@0xmonaco/types": "1.0.38-develop.ebf8e8c",
 		"@noble/curves": "^1.9.1",
 		"@noble/hashes": "^1.8.0",
 		"http-status-codes": "^2.3.0"