pmxtjs 2.35.29 → 2.35.32

package/pmxt/client.ts

@@ -44,6 +44,7 @@ import { ServerManager } from "./server-manager.js";
 import { buildArgsWithOptionalOptions } from "./args.js";
 import { PmxtError, fromServerError } from "./errors.js";
 import { LOCAL_URL, resolvePmxtBaseUrl } from "./constants.js";
+import { SidecarWsClient } from "./ws-client.js";
 
 /**
  * Resolve a MarketOutcome shorthand to a plain outcome ID string.
@@ -348,6 +349,11 @@ export abstract class Exchange {
      */
     private _getReadsUnsupported: boolean = false;
 
+    /** Shared WebSocket client for streaming methods (lazy). */
+    private _wsClient: SidecarWsClient | null = null;
+    /** Sticky flag: true if the sidecar /ws endpoint is unavailable. */
+    private _wsUnsupported: boolean = false;
+
     constructor(exchangeName: string, options: ExchangeOptions = {}) {
         this.exchangeName = exchangeName.toLowerCase();
         this.apiKey = options.apiKey;
@@ -502,6 +508,73 @@ export abstract class Exchange {
         throw lastError;
     }
 
+    /**
+     * Return the shared WebSocket client, creating it on first use.
+     *
+     * Returns `null` if the sidecar /ws endpoint was previously found
+     * to be unavailable, letting callers fall back to HTTP.
+     */
+    private async getOrCreateWs(): Promise<SidecarWsClient | null> {
+        if (this._wsUnsupported) return null;
+        if (this._wsClient?.connected) return this._wsClient;
+
+        const host = this.resolveBaseUrl();
+        const accessToken = this.serverManager.getAccessToken();
+
+        const client = new SidecarWsClient(host, accessToken || undefined);
+        try {
+            // Trigger connection to validate the endpoint exists.
+            // subscribe() calls ensureConnected internally, but we want
+            // to detect failure eagerly so we can set _wsUnsupported.
+            await client.subscribe(
+                this.exchangeName,
+                "_ping",
+                [],
+                undefined,
+                3000,
+            ).catch(() => {
+                // Expected -- no _ping method. The connection itself
+                // succeeded if we got a WS error frame back. If the
+                // connection itself failed, we'll catch below.
+            });
+            // If we got here without the connect promise rejecting,
+            // the WS endpoint exists.
+            if (!client.connected) {
+                throw new Error("WS handshake failed");
+            }
+        } catch {
+            this._wsUnsupported = true;
+            client.close();
+            return null;
+        }
+
+        this._wsClient = client;
+        return this._wsClient;
+    }
+
+    /**
+     * Attempt to use the WS transport for a watch method.
+     * Returns the raw data on success, or `null` if WS is unavailable.
+     */
+    private async watchViaWs(
+        method: string,
+        args: any[],
+    ): Promise<any | null> {
+        const ws = await this.getOrCreateWs();
+        if (!ws) return null;
+
+        try {
+            return await ws.subscribe(
+                this.exchangeName,
+                method,
+                args,
+                this.getCredentials() as Record<string, any> | undefined,
+            );
+        } catch {
+            return null;
+        }
+    }
+
     // Low-Level API Access
 
     /**
@@ -1432,12 +1505,19 @@ export abstract class Exchange {
     async watchOrderBook(outcomeId: string | MarketOutcome, limit?: number): Promise<OrderBook> {
         await this.initPromise;
         const resolvedOutcomeId = resolveOutcomeId(outcomeId);
-        try {
-            const args: any[] = [resolvedOutcomeId];
-            if (limit !== undefined) {
-                args.push(limit);
-            }
+        const args: any[] = [resolvedOutcomeId];
+        if (limit !== undefined) {
+            args.push(limit);
+        }
 
+        // Try WebSocket transport first
+        const wsData = await this.watchViaWs("watchOrderBook", args);
+        if (wsData !== null) {
+            return convertOrderBook(wsData);
+        }
+
+        // HTTP fallback
+        try {
             const response = await this.fetchWithRetry(`${this.resolveBaseUrl()}/api/${this.exchangeName}/watchOrderBook`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
@@ -1459,18 +1539,111 @@ export abstract class Exchange {
         }
     }
 
+    /**
+     * Watch real-time order book updates for multiple outcomes at once.
+     *
+     * Returns a record mapping each outcome ID (ticker) to its latest
+     * order book snapshot. Call repeatedly in a loop to stream updates
+     * (CCXT Pro pattern).
+     *
+     * Prefers the sidecar WebSocket transport when available, falling
+     * back to HTTP POST for older sidecars.
+     *
+     * @param outcomeIds - Array of outcome IDs (or MarketOutcome objects)
+     * @param limit - Optional depth limit for each order book
+     * @returns Record mapping ticker to OrderBook
+     *
+     * @example
+     * ```typescript
+     * const ids = markets.slice(0, 3).map(m => m.outcomes[0].outcomeId);
+     * while (true) {
+     *   const books = await exchange.watchOrderBooks(ids);
+     *   for (const [ticker, ob] of Object.entries(books)) {
+     *     console.log(`${ticker}: bid=${ob.bids[0]?.price}`);
+     *   }
+     * }
+     * ```
+     */
+    async watchOrderBooks(
+        outcomeIds: (string | MarketOutcome)[],
+        limit?: number,
+    ): Promise<Record<string, OrderBook>> {
+        await this.initPromise;
+        const resolvedIds = outcomeIds.map(resolveOutcomeId);
+        const args: any[] = [resolvedIds];
+        if (limit !== undefined) {
+            args.push(limit);
+        }
+
+        // Try WebSocket transport first
+        const ws = await this.getOrCreateWs();
+        if (ws) {
+            try {
+                const rawResult = await ws.subscribeBatch(
+                    this.exchangeName,
+                    "watchOrderBooks",
+                    args,
+                    this.getCredentials() as Record<string, any> | undefined,
+                );
+                if (rawResult && typeof rawResult === "object") {
+                    const result: Record<string, OrderBook> = {};
+                    for (const [k, v] of Object.entries(rawResult)) {
+                        if (v && typeof v === "object") {
+                            result[k] = convertOrderBook(v);
+                        }
+                    }
+                    return result;
+                }
+            } catch {
+                // fall through to HTTP
+            }
+        }
+
+        // HTTP fallback
+        try {
+            const response = await this.fetchWithRetry(
+                `${this.resolveBaseUrl()}/api/${this.exchangeName}/watchOrderBooks`,
+                {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
+                    body: JSON.stringify({ args, credentials: this.getCredentials() }),
+                },
+            );
+            if (!response.ok) {
+                const body = await response.json().catch(() => ({}));
+                if (body.error && typeof body.error === "object") {
+                    throw fromServerError(body.error);
+                }
+                throw new PmxtError(body.error?.message || response.statusText);
+            }
+            const json = await response.json();
+            const data = this.handleResponse(json);
+            if (data && typeof data === "object") {
+                const result: Record<string, OrderBook> = {};
+                for (const [k, v] of Object.entries(data as Record<string, any>)) {
+                    result[k] = convertOrderBook(v);
+                }
+                return result;
+            }
+            return {};
+        } catch (error) {
+            if (error instanceof PmxtError) throw error;
+            throw new PmxtError(`Failed to watch order books: ${error}`);
+        }
+    }
+
     /**
      * Watch real-time trade updates via WebSocket.
-     * 
+     *
      * Returns a promise that resolves with the next trade(s).
      * Call repeatedly in a loop to stream updates (CCXT Pro pattern).
-     * 
+     *
      * @param outcomeId - Outcome ID to watch
      * @param address - Public wallet to be watched
      * @param since - Optional timestamp to filter trades from
      * @param limit - Optional limit for number of trades
      * @returns Next trade update(s)
-     * 
+     *
      * @example
      * ```typescript
      * // Stream trade updates

package/pmxt/ws-client.ts

@@ -0,0 +1,347 @@
+/**
+ * WebSocket client for streaming methods.
+ *
+ * Provides a multiplexed WebSocket connection to the sidecar server,
+ * used by watchOrderBook and watchOrderBooks as an alternative to
+ * HTTP long-polling. Falls back to HTTP transparently when the sidecar
+ * does not support the /ws endpoint.
+ */
+
+import { PmxtError } from "./errors.js";
+
+interface WsSubscription {
+    readonly requestId: string;
+    readonly method: string;
+    readonly symbols: string[];
+    resolve: ((data: any) => void) | null;
+    reject: ((error: Error) => void) | null;
+}
+
+interface WsMessage {
+    id?: string;
+    event?: string;
+    method?: string;
+    symbol?: string;
+    data?: any;
+    error?: { message?: string; code?: string };
+}
+
+/**
+ * Multiplexed WebSocket client for the pmxt sidecar.
+ *
+ * Lazily connects to ws://{host}/ws?token={accessToken}. A single
+ * WebSocket connection is shared across all streaming subscriptions.
+ */
+export class SidecarWsClient {
+    private ws: WebSocket | null = null;
+    private host: string;
+    private accessToken: string | undefined;
+    private closed = false;
+
+    /** requestId -> latest data payload */
+    private dataStore: Map<string, any> = new Map();
+    /** requestId -> subscription metadata */
+    private subscriptions: Map<string, WsSubscription> = new Map();
+    /** (method:symbolKey) -> requestId -- avoids duplicate subscribes */
+    private activeSubs: Map<string, string> = new Map();
+
+    private connectPromise: Promise<void> | null = null;
+
+    constructor(host: string, accessToken?: string) {
+        this.host = host;
+        this.accessToken = accessToken;
+    }
+
+    // ------------------------------------------------------------------
+    // Connection lifecycle
+    // ------------------------------------------------------------------
+
+    private async ensureConnected(): Promise<void> {
+        if (this.ws && !this.closed) return;
+        if (this.connectPromise) return this.connectPromise;
+
+        this.connectPromise = this.connect();
+        try {
+            await this.connectPromise;
+        } finally {
+            this.connectPromise = null;
+        }
+    }
+
+    private connect(): Promise<void> {
+        return new Promise<void>((resolve, reject) => {
+            let hostPart = this.host;
+            let scheme = "ws";
+            if (hostPart.startsWith("https://")) {
+                hostPart = hostPart.slice("https://".length);
+                scheme = "wss";
+            } else if (hostPart.startsWith("http://")) {
+                hostPart = hostPart.slice("http://".length);
+            }
+
+            let url = `${scheme}://${hostPart}/ws`;
+            if (this.accessToken) {
+                url = `${url}?token=${this.accessToken}`;
+            }
+
+            // Use the ws package in Node.js, native WebSocket in browsers
+            const WsConstructor = this.getWebSocketConstructor();
+            if (!WsConstructor) {
+                reject(new PmxtError("No WebSocket implementation available"));
+                return;
+            }
+
+            const ws = new WsConstructor(url);
+            this.closed = false;
+
+            ws.onopen = () => {
+                this.ws = ws;
+                resolve();
+            };
+
+            ws.onerror = (err: any) => {
+                if (!this.ws) {
+                    // Connection failed during handshake
+                    reject(new PmxtError(`WebSocket connection failed: ${err.message || err}`));
+                }
+            };
+
+            ws.onclose = () => {
+                this.closed = true;
+                this.ws = null;
+            };
+
+            ws.onmessage = (event: any) => {
+                try {
+                    const data = typeof event.data === "string"
+                        ? event.data
+                        : event.data.toString();
+                    const msg: WsMessage = JSON.parse(data);
+                    this.dispatch(msg);
+                } catch {
+                    // Ignore unparseable frames
+                }
+            };
+        });
+    }
+
+    private getWebSocketConstructor(): (new (url: string) => WebSocket) | null {
+        // Browser / Deno / Bun
+        if (typeof globalThis !== "undefined" && (globalThis as any).WebSocket) {
+            return (globalThis as any).WebSocket;
+        }
+        // Node.js -- try to require ws
+        try {
+            // Dynamic require to avoid bundler issues
+            const wsModule = require("ws");
+            return wsModule.default || wsModule;
+        } catch {
+            return null;
+        }
+    }
+
+    private dispatch(msg: WsMessage): void {
+        const eventType = msg.event;
+        const requestId = msg.id;
+
+        if (eventType === "error" && requestId) {
+            const sub = this.subscriptions.get(requestId);
+            if (sub?.reject) {
+                sub.reject(new PmxtError(
+                    msg.error?.message || "WebSocket subscription error"
+                ));
+                sub.reject = null;
+                sub.resolve = null;
+            }
+            return;
+        }
+
+        if (eventType === "subscribed") {
+            // Acknowledgement -- nothing to do
+            return;
+        }
+
+        if (eventType === "data" && requestId) {
+            const symbol = msg.symbol || "";
+            const data = msg.data || {};
+
+            // Store by (requestId:symbol) for batch methods
+            this.dataStore.set(`${requestId}:${symbol}`, data);
+            // Store by requestId alone for single-symbol methods
+            this.dataStore.set(requestId, data);
+
+            const sub = this.subscriptions.get(requestId);
+            if (sub?.resolve) {
+                sub.resolve(data);
+                sub.resolve = null;
+                sub.reject = null;
+            }
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // Public API
+    // ------------------------------------------------------------------
+
+    async subscribe(
+        exchange: string,
+        method: string,
+        args: any[],
+        credentials?: Record<string, any>,
+        timeoutMs = 30000,
+    ): Promise<any> {
+        const firstArg = args[0] ?? "";
+        const subKey = Array.isArray(firstArg)
+            ? `${method}:${[...firstArg].sort().join(",")}`
+            : `${method}:${firstArg}`;
+
+        // Reuse existing subscription
+        const existingId = this.activeSubs.get(subKey);
+        if (existingId && this.subscriptions.has(existingId)) {
+            return this.waitForData(existingId, timeoutMs);
+        }
+
+        await this.ensureConnected();
+
+        const requestId = `req-${Math.random().toString(36).slice(2, 14)}`;
+        const symbols = Array.isArray(firstArg) ? firstArg : firstArg ? [firstArg] : [];
+
+        const sub: WsSubscription = {
+            requestId,
+            method,
+            symbols,
+            resolve: null,
+            reject: null,
+        };
+        this.subscriptions.set(requestId, sub);
+        this.activeSubs.set(subKey, requestId);
+
+        const message: Record<string, any> = {
+            id: requestId,
+            action: "subscribe",
+            exchange,
+            method,
+            args,
+        };
+        if (credentials) {
+            message.credentials = credentials;
+        }
+
+        this.ws!.send(JSON.stringify(message));
+
+        return this.waitForData(requestId, timeoutMs);
+    }
+
+    async subscribeBatch(
+        exchange: string,
+        method: string,
+        args: any[],
+        credentials?: Record<string, any>,
+        timeoutMs = 30000,
+    ): Promise<Record<string, any>> {
+        const symbols: string[] = Array.isArray(args[0]) ? args[0] : [];
+
+        await this.ensureConnected();
+
+        const requestId = `req-${Math.random().toString(36).slice(2, 14)}`;
+
+        const sub: WsSubscription = {
+            requestId,
+            method,
+            symbols,
+            resolve: null,
+            reject: null,
+        };
+        this.subscriptions.set(requestId, sub);
+
+        const message: Record<string, any> = {
+            id: requestId,
+            action: "subscribe",
+            exchange,
+            method,
+            args,
+        };
+        if (credentials) {
+            message.credentials = credentials;
+        }
+
+        this.ws!.send(JSON.stringify(message));
+
+        // Wait for first data event
+        await this.waitForData(requestId, timeoutMs);
+
+        // Collect per-symbol data
+        const result: Record<string, any> = {};
+        for (const symbol of symbols) {
+            const storeKey = `${requestId}:${symbol}`;
+            const data = this.dataStore.get(storeKey);
+            if (data !== undefined) {
+                result[symbol] = data;
+            }
+        }
+
+        // If no per-symbol data, return the single data event as-is
+        if (Object.keys(result).length === 0) {
+            const data = this.dataStore.get(requestId);
+            if (data && typeof data === "object") {
+                return data;
+            }
+        }
+
+        return result;
+    }
+
+    close(): void {
+        this.closed = true;
+        if (this.ws) {
+            try {
+                this.ws.close();
+            } catch {
+                // ignore
+            }
+            this.ws = null;
+        }
+    }
+
+    get connected(): boolean {
+        return this.ws !== null && !this.closed;
+    }
+
+    // ------------------------------------------------------------------
+    // Internal
+    // ------------------------------------------------------------------
+
+    private waitForData(requestId: string, timeoutMs: number): Promise<any> {
+        // Check if data is already available
+        const existing = this.dataStore.get(requestId);
+        if (existing !== undefined) {
+            this.dataStore.delete(requestId);
+            return Promise.resolve(existing);
+        }
+
+        return new Promise<any>((resolve, reject) => {
+            const sub = this.subscriptions.get(requestId);
+            if (!sub) {
+                reject(new PmxtError("Subscription not found"));
+                return;
+            }
+
+            const timer = setTimeout(() => {
+                sub.resolve = null;
+                sub.reject = null;
+                reject(new PmxtError(
+                    `Timeout waiting for WebSocket data (method=${sub.method})`
+                ));
+            }, timeoutMs);
+
+            sub.resolve = (data: any) => {
+                clearTimeout(timer);
+                resolve(data);
+            };
+            sub.reject = (err: Error) => {
+                clearTimeout(timer);
+                reject(err);
+            };
+        });
+    }
+}