@nevuamarkets/poly-websockets 0.0.1

package/README.md

@@ -0,0 +1,251 @@
+# Poly-WebSockets
+
+A TypeScript library for real-time Polymarket WebSocket price alerts with automatic connection management and intelligent reconnection handling.
+
+## Installation
+
+```bash
+npm install poly-websockets
+```
+
+## Features
+
+- 🔄 **Automatic Connection Management**: Handles WebSocket connections, reconnections, and cleanup for grouped subscriptions
+- 📊 **Real-time Price Updates**: Get live price data, order book updates, and trade events from Polymarket
+- 🎯 **Smart Price Logic**: Implements Polymarket's price calculation logic (midpoint vs last trade price based on spread)
+- 🚦 **Rate Limiting**: Built-in rate limiting to respect Polymarket API limits
+- 🔗 **Group Management**: Efficiently manages multiple asset subscriptions across connection groups
+- 💪 **TypeScript Support**: Full TypeScript definitions for all events and handlers
+
+## Quick Start
+
+```typescript
+import { WSSubscriptionManager, WebSocketHandlers } from '@nevuamarkets/poly-websockets';
+
+// Define your event handlers
+const handlers: WebSocketHandlers = {
+  onPolymarketPriceUpdate: async (events) => {
+    events.forEach(event => {
+      console.log(`Price update for ${event.asset_id}: $${event.price}`);
+    });
+  },
+  onError: async (error) => {
+    console.error('WebSocket error:', error);
+  }
+};
+
+// Create the subscription manager
+const manager = new WSSubscriptionManager(handlers);
+
+// Subscribe to assets
+await manager.addSubscriptions(['asset-id-1', 'asset-id-2']);
+
+// Remove subscriptions
+await manager.removeSubscriptions(['asset-id-1']);
+
+// Clear all subscriptions and connections
+await manager.clearState();
+```
+
+## API Reference
+
+### WSSubscriptionManager
+
+The main class that manages WebSocket connections and subscriptions.
+
+#### Constructor
+
+```typescript
+new WSSubscriptionManager(handlers: WebSocketHandlers, options?: SubscriptionManagerOptions)
+```
+
+**Parameters:**
+- `handlers` - Event handlers for different WebSocket events
+- `options` - Optional configuration object:
+  - `maxMarketsPerWS?: number` - Maximum assets per WebSocket connection (default: 100)
+  - `reconnectAndCleanupIntervalMs?: number` - Interval for reconnection attempts (default: 10s)
+  - `burstLimiter?: Bottleneck` - Custom rate limiter instance
+
+**Connection Management:**
+The WSSubscriptionManager automatically:
+- Groups asset subscriptions into efficient WebSocket connections
+- Handles reconnections when connections drop
+- Manages connection lifecycle and cleanup
+- Balances load across multiple WebSocket groups
+
+#### Methods
+
+##### `addSubscriptions(assetIds: string[]): Promise<void>`
+
+Adds new asset subscriptions. The manager will:
+- Filter out already subscribed assets
+- Find available connection groups or create new ones
+- Establish WebSocket connections as needed
+
+##### `removeSubscriptions(assetIds: string[]): Promise<void>`
+
+Removes asset subscriptions. Connections are kept alive to avoid missing events, and unused groups are cleaned up during the next reconnection cycle.
+
+##### `clearState(): Promise<void>`
+
+Clears all subscriptions and state:
+- Removes all asset subscriptions
+- Closes all WebSocket connections
+- Clears the internal order book cache
+
+### WebSocketHandlers
+
+Interface defining event handlers for different WebSocket events.
+
+```typescript
+interface WebSocketHandlers {
+  // Core Polymarket WebSocket events
+  onBook?: (events: BookEvent[]) => Promise<void>;
+  onLastTradePrice?: (events: LastTradePriceEvent[]) => Promise<void>;
+  onPriceChange?: (events: PriceChangeEvent[]) => Promise<void>;
+  onTickSizeChange?: (events: TickSizeChangeEvent[]) => Promise<void>;
+  
+  // Aggregated price update event (recommended for most use cases)
+  onPolymarketPriceUpdate?: (events: PolymarketPriceUpdateEvent[]) => Promise<void>;
+  
+  // Connection lifecycle events
+  onWSOpen?: (groupId: string, assetIds: string[]) => Promise<void>;
+  onWSClose?: (groupId: string, code: number, reason: string) => Promise<void>;
+  onError?: (error: Error) => Promise<void>;
+}
+```
+
+#### Key Event Types
+
+**PolymarketPriceUpdateEvent** (Recommended)
+- Aggregated price update following Polymarket's display logic
+- Uses midpoint when spread < $0.10, otherwise uses last trade price
+- Includes full order book context
+
+**BookEvent**
+- Complete order book snapshots with bids and asks
+- Triggered on significant order book changes
+
+**PriceChangeEvent**
+- Individual price level changes in the order book
+- More granular than book events
+
+**LastTradePriceEvent**
+- Real-time trade executions
+- Includes trade side, size, and price
+
+## Advanced Usage
+
+### Custom Rate Limiting
+
+```typescript
+import Bottleneck from 'bottleneck';
+
+const customLimiter = new Bottleneck({
+  reservoir: 3,
+  reservoirRefreshAmount: 3,
+  reservoirRefreshInterval: 1000,
+  maxConcurrent: 3
+});
+
+const manager = new WSSubscriptionManager(handlers, {
+  burstLimiter: customLimiter
+});
+```
+
+### Connection Group Configuration
+
+```typescript
+const manager = new WSSubscriptionManager(handlers, {
+  maxMarketsPerWS: 50,  // Smaller groups for more granular control
+  reconnectAndCleanupIntervalMs: 5000  // More frequent reconnection checks
+});
+```
+
+### Handling All Event Types
+
+```typescript
+const comprehensiveHandlers: WebSocketHandlers = {
+  onPolymarketPriceUpdate: async (events) => {
+    // Primary price updates for UI display
+    events.forEach(event => {
+      updatePriceDisplay(event.asset_id, event.price);
+    });
+  },
+  
+  onBook: async (events) => {
+    // Order book depth for trading interfaces
+    events.forEach(event => {
+      updateOrderBook(event.asset_id, event.bids, event.asks);
+    });
+  },
+  
+  onLastTradePrice: async (events) => {
+    // Real-time trade feed
+    events.forEach(event => {
+      logTrade(event.asset_id, event.price, event.size, event.side);
+    });
+  },
+  
+  onWSOpen: async (groupId, assetIds) => {
+    console.log(`Connected group ${groupId} with ${assetIds.length} assets`);
+  },
+  
+  onWSClose: async (groupId, code, reason) => {
+    console.log(`Disconnected group ${groupId}: ${reason} (${code})`);
+  },
+  
+  onError: async (error) => {
+    console.error('WebSocket error:', error);
+    // Implement your error handling/alerting logic
+  }
+};
+```
+
+## Examples
+
+Check the [examples](./examples) folder for complete working examples including:
+- Basic price monitoring
+- Market data aggregation  
+- Real-time trading interfaces
+
+## Error Handling
+
+The library includes comprehensive error handling:
+- Automatic reconnection on connection drops
+- Rate limiting to prevent API blocking
+- Graceful handling of malformed messages
+- User-defined error callbacks for custom handling
+
+## Rate Limits
+
+Respects Polymarket's API rate limits:
+- Default: 5 requests per second burst limit
+- Configurable through custom Bottleneck instances
+- Automatic backoff on rate limit hits
+
+## License
+
+AGPL-3
+
+## Testing
+
+```bash
+npm test
+```
+
+## TypeScript Support
+
+Full TypeScript definitions included.
+
+## Disclaimer
+
+This software is provided "as is", without warranty of any kind, express or implied. The author(s) are not responsible for:
+
+- Any financial losses incurred from using this software
+- Trading decisions made based on the data provided
+- Bugs, errors, or inaccuracies in the data
+- System failures or downtime
+- Any other damages arising from the use of this software
+
+Use at your own risk. Always verify data independently and never rely solely on automated systems for trading decisions.

package/dist/WSSubscriptionManager.d.ts

@@ -0,0 +1,18 @@
+import { WebSocketHandlers } from './types/PolymarketWebSocket';
+import { SubscriptionManagerOptions } from './types/WebSocketSubscriptions';
+declare class WSSubscriptionManager {
+    private handlers;
+    private burstLimiter;
+    private groupRegistry;
+    private bookCache;
+    private reconnectAndCleanupIntervalMs;
+    private maxMarketsPerWS;
+    constructor(userHandlers: WebSocketHandlers, options?: SubscriptionManagerOptions);
+    clearState(): Promise<void>;
+    private actOnSubscribedEvents;
+    addSubscriptions(assetIdsToAdd: string[]): Promise<void>;
+    removeSubscriptions(assetIdsToRemove: string[]): Promise<void>;
+    private reconnectAndCleanupGroups;
+    private createWebSocketClient;
+}
+export { WSSubscriptionManager, WebSocketHandlers };

package/dist/WSSubscriptionManager.js

@@ -0,0 +1,174 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WSSubscriptionManager = void 0;
+const ms_1 = __importDefault(require("ms"));
+const lodash_1 = __importDefault(require("lodash"));
+const bottleneck_1 = __importDefault(require("bottleneck"));
+const GroupRegistry_1 = require("./modules/GroupRegistry");
+const OrderBookCache_1 = require("./modules/OrderBookCache");
+const GroupSocket_1 = require("./modules/GroupSocket");
+const logger_1 = require("./logger");
+// Keeping a burst limit under 10/s to avoid rate limiting
+// See https://docs.polymarket.com/quickstart/introduction/rate-limits#api-rate-limits
+const BURST_LIMIT_PER_SECOND = 5;
+const DEFAULT_RECONNECT_AND_CLEANUP_INTERVAL_MS = (0, ms_1.default)('10s');
+const DEFAULT_MAX_MARKETS_PER_WS = 100;
+class WSSubscriptionManager {
+    constructor(userHandlers, options) {
+        this.groupRegistry = new GroupRegistry_1.GroupRegistry();
+        this.bookCache = new OrderBookCache_1.OrderBookCache();
+        this.burstLimiter = (options === null || options === void 0 ? void 0 : options.burstLimiter) || new bottleneck_1.default({
+            reservoir: BURST_LIMIT_PER_SECOND,
+            reservoirRefreshAmount: BURST_LIMIT_PER_SECOND,
+            reservoirRefreshInterval: (0, ms_1.default)('1s'),
+            maxConcurrent: BURST_LIMIT_PER_SECOND
+        });
+        this.reconnectAndCleanupIntervalMs = (options === null || options === void 0 ? void 0 : options.reconnectAndCleanupIntervalMs) || DEFAULT_RECONNECT_AND_CLEANUP_INTERVAL_MS;
+        this.maxMarketsPerWS = (options === null || options === void 0 ? void 0 : options.maxMarketsPerWS) || DEFAULT_MAX_MARKETS_PER_WS;
+        this.handlers = {
+            onBook: async (events) => {
+                await this.actOnSubscribedEvents(events, userHandlers.onBook);
+            },
+            onLastTradePrice: async (events) => {
+                await this.actOnSubscribedEvents(events, userHandlers.onLastTradePrice);
+            },
+            onTickSizeChange: async (events) => {
+                await this.actOnSubscribedEvents(events, userHandlers.onTickSizeChange);
+            },
+            onPriceChange: async (events) => {
+                await this.actOnSubscribedEvents(events, userHandlers.onPriceChange);
+            },
+            onPolymarketPriceUpdate: async (events) => {
+                await this.actOnSubscribedEvents(events, userHandlers.onPolymarketPriceUpdate);
+            },
+            onWSClose: userHandlers.onWSClose,
+            onWSOpen: userHandlers.onWSOpen,
+            onError: userHandlers.onError
+        };
+        this.burstLimiter.on('error', (err) => {
+            var _a, _b;
+            (_b = (_a = this.handlers).onError) === null || _b === void 0 ? void 0 : _b.call(_a, err);
+        });
+        // Check for dead groups every 10s and reconnect them if needed
+        setInterval(() => {
+            this.reconnectAndCleanupGroups();
+        }, this.reconnectAndCleanupIntervalMs);
+    }
+    /*
+        Clears all WebSocket subscriptions and state.
+
+        This will:
+
+        1. Remove all subscriptions and groups
+        2. Close all WebSocket connections
+        3. Clear the order book cache
+    */
+    async clearState() {
+        const previousGroups = await this.groupRegistry.clearAllGroups();
+        // Close sockets outside the lock
+        for (const group of previousGroups) {
+            this.groupRegistry.disconnectGroup(group);
+        }
+        // Also clear the order book cache
+        this.bookCache.clear();
+    }
+    /*
+        This function is called when:
+        - a websocket event is received from the Polymarket WS
+        - a price update event detected, either by after a 'last_trade_price' event or a 'price_change' event
+        depending on the current bid-ask spread (see https://docs.polymarket.com/polymarket-learn/trading/how-are-prices-calculated)
+
+        The user handlers will be called **ONLY** for assets that are actively subscribed to by any groups.
+    */
+    async actOnSubscribedEvents(events, action) {
+        // Filter out events that are not subscribed to by any groups
+        events = lodash_1.default.filter(events, (event) => {
+            const groupIndices = this.groupRegistry.getGroupIndicesForAsset(event.asset_id);
+            if (groupIndices.length > 1) {
+                logger_1.logger.warn({
+                    message: 'Found multiple groups for asset',
+                    asset_id: event.asset_id,
+                    group_indices: groupIndices
+                });
+            }
+            return groupIndices.length > 0;
+        });
+        await (action === null || action === void 0 ? void 0 : action(events));
+    }
+    /*
+        Edits wsGroups: Adds new subscriptions.
+
+        - Filters out assets that are already subscribed
+        - Finds a group with capacity or creates a new one
+        - Creates a new WebSocket client and adds it to the group
+    */
+    async addSubscriptions(assetIdsToAdd) {
+        var _a, _b;
+        try {
+            const groupIdsToConnect = await this.groupRegistry.addAssets(assetIdsToAdd, this.maxMarketsPerWS);
+            for (const groupId of groupIdsToConnect) {
+                await this.createWebSocketClient(groupId, this.handlers);
+            }
+        }
+        catch (error) {
+            const msg = `Error adding subscriptions: ${error instanceof Error ? error.message : String(error)}`;
+            await ((_b = (_a = this.handlers).onError) === null || _b === void 0 ? void 0 : _b.call(_a, new Error(msg)));
+        }
+    }
+    /*
+        Edits wsGroups: Removes subscriptions.
+        The group will use the updated subscriptions when it reconnects.
+        We do that because we don't want to miss events by reconnecting.
+    */
+    async removeSubscriptions(assetIdsToRemove) {
+        var _a, _b;
+        try {
+            await this.groupRegistry.removeAssets(assetIdsToRemove, this.bookCache);
+        }
+        catch (error) {
+            const errMsg = `Error removing subscriptions: ${error instanceof Error ? error.message : String(error)}`;
+            await ((_b = (_a = this.handlers).onError) === null || _b === void 0 ? void 0 : _b.call(_a, new Error(errMsg)));
+        }
+    }
+    /*
+        This function runs periodically and:
+
+        - Tries to reconnect groups that have assets and are disconnected
+        - Cleans up groups that have no assets
+    */
+    async reconnectAndCleanupGroups() {
+        var _a, _b;
+        try {
+            const reconnectIds = await this.groupRegistry.getGroupsToReconnectAndCleanup();
+            for (const groupId of reconnectIds) {
+                await this.createWebSocketClient(groupId, this.handlers);
+            }
+        }
+        catch (err) {
+            await ((_b = (_a = this.handlers).onError) === null || _b === void 0 ? void 0 : _b.call(_a, err));
+        }
+    }
+    async createWebSocketClient(groupId, handlers) {
+        var _a, _b;
+        const group = this.groupRegistry.findGroupById(groupId);
+        /*
+            Should never happen, but just in case.
+        */
+        if (!group) {
+            await ((_a = handlers.onError) === null || _a === void 0 ? void 0 : _a.call(handlers, new Error(`Group ${groupId} not found in registry`)));
+            return;
+        }
+        const groupSocket = new GroupSocket_1.GroupSocket(group, this.burstLimiter, this.bookCache, handlers);
+        try {
+            await groupSocket.connect();
+        }
+        catch (error) {
+            const errorMessage = `Error creating WebSocket client for group ${groupId}: ${error instanceof Error ? error.message : String(error)}`;
+            await ((_b = handlers.onError) === null || _b === void 0 ? void 0 : _b.call(handlers, new Error(errorMessage)));
+        }
+    }
+}
+exports.WSSubscriptionManager = WSSubscriptionManager;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { WSSubscriptionManager, WebSocketHandlers } from './WSSubscriptionManager';
+export * from './types/PolymarketWebSocket';
+export * from './types/WebSocketSubscriptions';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WSSubscriptionManager = void 0;
+var WSSubscriptionManager_1 = require("./WSSubscriptionManager");
+Object.defineProperty(exports, "WSSubscriptionManager", { enumerable: true, get: function () { return WSSubscriptionManager_1.WSSubscriptionManager; } });
+__exportStar(require("./types/PolymarketWebSocket"), exports);
+__exportStar(require("./types/WebSocketSubscriptions"), exports);

package/dist/logger.d.ts

@@ -0,0 +1,2 @@
+import winston from 'winston';
+export declare const logger: winston.Logger;

package/dist/logger.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const winston_1 = __importDefault(require("winston"));
+// Override with LOG_LEVEL environment variable (e.g., LOG_LEVEL=info npm start)
+exports.logger = winston_1.default.createLogger({
+    level: process.env.LOG_LEVEL || 'error',
+    format: winston_1.default.format.combine(winston_1.default.format.timestamp(), winston_1.default.format.errors({ stack: true }), winston_1.default.format.colorize(), winston_1.default.format.printf(({ level, message, timestamp, ...rest }) => {
+        // Ensure consistent order: timestamp, level, message, then rest of fields
+        const restString = Object.keys(rest)
+            .filter(key => key !== 'service') // Exclude service since we add it in defaultMeta
+            .sort()
+            .map(key => `${key}: ${JSON.stringify(rest[key])}`)
+            .join(', ');
+        return `${timestamp} ${level}: ${message}${restString ? ` (${restString})` : ''}`;
+    })),
+    defaultMeta: { service: 'poly-websockets' },
+    transports: [
+        new winston_1.default.transports.Console({
+            format: winston_1.default.format.combine(winston_1.default.format.colorize({
+                all: true,
+                colors: {
+                    error: 'red',
+                    warn: 'yellow',
+                    info: 'cyan',
+                    debug: 'green'
+                }
+            }))
+        })
+    ]
+});

package/dist/modules/GroupRegistry.d.ts

@@ -0,0 +1,85 @@
+import { WebSocketGroup } from '../types/WebSocketSubscriptions';
+import { OrderBookCache } from './OrderBookCache';
+export declare class GroupRegistry {
+    /**
+     * Atomic mutate helper.
+     *
+     * @param fn - The function to run atomically.
+     * @returns The result of the function.
+     */
+    mutate<T>(fn: (groups: WebSocketGroup[]) => T | Promise<T>): Promise<T>;
+    /**
+     * Read-only copy of the registry.
+     *
+     * Only to be used in test suite.
+     */
+    snapshot(): WebSocketGroup[];
+    /**
+     * Find the first group with capacity to hold new assets.
+     *
+     * Returns the groupId if found, otherwise null.
+     */
+    findGroupWithCapacity(newAssetLen: number, maxPerWS: number): string | null;
+    /**
+     * Get the indices of all groups that contain the asset.
+     *
+     * Returns an array of indices.
+     */
+    getGroupIndicesForAsset(assetId: string): number[];
+    /**
+     * Check if any group contains the asset.
+     */
+    hasAsset(assetId: string): boolean;
+    /**
+     * Find the group by groupId.
+     *
+     * Returns the group if found, otherwise undefined.
+     */
+    findGroupById(groupId: string): WebSocketGroup | undefined;
+    /**
+     * Atomically remove **all** groups from the registry and return them so the
+     * caller can perform any asynchronous cleanup (closing sockets, etc.)
+     * outside the lock.
+     *
+     * Returns the removed groups.
+     */
+    clearAllGroups(): Promise<WebSocketGroup[]>;
+    /**
+     * Add new asset subscriptions.
+     *
+     * – Ignores assets that are already subscribed.
+     * – Either reuses an existing group with capacity or creates new groups (size ≤ maxPerWS).
+     * – If appending to a group:
+     *  - A new group is created with the updated assetIds.
+     *  - The old group is marked for cleanup.
+     *  - The group is added to the list of groups to connect.
+     *
+     * @param assetIds - The assetIds to add.
+     * @param maxPerWS - The maximum number of assets per WebSocket group.
+     * @returns An array of *new* groupIds that need websocket connections.
+     */
+    addAssets(assetIds: string[], maxPerWS: number): Promise<string[]>;
+    /**
+     * Remove asset subscriptions from every group that contains the asset.
+     *
+     * It should be only one group that contains the asset, we search all of them
+     * regardless.
+     *
+     * Returns the list of assetIds that were removed.
+     */
+    removeAssets(assetIds: string[], bookCache: OrderBookCache): Promise<string[]>;
+    /**
+     * Disconnect a group.
+     */
+    disconnectGroup(group: WebSocketGroup): void;
+    /**
+     * Check status of groups and reconnect or cleanup as needed.
+     *
+     * – Empty groups are removed from the global array and returned.
+     * – Dead (but non-empty) groups are reset so that caller can reconnect them.
+     * – Pending groups are returned so that caller can connect them.
+     *
+     * Returns an array of group IDs that need to be reconnected, after cleaning up empty and cleanup-marked groups.
+     */
+    getGroupsToReconnectAndCleanup(): Promise<string[]>;
+}