@nevuamarkets/poly-websockets 0.0.1

package/src/modules/GroupSocket.ts

@@ -0,0 +1,338 @@
+import WebSocket from 'ws';
+import Bottleneck from 'bottleneck';
+import { logger } from '../logger';
+import { WebSocketGroup, WebSocketStatus } from '../types/WebSocketSubscriptions';
+import { BookEntry, OrderBookCache } from './OrderBookCache';
+import {
+    BookEvent,
+    isBookEvent,
+    isLastTradePriceEvent,
+    isPriceChangeEvent,
+    isTickSizeChangeEvent,
+    LastTradePriceEvent,
+    PriceChangeEvent,
+    TickSizeChangeEvent,
+    PolymarketWSEvent,
+    WebSocketHandlers,
+    PolymarketPriceUpdateEvent,
+} from '../types/PolymarketWebSocket';
+import _ from 'lodash';
+import ms from 'ms';
+import { randomInt } from 'crypto';
+
+const CLOB_WSS_URL = 'wss://ws-subscriptions-clob.polymarket.com/ws/market';
+
+export class GroupSocket {
+    private pingInterval?: NodeJS.Timeout;
+
+    constructor(
+        private group: WebSocketGroup,
+        private limiter: Bottleneck,
+        private bookCache: OrderBookCache,
+        private handlers: WebSocketHandlers,
+    ) {}
+
+    /**
+     * Establish the websocket connection using the provided Bottleneck limiter.
+     * 
+     */
+    public async connect(): Promise<void> {
+        if (this.group.assetIds.size === 0) {
+            this.group.status = WebSocketStatus.CLEANUP;
+            return;
+        }
+
+        try {
+            logger.info({
+                message: 'Connecting to CLOB WebSocket',
+                groupId: this.group.groupId,
+                assetIdsLength: this.group.assetIds.size,
+            });
+            this.group.wsClient = await this.limiter.schedule({ priority: 0 }, async () => { 
+                const ws = new WebSocket(CLOB_WSS_URL);
+                /*
+                    This handler will be replaced by the handlers in setupEventHandlers
+                */
+                ws.on('error', (err) => {
+                    logger.warn({
+                        message: 'Error connecting to CLOB WebSocket',
+                        error: err,
+                        groupId: this.group.groupId,
+                        assetIdsLength: this.group.assetIds.size,
+                    });
+                });
+                return ws;
+            });
+        } catch (err) {
+            this.group.status = WebSocketStatus.DEAD;
+            throw err; // caller responsible for error handler
+        }
+
+        this.setupEventHandlers();
+    }
+
+    private setupEventHandlers() {
+        const group = this.group;
+        const handlers = this.handlers;
+
+        /*
+            Define handlers within this scope to capture 'this' context
+        */
+        const handleOpen = async () => {
+            if (group.assetIds.size === 0) {
+                group.status = WebSocketStatus.CLEANUP;
+                return;
+            }
+
+            group.status = WebSocketStatus.ALIVE;
+
+            group.wsClient!.send(JSON.stringify({ assets_ids: Array.from(group.assetIds), type: 'market' }));
+            await handlers.onWSOpen?.(group.groupId, Array.from(group.assetIds));
+
+            this.pingInterval = setInterval(() => {
+                if (group.assetIds.size === 0) {
+                    clearInterval(this.pingInterval);
+                    group.status = WebSocketStatus.CLEANUP;
+                    return;
+                }
+
+                if (!group.wsClient) {
+                    clearInterval(this.pingInterval);
+                    group.status = WebSocketStatus.DEAD;
+                    return;
+                }
+                group.wsClient.ping();
+            }, randomInt(ms('15s'), ms('25s')));
+        };
+
+        const handleMessage = async (data: Buffer) => {
+            let events: PolymarketWSEvent[] = [];
+            try {
+                const parsedData: any = JSON.parse(data.toString());
+                events = Array.isArray(parsedData) ? parsedData : [parsedData];
+            } catch (err) {
+                await handlers.onError?.(new Error(`Not JSON: ${data.toString()}`));
+                return;
+            }
+
+            events = _.filter(events, (event: PolymarketWSEvent) => _.size(event.asset_id) > 0);
+
+            const bookEvents: BookEvent[] = [];
+            const lastTradeEvents: LastTradePriceEvent[] = [];
+            const tickEvents: TickSizeChangeEvent[] = [];
+            const priceChangeEvents: PriceChangeEvent[] = [];
+
+            for (const event of events) {
+                /* 
+                    Skip events for asset ids that are not in the group to ensure that
+                    we don't get stale events for assets that were removed.
+                */
+                if (!group.assetIds.has(event.asset_id)) {
+                    continue;
+                }
+
+                if (isBookEvent(event)) {
+                    bookEvents.push(event);
+                } else if (isLastTradePriceEvent(event)) {
+                    lastTradeEvents.push(event);
+                } else if (isTickSizeChangeEvent(event)) {
+                    tickEvents.push(event);
+                } else if (isPriceChangeEvent(event)) {
+                    priceChangeEvents.push(event);
+                }
+                else {
+                    await handlers.onError?.(new Error(`Unknown event: ${JSON.stringify(event)}`));
+                }
+            }
+
+            await this.handleBookEvents(bookEvents);
+            await this.handleTickEvents(tickEvents);
+            await this.handlePriceChangeEvents(priceChangeEvents);
+            await this.handleLastTradeEvents(lastTradeEvents);
+        };
+
+        const handlePong = () => {
+            group.groupId;
+        };
+
+        const handleError = (err: Error) => {
+            group.status = WebSocketStatus.DEAD;
+            clearInterval(this.pingInterval);
+            handlers.onError?.(new Error(`WebSocket error for group ${group.groupId}: ${err.message}`));
+        };
+
+        const handleClose = async (code: number, reason: Buffer) => {
+            group.status = WebSocketStatus.DEAD;
+            clearInterval(this.pingInterval);
+            await handlers.onWSClose?.(group.groupId, code, reason.toString());
+        };
+
+        if (group.wsClient) {
+            // Remove any existing handlers
+            group.wsClient.removeAllListeners();
+
+            // Add the handlers
+            group.wsClient.on('open', handleOpen);
+            group.wsClient.on('message', handleMessage);
+            group.wsClient.on('pong', handlePong);
+            group.wsClient.on('error', handleError);
+            group.wsClient.on('close', handleClose);
+        }
+
+        if (group.assetIds.size === 0) {
+            group.status = WebSocketStatus.CLEANUP;
+            return;
+        }
+
+        if (!group.wsClient) {
+            group.status = WebSocketStatus.DEAD;
+            return;
+        }
+    }
+
+    private async handleBookEvents(bookEvents: BookEvent[]): Promise<void> {
+        if (bookEvents.length) {
+            for (const event of bookEvents) {
+                this.bookCache.replaceBook(event);
+            }
+            await this.handlers.onBook?.(bookEvents);
+        }
+    }
+
+    private async handleTickEvents(tickEvents: TickSizeChangeEvent[]): Promise<void> {
+        if (tickEvents.length) {
+            await this.handlers.onTickSizeChange?.(tickEvents);
+        }
+    }
+
+    private async handlePriceChangeEvents(priceChangeEvents: PriceChangeEvent[]): Promise<void> {
+        if (priceChangeEvents.length) {
+            await this.handlers.onPriceChange?.(priceChangeEvents);
+
+            for (const event of priceChangeEvents) {
+                try {
+                    this.bookCache.upsertPriceChange(event);
+                } catch (err) {
+                    logger.warn({ 
+                        message: `Skipping price_change: book not found for asset`, 
+                        asset_id: event.asset_id, 
+                        event: event,
+                        error: err 
+                    });
+                    continue;
+                }
+
+                let spreadOver10Cents: boolean;
+                try {
+                    spreadOver10Cents = this.bookCache.spreadOver(event.asset_id, 0.1);
+                } catch (err) {
+                    logger.warn({ 
+                        message: 'Skipping price_change: error calculating spread', 
+                        asset_id: event.asset_id, 
+                        event: event,
+                        error: err 
+                    });
+                    await this.handlers.onError?.(err as Error);
+                    continue;
+                }
+
+                if (!spreadOver10Cents) {
+                    let newPrice: string;
+                    try {
+                        newPrice = this.bookCache.midpoint(event.asset_id);
+                    } catch (err) {
+                        logger.warn({ 
+                            message: 'Skipping price_change: error calculating midpoint', 
+                            asset_id: event.asset_id, 
+                            event: event,
+                            error: err 
+                        });
+                        await this.handlers.onError?.(err as Error);
+                        continue;
+                    }
+
+                    const bookEntry: BookEntry | null = this.bookCache.getBookEntry(event.asset_id);
+                    if (!bookEntry) {
+                        logger.warn({ 
+                            message: 'Skipping price_change: book not found for asset', 
+                            asset_id: event.asset_id, 
+                            event: event,
+                        });
+                        continue;
+                    }
+
+                    if (newPrice !== bookEntry.price) {
+                        bookEntry.price = newPrice;
+                        const priceUpdateEvent: PolymarketPriceUpdateEvent = {
+                            asset_id: event.asset_id,
+                            event_type: 'price_update',
+                            triggeringEvent: event,
+                            timestamp: event.timestamp,
+                            book: { bids: bookEntry.bids, asks: bookEntry.asks },
+                            price: newPrice,
+                            midpoint: bookEntry.midpoint || '',
+                            spread: bookEntry.spread || '',
+                        };
+                        await this.handlers.onPolymarketPriceUpdate?.([priceUpdateEvent]);
+                    }
+                }
+            }
+        }
+    }
+
+    private async handleLastTradeEvents(lastTradeEvents: LastTradePriceEvent[]): Promise<void> {
+        if (lastTradeEvents.length) {
+            /*
+                Note: There is no need to edit the book here. According to the docs, a separate
+                book event is sent when a trade affects the book.
+
+                See: https://docs.polymarket.com/developers/CLOB/websocket/market-channel#book-message
+            */
+            await this.handlers.onLastTradePrice?.(lastTradeEvents);
+
+            for (const event of lastTradeEvents) {
+                let spreadOver10Cents: boolean;
+                try {
+                    spreadOver10Cents = this.bookCache.spreadOver(event.asset_id, 0.1);
+                } catch (err) {
+                    logger.warn({ 
+                        message: 'Skipping last_trade_price: error calculating spread', 
+                        asset_id: event.asset_id, 
+                        event: event,
+                        error: err 
+                    });
+                    await this.handlers.onError?.(err as Error);
+                    continue;
+                }
+                if (spreadOver10Cents) {
+                    // Ensure no trailing zeros
+                    const newPrice = parseFloat(event.price).toString();
+
+                    const bookEntry: BookEntry | null = this.bookCache.getBookEntry(event.asset_id);
+                    if (!bookEntry) {
+                        logger.warn({ 
+                            message: 'Skipping last_trade_price: book not found for asset', 
+                            asset_id: event.asset_id, 
+                            event: event,
+                        });
+                        continue;
+                    }
+                    if (newPrice !== bookEntry.price) {
+                        bookEntry.price = newPrice;
+                        const priceUpdateEvent: PolymarketPriceUpdateEvent = {
+                            asset_id: event.asset_id,
+                            event_type: 'price_update',
+                            triggeringEvent: event,
+                            timestamp: event.timestamp,
+                            book: { bids: bookEntry.bids, asks: bookEntry.asks },
+                            price: newPrice,
+                            midpoint: bookEntry.midpoint || '',
+                            spread: bookEntry.spread || '',
+                        };
+                        await this.handlers.onPolymarketPriceUpdate?.([priceUpdateEvent]);
+                    }
+                }
+            }
+        }
+    }
+} 

package/src/modules/OrderBookCache.ts

@@ -0,0 +1,208 @@
+import _ from 'lodash';
+import {
+    BookEvent,
+    PriceChangeEvent,
+    PriceLevel,
+} from '../types/PolymarketWebSocket';
+
+/*
+ * Shared book cache store – exported so legacy code paths can keep using it
+ * until the refactor is complete.
+ */
+export interface BookEntry {
+    bids: PriceLevel[];
+    asks: PriceLevel[];
+    price: string | null;
+    midpoint: string | null;
+    spread: string | null;
+}
+
+export 
+
+function sortDescendingInPlace(bookSide: PriceLevel[]): void {
+    bookSide.sort((a, b) => parseFloat(b.price) - parseFloat(a.price));
+}
+
+function sortAscendingInPlace(bookSide: PriceLevel[]): void {
+    bookSide.sort((a, b) => parseFloat(a.price) - parseFloat(b.price));
+}
+
+export class OrderBookCache {
+    private bookCache: { 
+        [assetId: string]: BookEntry 
+    } = {};
+
+    constructor() {}
+
+    /**
+     * Replace full book (after a `book` event)
+     */
+    public replaceBook(event: BookEvent): void {
+        let lastPrice = null;
+        let lastMidpoint = null;
+        let lastSpread = null;
+        if (this.bookCache[event.asset_id]) {
+            lastPrice = this.bookCache[event.asset_id].price;
+            lastMidpoint = this.bookCache[event.asset_id].midpoint;
+            lastSpread = this.bookCache[event.asset_id].spread;
+        }
+
+        this.bookCache[event.asset_id] = {
+            bids: [...event.bids],
+            asks: [...event.asks],
+            price: lastPrice,
+            midpoint: lastMidpoint,
+            spread: lastSpread,
+        };
+
+        /* Polymarket book events are currently sorted as such:
+         * - bids (buys) ascending
+         * - asks (sells) descending
+         * 
+         * So we maintain this order in the cache.
+         */
+        sortAscendingInPlace(this.bookCache[event.asset_id].bids);
+        sortDescendingInPlace(this.bookCache[event.asset_id].asks);
+    }
+
+    /**
+     * Update a cached book from a `price_change` event.
+     * 
+     * Returns true if the book was updated.
+     * Throws if the book is not found.
+     */
+    public upsertPriceChange(event: PriceChangeEvent): void {
+        const book = this.bookCache[event.asset_id];
+        if (!book) {
+            throw new Error(`Book not found for asset ${event.asset_id}`);
+        }
+
+        for (const change of event.changes) {
+            const { price, size, side } = change;
+            if (side === 'BUY') {
+                const i = book.bids.findIndex(bid => bid.price === price);
+                if (i !== -1) {
+                    book.bids[i].size = size;
+                } else {
+                    book.bids.push({ price, size });
+                    
+                    // Ensure the bids are sorted ascending
+                    sortAscendingInPlace(book.bids);
+                }
+            } else {
+                const i = book.asks.findIndex(ask => ask.price === price);
+                if (i !== -1) {
+                    book.asks[i].size = size;
+                } else {
+                    book.asks.push({ price, size });
+
+                    // Ensure the asks are sorted descending
+                    sortDescendingInPlace(book.asks);
+                }
+            }
+        }
+    }
+
+    /**
+     * Return `true` if best-bid/best-ask spread exceeds `cents`.
+     * 
+     * Side effect: updates the book's spread
+     * 
+     * Throws if either side of the book is empty.
+     */
+    public spreadOver(assetId: string, cents = 0.1): boolean {
+        const book = this.bookCache[assetId];
+        if (!book) throw new Error(`Book for ${assetId} not cached`);
+        if (book.asks.length === 0) throw new Error('No asks in book');
+        if (book.bids.length === 0) throw new Error('No bids in book');
+
+        /*
+         * Polymarket book events are currently sorted as such:
+         * - bids ascending
+         * - asks descending
+         */
+        
+        const highestBid = book.bids[book.bids.length - 1].price;
+        const lowestAsk = book.asks[book.asks.length - 1].price;
+        
+        const highestBidNum = parseFloat(highestBid);
+        const lowestAskNum = parseFloat(lowestAsk);
+
+        const spread = lowestAskNum - highestBidNum;
+
+        if (isNaN(spread)) {
+            throw new Error(`Spread is NaN: lowestAsk '${lowestAsk}' highestBid '${highestBid}'`);
+        }
+
+        /*
+        *   Update spead, 3 precision decimal places, trim trailing zeros
+        */
+        book.spread = parseFloat(spread.toFixed(3)).toString();
+
+        // Should be safe for 0.### - precision values
+        return spread > cents;
+    }
+
+    /** 
+     * Calculate the midpoint of the book, rounded to 3dp, no trailing zeros 
+     * 
+     * Side effect: updates the book's midpoint
+     * 
+     * Throws if
+     * - the book is not found or missing either bid or ask
+     * - the midpoint is NaN.
+    */
+    public midpoint(assetId: string): string {
+        const book = this.bookCache[assetId];
+        if (!book) throw new Error(`Book for ${assetId} not cached`);
+        if (book.asks.length === 0) throw new Error('No asks in book');
+        if (book.bids.length === 0) throw new Error('No bids in book');
+
+        /*
+         * Polymarket book events are currently sorted as such:
+         * - bids ascending
+         * - asks descending
+         */
+        const highestBid = book.bids[book.bids.length - 1].price;
+        const lowestAsk = book.asks[book.asks.length - 1].price;
+
+        const highestBidNum = parseFloat(highestBid);
+        const lowestAskNum = parseFloat(lowestAsk);
+
+        const midpoint = (highestBidNum + lowestAskNum) / 2;
+
+        if (isNaN(midpoint)) {
+            throw new Error(`Midpoint is NaN: lowestAsk '${lowestAsk}' highestBid '${highestBid}'`);
+        }
+
+        /*
+        *   Update midpoint, 3 precision decimal places, trim trailing zeros
+        */
+        book.midpoint = parseFloat(midpoint.toFixed(3)).toString();
+
+        return parseFloat(midpoint.toFixed(3)).toString();
+    }
+
+    public clear(assetId?: string): void {
+        if (assetId) {
+            delete this.bookCache[assetId];
+        } else {
+            for (const k of Object.keys(this.bookCache)) {
+                delete this.bookCache[k];
+            }
+        }
+    }
+
+    /**
+     * Get a book entry by asset id.
+     * 
+     * Return null if the book is not found.
+     */
+    public getBookEntry(assetId: string): BookEntry | null {
+        if (!this.bookCache[assetId]) {
+            return null;
+        }
+        return this.bookCache[assetId];
+    }
+
+}