@nevuamarkets/poly-websockets 1.0.0-beta.0 → 1.0.0-beta.1

package/README.md

@@ -1,6 +1,6 @@
 # Poly-WebSockets
 
-A TypeScript library for **real-time Polymarket market price alerts** over **Websocket** with **automatic reconnections** and **easy subscription management**.
+A TypeScript library for **real-time Polymarket market data** over **WebSocket** with **automatic reconnections** and **easy subscription management**.
 
 Powering [Nevua Markets](https://nevua.markets)
 
@@ -12,43 +12,44 @@ npm install @nevuamarkets/poly-websockets
 
 ## Features
 
-- 📊 **Real-time Market Updates**: Get `book` , `price_change`, `tick_size_change` and `last_trade_price` real-time market events from Polymarket WSS
-- 🎯 **Derived Future Price Event**: Implements Polymarket's [price calculation logic](https://docs.polymarket.com/polymarket-learn/trading/how-are-prices-calculated#future-price) (midpoint vs last trade price based on spread)
-- 🔗 **Dynamic Subscriptions**: Subscribe and unsubscribe to assets on existing WebSocket connections without reconnecting
-- 🔄 **Automatic Connection Management**: Handles WebSocket connections, reconnections, and cleanup
-- 🚦 **Rate Limiting**: Built-in rate limiting to respect Polymarket API limits
+- 📊 **Real-time Market Updates**: Get `book`, `price_change`, `tick_size_change` and `last_trade_price` events from Polymarket WebSocket
+- 🎯 **Derived Price Event**: Implements Polymarket's [price calculation logic](https://docs.polymarket.com/polymarket-learn/trading/how-are-prices-calculated#future-price) (midpoint vs last trade price based on spread)
+- 🔗 **Dynamic Subscriptions**: Subscribe and unsubscribe to assets without reconnecting
+- 🔄 **Automatic Reconnection**: Handles connection drops with automatic reconnection
 - 💪 **TypeScript Support**: Full TypeScript definitions for all events and handlers
-- ♾️ **Unlimited Assets**: By default, all subscriptions go through a single WebSocket connection (Polymarket now supports unlimited assets per connection)
+- 🔒 **Independent Instances**: Each manager instance is fully isolated with its own WebSocket connection
 
 ## Quick Start
 
 ```typescript
-import {
-  WSSubscriptionManager,
-  WebSocketHandlers
-  } from '@nevuamarkets/poly-websockets';
+import { WSSubscriptionManager } from '@nevuamarkets/poly-websockets';
 
-// Create the subscription manager with your own handlers
 const manager = new WSSubscriptionManager({
-  onBook: async (events: BookEvent[]) => {
-    for (const event of events) {
-      console.log('book event', JSON.stringify(event, null, 2))
-    }
+  onBook: async (events) => {
+    console.log('Book events:', events);
   },
-  onPriceChange: async (events: PriceChangeEvent[]) => {
-    for (const event of events) {
-      console.log('price change event', JSON.stringify(event, null, 2))
-    }
+  onPriceChange: async (events) => {
+    console.log('Price change events:', events);
+  },
+  onPolymarketPriceUpdate: async (events) => {
+    // Derived price following Polymarket's display logic
+    console.log('Price updates:', events);
+  },
+  onError: async (error) => {
+    console.error('Error:', error.message);
   }
 });
 
 // Subscribe to assets
 await manager.addSubscriptions(['asset-id-1', 'asset-id-2']);
 
+// Get monitored assets
+console.log('Monitored:', manager.getAssetIds());
+
 // Remove subscriptions
 await manager.removeSubscriptions(['asset-id-1']);
 
-// Clear all subscriptions and connections
+// Clear all subscriptions and close connection
 await manager.clearState();
 ```
 
@@ -56,8 +57,6 @@ await manager.clearState();
 
 ### WSSubscriptionManager
 
-The main class that manages WebSocket connections and subscriptions.
-
 #### Constructor
 
 ```typescript
@@ -65,118 +64,81 @@ new WSSubscriptionManager(handlers: WebSocketHandlers, options?: SubscriptionMan
 ```
 
 **Parameters:**
-- `handlers` - Event handlers for different WebSocket events
-- `options` - Optional configuration object:
-  - `maxMarketsPerWS?: number` - Maximum assets per WebSocket connection (default: `Infinity` - unlimited, single connection for all assets)
-  - `reconnectAndCleanupIntervalMs?: number` - Interval for reconnection attempts (default: 10s)
-  - `burstLimiter?: Bottleneck` - Custom rate limiter instance. If none is provided, one will be created and used internally in the component.
+- `handlers` - Event handlers for WebSocket events
+- `options` - Optional configuration:
+  - `reconnectAndCleanupIntervalMs?: number` - Reconnection check interval (default: 5000ms)
+  - `pendingFlushIntervalMs?: number` - How often to flush pending subscriptions (default: 100ms)
+  - ~~`burstLimiter`~~ - **@deprecated** No longer used
+  - ~~`maxMarketsPerWS`~~ - **@deprecated** No longer used. Create multiple manager instances instead
 
 #### Methods
 
-##### `addSubscriptions(assetIds: string[]): Promise<void>`
-
-Adds new asset subscriptions. The manager will:
-- Filter out already subscribed assets
-- If an active WebSocket connection exists with capacity, send a subscribe message on that connection
-- Otherwise, create a new WebSocket connection
-
-##### `removeSubscriptions(assetIds: string[]): Promise<void>`
-
-Removes asset subscriptions. The manager will:
-- Send an unsubscribe message on the active connection
-- Clear the internal order book cache for removed assets
-- Connections are kept alive to avoid missing events for other subscribed assets
-
-##### `clearState(): Promise<void>`
+| Method | Description |
+|--------|-------------|
+| `addSubscriptions(assetIds: string[])` | Add assets to monitor |
+| `removeSubscriptions(assetIds: string[])` | Stop monitoring assets |
+| `getAssetIds(): string[]` | Get all monitored asset IDs (subscribed + pending) |
+| `getStatistics()` | Get connection and subscription statistics |
+| `clearState()` | Clear all subscriptions and close connection |
 
-Clears all subscriptions and state:
-- Removes all asset subscriptions
-- Closes all WebSocket connections
-- Clears the internal order book cache
+#### Statistics Object
 
-##### `getStatistics(): { openWebSockets: number; subscribedAssetIds: number }`
-
-Returns statistics about the current state of the subscription manager:
-- `openWebSockets`: The number of websockets that are currently in OPEN state
-- `subscribedAssetIds`: The number of unique asset IDs that are currently subscribed
+```typescript
+manager.getStatistics() // Returns:
+{
+  openWebSockets: number;           // 1 if connected, 0 otherwise
+  assetIds: number;                 // Total monitored assets
+  pendingSubscribeCount: number;    // Assets waiting to be subscribed
+  pendingUnsubscribeCount: number;  // Assets waiting to be unsubscribed
+}
+```
 
 ### WebSocketHandlers
 
-Interface defining event handlers for different WebSocket events.
-
 ```typescript
 interface WebSocketHandlers {
-  // Core Polymarket WebSocket events
+  // Polymarket WebSocket events
   onBook?: (events: BookEvent[]) => Promise<void>;
   onLastTradePrice?: (events: LastTradePriceEvent[]) => Promise<void>;
   onPriceChange?: (events: PriceChangeEvent[]) => Promise<void>;
   onTickSizeChange?: (events: TickSizeChangeEvent[]) => Promise<void>;
   
-  // Derived polymarket price update event
+  // Derived price update (implements Polymarket's display logic)
   onPolymarketPriceUpdate?: (events: PolymarketPriceUpdateEvent[]) => Promise<void>;
   
-  // Connection lifecycle events
-  onWSOpen?: (groupId: string, assetIds: string[]) => Promise<void>;
-  onWSClose?: (groupId: string, code: number, reason: string) => Promise<void>;
+  // Connection events
+  onWSOpen?: (managerId: string, pendingAssetIds: string[]) => Promise<void>;
+  onWSClose?: (managerId: string, code: number, reason: string) => Promise<void>;
   onError?: (error: Error) => Promise<void>;
 }
 ```
 
-#### Key Event Types
-
-**BookEvent**
-- See // https://docs.polymarket.com/developers/CLOB/websocket/market-channel#book-message
-
-**PriceChangeEvent**
-- See https://docs.polymarket.com/developers/CLOB/websocket/market-channel#price-change-message
+### Event Types
 
-**onTickSizeChange**
-- See https://docs.polymarket.com/developers/CLOB/websocket/market-channel#tick-size-change-message
+| Event | Description |
+|-------|-------------|
+| `BookEvent` | Full order book snapshot ([docs](https://docs.polymarket.com/developers/CLOB/websocket/market-channel#book-message)) |
+| `PriceChangeEvent` | Order book price level changes ([docs](https://docs.polymarket.com/developers/CLOB/websocket/market-channel#price-change-message)) |
+| `TickSizeChangeEvent` | Tick size changes ([docs](https://docs.polymarket.com/developers/CLOB/websocket/market-channel#tick-size-change-message)) |
+| `LastTradePriceEvent` | Trade executions |
+| `PolymarketPriceUpdateEvent` | Derived price using Polymarket's display logic |
 
-**LastTradePriceEvent**
-- Currently undocumented, but is emitted when a trade occurs
+## Multiple Independent Connections
 
-**PolymarketPriceUpdateEvent**
-- Derived price update following Polymarket's display logic
-- Uses midpoint when spread <= $0.10, otherwise uses last trade price
-- Includes full order book context
-
-### Custom Rate Limiting
+Each `WSSubscriptionManager` instance maintains its own WebSocket connection:
 
 ```typescript
-import Bottleneck from 'bottleneck';
-
-const customLimiter = new Bottleneck({
-  reservoir: 10,
-  reservoirRefreshAmount: 10,
-  reservoirRefreshInterval: 1000,
-  maxConcurrent: 10
-});
+// Two separate connections for different asset groups
+const manager1 = new WSSubscriptionManager(handlers1);
+const manager2 = new WSSubscriptionManager(handlers2);
 
-const manager = new WSSubscriptionManager(handlers, {
-  burstLimiter: customLimiter
-});
+await manager1.addSubscriptions(['asset-1', 'asset-2']);
+await manager2.addSubscriptions(['asset-3', 'asset-4']);
 ```
 
 ## Examples
 
-Check the [examples](./examples) folder for complete working examples
-
-## Error Handling
-
-The library includes error handling:
-- Automatic reconnection on connection drops
-- 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
-
-## License
-
-AGPL-3
+See the [examples](./examples) folder for complete working examples.
 
 ## Testing
 
@@ -184,18 +146,10 @@ AGPL-3
 npm test
 ```
 
-## TypeScript Support
+## License
 
-Full TypeScript definitions included.
+AGPL-3.0
 
 ## 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.
+This software is provided "as is", without warranty of any kind. The author(s) are not responsible for any financial losses, trading decisions, bugs, or system failures. Use at your own risk.

package/dist/WSSubscriptionManager.d.ts

@@ -1,65 +1,145 @@
 import { WebSocketHandlers } from './types/PolymarketWebSocket';
 import { SubscriptionManagerOptions } from './types/WebSocketSubscriptions';
+/**
+ * WebSocket Subscription Manager for Polymarket CLOB WebSocket.
+ *
+ * Each instance manages a single WebSocket connection and tracks:
+ * - Subscribed assets: Successfully subscribed to the WebSocket
+ * - Pending assets: Waiting to be subscribed (batched and flushed periodically)
+ *
+ * Instances are fully independent - no shared state between managers.
+ */
 declare class WSSubscriptionManager {
+    private readonly managerId;
     private handlers;
-    private burstLimiter;
-    private groupRegistry;
     private bookCache;
-    private reconnectAndCleanupIntervalMs;
-    private maxMarketsPerWS;
+    private wsClient;
+    private status;
+    private connecting;
+    private subscribedAssetIds;
+    private pendingSubscribeAssetIds;
+    private pendingUnsubscribeAssetIds;
+    private reconnectIntervalMs;
+    private pendingFlushIntervalMs;
     private reconnectInterval?;
+    private pendingFlushInterval?;
+    private pingInterval?;
+    private connectionTimeout?;
     constructor(userHandlers: WebSocketHandlers, options?: SubscriptionManagerOptions);
     /**
      * Clears all WebSocket subscriptions and state.
      *
      * This will:
-     *
-     * 1. Stop the reconnection interval
-     * 2. Remove all subscriptions and groups (including GroupSockets)
-     * 3. Close all WebSocket connections
+     * 1. Stop all timers
+     * 2. Close the WebSocket connection
+     * 3. Clear all asset tracking
      * 4. Clear the order book cache
      */
     clearState(): Promise<void>;
     /**
-     * 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.
-     *
-     * @param events - The events to process.
-     * @param action - The action to perform on the filtered events.
+     * Filters events to only include those for subscribed assets.
+     * Wraps user handler calls in try-catch to prevent user errors from breaking internal logic.
+     * Does not call the handler if all events are filtered out.
      */
     private actOnSubscribedEvents;
     /**
      * Adds new subscriptions.
      *
-     * - Filters out assets that are already subscribed
-     * - If an ALIVE group exists with capacity, sends subscribe message on that connection
-     * - Otherwise creates a new group and WebSocket connection
+     * Assets are added to a pending queue and will be subscribed when:
+     * - The WebSocket connects (initial subscription)
+     * - The pending flush timer fires (for new assets on an existing connection)
      *
      * @param assetIdsToAdd - The asset IDs to add subscriptions for.
      */
     addSubscriptions(assetIdsToAdd: string[]): Promise<void>;
+    /**
+     * Ensures the periodic intervals are running.
+     * Called after clearState() when new subscriptions are added.
+     */
+    private ensureIntervalsRunning;
+    /**
+     * Schedules the next reconnection check.
+     * Uses a fixed interval (default 5 seconds) between checks.
+     */
+    private scheduleReconnectionCheck;
+    /**
+     * Safely calls the error handler, catching any exceptions thrown by it.
+     * Prevents user handler exceptions from breaking internal logic.
+     */
+    private safeCallErrorHandler;
     /**
      * Removes subscriptions.
-     * Sends unsubscribe messages to ALIVE connections.
      *
      * @param assetIdsToRemove - The asset IDs to remove subscriptions for.
      */
     removeSubscriptions(assetIdsToRemove: string[]): Promise<void>;
     /**
-     * This function runs periodically and:
+     * Get all currently monitored asset IDs.
+     * This includes both successfully subscribed assets and pending subscriptions.
      *
-     * - Tries to reconnect groups that have assets and are disconnected
-     * - Cleans up groups that have no assets
+     * @returns Array of asset IDs being monitored.
+     */
+    getAssetIds(): string[];
+    /**
+     * Returns statistics about the current state of the subscription manager.
      */
-    private reconnectAndCleanupGroups;
     getStatistics(): {
         openWebSockets: number;
-        subscribedAssetIds: number;
+        assetIds: number;
+        pendingSubscribeCount: number;
+        pendingUnsubscribeCount: number;
+        /** @deprecated Use pendingSubscribeCount + pendingUnsubscribeCount instead */
+        pendingAssetIds: number;
     };
-    private createWebSocketClient;
+    /**
+     * Flush pending subscriptions and unsubscriptions to the WebSocket.
+     *
+     * SUBSCRIPTION PROTOCOL NOTE:
+     * The Polymarket WebSocket protocol does NOT send any confirmation or acknowledgment
+     * messages for subscribe/unsubscribe operations. The server silently processes these
+     * requests. We optimistically assume success after sending. If the server rejects
+     * a request (e.g., invalid asset ID), events for those assets simply won't arrive -
+     * there is no error response to handle.
+     *
+     * This means:
+     * - We cannot definitively know if a subscription succeeded
+     * - We cannot definitively know if an unsubscription succeeded
+     * - The only indication of failure is the absence of expected events
+     */
+    private flushPendingSubscriptions;
+    /**
+     * Closes the WebSocket connection and cleans up related resources.
+     */
+    private closeWebSocket;
+    /**
+     * Check if we need to reconnect.
+     * Note: Assets are moved to pending in handleClose/handleError handlers,
+     * so this method only needs to check if reconnection is needed.
+     */
+    private checkReconnection;
+    /**
+     * Establish the WebSocket connection.
+     */
+    private connect;
+    /**
+     * Sets up event handlers for the WebSocket connection.
+     */
+    private setupEventHandlers;
+    /**
+     * Handles book events by updating the cache and notifying listeners.
+     */
+    private handleBookEvents;
+    /**
+     * Handles tick size change events by notifying listeners.
+     */
+    private handleTickEvents;
+    /**
+     * Handles price change events.
+     */
+    private handlePriceChangeEvents;
+    /**
+     * Handles last trade price events.
+     */
+    private handleLastTradeEvents;
 }
 export { WSSubscriptionManager, WebSocketHandlers };