@nevuamarkets/poly-websockets 0.0.1

package/dist/modules/OrderBookCache.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderBookCache = void 0;
+exports.sortDescendingInPlace = sortDescendingInPlace;
+function sortDescendingInPlace(bookSide) {
+    bookSide.sort((a, b) => parseFloat(b.price) - parseFloat(a.price));
+}
+function sortAscendingInPlace(bookSide) {
+    bookSide.sort((a, b) => parseFloat(a.price) - parseFloat(b.price));
+}
+class OrderBookCache {
+    constructor() {
+        this.bookCache = {};
+    }
+    /**
+     * Replace full book (after a `book` event)
+     */
+    replaceBook(event) {
+        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.
+     */
+    upsertPriceChange(event) {
+        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.
+     */
+    spreadOver(assetId, cents = 0.1) {
+        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.
+    */
+    midpoint(assetId) {
+        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();
+    }
+    clear(assetId) {
+        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.
+     */
+    getBookEntry(assetId) {
+        if (!this.bookCache[assetId]) {
+            return null;
+        }
+        return this.bookCache[assetId];
+    }
+}
+exports.OrderBookCache = OrderBookCache;

package/dist/types/PolymarketWebSocket.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Represents a single price level in the order book
+ * @example
+ * { price: "0.01", size: "510000" }
+ */
+export type PriceLevel = {
+    price: string;
+    size: string;
+};
+/**
+ * Represents a price_change event from Polymarket WebSocket
+ * @example
+ * {
+ *   asset_id: "39327269875426915204597944387916069897800289788920336317845465327697809453999",
+ *   changes: [
+ *     { price: "0.044", side: "SELL", size: "611" }
+ *   ],
+ *   event_type: "price_change",
+ *   hash: "a0b7cadf869fc288dbbf65704996fe818cc97d6a",
+ *   market: "0x5412ae25e97078f814157de948459d59c6221b4c4c495fdd57b536543ad36729",
+ *   timestamp: "1749371014925"
+ * }
+ */
+export type PriceChangeEvent = {
+    asset_id: string;
+    changes: {
+        price: string;
+        side: string;
+        size: string;
+    }[];
+    event_type: 'price_change';
+    hash: string;
+    market: string;
+    timestamp: string;
+};
+/**
+ * Represents a Polymarket book
+ * @example
+ * {
+ *  bids: [
+ *    { price: "0.01", size: "510000" },
+ *    { price: "0.02", size: "3100" }
+ *  ],
+ *  asks: [
+ *    { price: "0.99", size: "58.07" },
+ *    { price: "0.97", size: "178.73" }
+ * }
+ */
+export type Book = {
+    bids: PriceLevel[];
+    asks: PriceLevel[];
+};
+/**
+ * Represents a book event from Polymarket WebSocket
+ * @example
+ * {
+ *   market: "0xf83fb46dd70a4459fcc441a8511701c463374c5c3c250f585d74fda85ddfb7c9",
+ *   asset_id: "101007741586870489619361069512452187353898396425142157315847015703471254508752",
+ *   timestamp: "1740759191594",
+ *   hash: "c0e51b1cfdbcb1b2aec58feaf7b01004019a89c6",
+ *   bids: [
+ *     { price: "0.01", size: "510000" },
+ *     { price: "0.02", size: "3100" }
+ *   ],
+ *   asks: [
+ *     { price: "0.99", size: "58.07" },
+ *     { price: "0.97", size: "178.73" }
+ *   ],
+ *   event_type: "book"
+ * }
+ */
+export type BookEvent = {
+    market: string;
+    asset_id: string;
+    timestamp: string;
+    hash: string;
+    bids: PriceLevel[];
+    asks: PriceLevel[];
+    event_type: 'book';
+};
+/**
+ * Represents a last trade price event from Polymarket WebSocket
+ * @example
+ * {
+ *   asset_id: "101007741586870489619361069512452187353898396425142157315847015703471254508752",
+ *   event_type: "last_trade_price",
+ *   fee_rate_bps: "0",
+ *   market: "0xf83fb46dd70a4459fcc441a8511701c463374c5c3c250f585d74fda85ddfb7c9",
+ *   price: "0.12",
+ *   side: "BUY",
+ *   size: "8.333332",
+ *   timestamp: "1740760245471"
+ * }
+ */
+export type LastTradePriceEvent = {
+    asset_id: string;
+    event_type: 'last_trade_price';
+    fee_rate_bps: string;
+    market: string;
+    price: string;
+    side: 'BUY' | 'SELL';
+    size: string;
+    timestamp: string;
+};
+/**
+ * Represents a tick size change event from Polymarket WebSocket
+ * @example
+ * {
+ *   event_type: "tick_size_change",
+ *   asset_id: "65818619657568813474341868652308942079804919287380422192892211131408793125422",
+ *   market: "0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af",
+ *   old_tick_size: "0.01",
+ *   new_tick_size: "0.001",
+ *   timestamp: "100000000"
+ * }
+ */
+export type TickSizeChangeEvent = {
+    asset_id: string;
+    event_type: 'tick_size_change';
+    market: string;
+    old_tick_size: string;
+    new_tick_size: string;
+    timestamp: string;
+};
+/**
+ * Union type representing all possible event types from Polymarket WebSocket
+ * @example BookEvent
+ * {
+ *   market: "0xf83fb46dd70a4459fcc441a8511701c463374c5c3c250f585d74fda85ddfb7c9",
+ *   asset_id: "101007741586870489619361069512452187353898396425142157315847015703471254508752",
+ *   timestamp: "1740759191594",
+ *   hash: "c0e51b1cfdbcb1b2aec58feaf7b01004019a89c6",
+ *   bids: [{ price: "0.01", size: "510000" }],
+ *   asks: [{ price: "0.99", size: "58.07" }],
+ *   event_type: "book"
+ * }
+ *
+ * @example LastTradePriceEvent
+ * {
+ *   asset_id: "101007741586870489619361069512452187353898396425142157315847015703471254508752",
+ *   event_type: "last_trade_price",
+ *   fee_rate_bps: "0",
+ *   market: "0xf83fb46dd70a4459fcc441a8511701c463374c5c3c250f585d74fda85ddfb7c9",
+ *   price: "0.12",
+ *   side: "BUY",
+ *   size: "8.333332",
+ *   timestamp: "1740760245471"
+ * }
+ *
+ * @example PriceChangeEvent
+ * {
+ *   asset_id: "39327269875426915204597944387916069897800289788920336317845465327697809453999",
+ *   changes: [
+ *     { price: "0.044", side: "SELL", size: "611" }
+ *   ],
+ *   event_type: "price_change",
+ *   hash: "a0b7cadf869fc288dbbf65704996fe818cc97d6a",
+ *   market: "0x5412ae25e97078f814157de948459d59c6221b4c4c495fdd57b536543ad36729",
+ *   timestamp: "1749371014925"
+ * }
+ *
+ * @example TickSizeChangeEvent
+ * {
+ *   event_type: "tick_size_change",
+ *   asset_id: "65818619657568813474341868652308942079804919287380422192892211131408793125422",
+ *   market: "0xbd31dc8a20211944f6b70f31557f1001557b59905b7738480ca09bd4532f84af",
+ *   old_tick_size: "0.01",
+ *   new_tick_size: "0.001",
+ *   timestamp: "100000000"
+ * }
+ */
+export type PolymarketWSEvent = BookEvent | LastTradePriceEvent | PriceChangeEvent | TickSizeChangeEvent;
+/**
+ * Represents a price update event
+ *
+ * This is an event that is emitted to faciliate price update events. It is
+ * not emitted by the Polymarket WebSocket directly.
+ *
+ * See https://docs.polymarket.com/polymarket-learn/trading/how-are-prices-calculated
+ *
+ * TLDR: The prices displayed on Polymarket are the midpoint of the bid-ask spread in the orderbook,
+ * UNLESS that spread is over $0.10, in which case the **last traded price** is used.
+ */
+export interface PolymarketPriceUpdateEvent {
+    event_type: 'price_update';
+    asset_id: string;
+    timestamp: string;
+    triggeringEvent: LastTradePriceEvent | PriceChangeEvent;
+    book: Book;
+    price: string;
+    midpoint: string;
+    spread: string;
+}
+/**
+ * Represents the handlers for the Polymarket WebSocket
+ */
+export type WebSocketHandlers = {
+    onBook?: (events: BookEvent[]) => Promise<void>;
+    onLastTradePrice?: (events: LastTradePriceEvent[]) => Promise<void>;
+    onTickSizeChange?: (events: TickSizeChangeEvent[]) => Promise<void>;
+    onPriceChange?: (events: PriceChangeEvent[]) => Promise<void>;
+    onPolymarketPriceUpdate?: (events: PolymarketPriceUpdateEvent[]) => Promise<void>;
+    onError?: (error: Error) => Promise<void>;
+    onWSClose?: (groupId: string, code: number, reason: string) => Promise<void>;
+    onWSOpen?: (groupId: string, assetIds: string[]) => Promise<void>;
+};
+/**
+ * Type guard to check if an event is a BookEvent
+ * @example
+ * if (isBookEvent(event)) {
+ *   // event is now typed as BookEvent
+ *   console.log(event.bids);
+ * }
+ */
+export declare function isBookEvent(event: PolymarketWSEvent): event is BookEvent;
+/**
+ * Type guard to check if an event is a LastTradePriceEvent
+ * @example
+ * if (isLastTradePriceEvent(event)) {
+ *   // event is now typed as LastTradePriceEvent
+ *   console.log(event.side);
+ * }
+ */
+export declare function isLastTradePriceEvent(event: PolymarketWSEvent): event is LastTradePriceEvent;
+/**
+ * Type guard to check if an event is a PriceChangeEvent
+ * @example
+ * if (isPriceChangeEvent(event)) {
+ *   // event is now typed as PriceChangeEvent
+ *   console.log(event.changes);
+ * }
+ */
+export declare function isPriceChangeEvent(event: PolymarketWSEvent): event is PriceChangeEvent;
+/**
+ * Type guard to check if an event is a TickSizeChangeEvent
+ * @example
+ * if (isTickSizeChangeEvent(event)) {
+ *   // event is now typed as TickSizeChangeEvent
+ *   console.log(event.old_tick_size);
+ * }
+ */
+export declare function isTickSizeChangeEvent(event: PolymarketWSEvent): event is TickSizeChangeEvent;

package/dist/types/PolymarketWebSocket.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isBookEvent = isBookEvent;
+exports.isLastTradePriceEvent = isLastTradePriceEvent;
+exports.isPriceChangeEvent = isPriceChangeEvent;
+exports.isTickSizeChangeEvent = isTickSizeChangeEvent;
+/**
+ * Type guard to check if an event is a BookEvent
+ * @example
+ * if (isBookEvent(event)) {
+ *   // event is now typed as BookEvent
+ *   console.log(event.bids);
+ * }
+ */
+function isBookEvent(event) {
+    return (event === null || event === void 0 ? void 0 : event.event_type) === 'book';
+}
+/**
+ * Type guard to check if an event is a LastTradePriceEvent
+ * @example
+ * if (isLastTradePriceEvent(event)) {
+ *   // event is now typed as LastTradePriceEvent
+ *   console.log(event.side);
+ * }
+ */
+function isLastTradePriceEvent(event) {
+    return (event === null || event === void 0 ? void 0 : event.event_type) === 'last_trade_price';
+}
+/**
+ * Type guard to check if an event is a PriceChangeEvent
+ * @example
+ * if (isPriceChangeEvent(event)) {
+ *   // event is now typed as PriceChangeEvent
+ *   console.log(event.changes);
+ * }
+ */
+function isPriceChangeEvent(event) {
+    return (event === null || event === void 0 ? void 0 : event.event_type) === 'price_change';
+}
+/**
+ * Type guard to check if an event is a TickSizeChangeEvent
+ * @example
+ * if (isTickSizeChangeEvent(event)) {
+ *   // event is now typed as TickSizeChangeEvent
+ *   console.log(event.old_tick_size);
+ * }
+ */
+function isTickSizeChangeEvent(event) {
+    return (event === null || event === void 0 ? void 0 : event.event_type) === 'tick_size_change';
+}

package/dist/types/WebSocketSubscriptions.d.ts

@@ -0,0 +1,19 @@
+import Bottleneck from 'bottleneck';
+import WebSocket from 'ws';
+export declare enum WebSocketStatus {
+    PENDING = "pending",// New group that is pending connection
+    ALIVE = "alive",// Group is connected and receiving events
+    DEAD = "dead",// Group is disconnected
+    CLEANUP = "cleanup"
+}
+export type WebSocketGroup = {
+    groupId: string;
+    assetIds: Set<string>;
+    wsClient: WebSocket | null;
+    status: WebSocketStatus;
+};
+export type SubscriptionManagerOptions = {
+    burstLimiter?: Bottleneck;
+    reconnectAndCleanupIntervalMs?: number;
+    maxMarketsPerWS?: number;
+};

package/dist/types/WebSocketSubscriptions.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketStatus = void 0;
+var WebSocketStatus;
+(function (WebSocketStatus) {
+    WebSocketStatus["PENDING"] = "pending";
+    WebSocketStatus["ALIVE"] = "alive";
+    WebSocketStatus["DEAD"] = "dead";
+    WebSocketStatus["CLEANUP"] = "cleanup"; // Group is marked for cleanup
+})(WebSocketStatus || (exports.WebSocketStatus = WebSocketStatus = {}));

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nevuamarkets/poly-websockets",
+  "version": "0.0.1",
+  "description": "Plug-and-play Polymarket WebSocket price alerts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nevuamarkets/poly-websockets.git"
+  },
+  "keywords": [
+    "polymarket",
+    "websocket",
+    "price",
+    "market",
+    "alerts"
+  ],
+  "author": "Konstantinos Lekkas",
+  "license": "AGPL-3.0",
+  "bugs": {
+    "url": "https://github.com/nevuamarkets/poly-websockets/issues"
+  },
+  "homepage": "https://github.com/nevuamarkets/poly-websockets#readme",
+  "dependencies": {
+    "async-mutex": "^0.5.0",
+    "bottleneck": "^2.19.5",
+    "lodash": "^4.17.21",
+    "uuid": "^11.1.0",
+    "winston": "^3.17.0",
+    "ws": "^8.18.2"
+  },
+  "devDependencies": {
+    "@types/lodash": "^4.17.17",
+    "@types/ms": "^2.1.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.4.2",
+    "vitest": "^3.0.7",
+    "@types/node": "^22.13.11"
+  }
+}