@tentou-tech/poly-websockets 1.0.0

package/README.md

@@ -0,0 +1,212 @@
+# Poly-WebSockets
+
+A TypeScript library for **real-time Polymarket market data** over **WebSocket** with **automatic reconnections** and **easy subscription management**.
+
+Powering [Nevua Markets](https://nevua.markets)
+
+## Installation
+
+```bash
+npm install @tentou-tech/poly-websockets
+```
+
+## Features
+
+- 📊 **Real-time Market Updates**: Get `book`, `price_change`, `tick_size_change`, `last_trade_price`, `best_bid_ask`, `new_market` and `market_resolved` 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
+- 🔒 **Independent Instances**: Each manager instance is fully isolated with its own WebSocket connection
+
+## Quick Start
+
+```typescript
+import { WSSubscriptionManager } from '@nevuamarkets/poly-websockets';
+
+const manager = new WSSubscriptionManager({
+  onBook: async (events) => {
+    console.log('Book events:', events);
+  },
+  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 close connection
+await manager.clearState();
+```
+
+## Market-Level Events
+
+To receive `new_market` and `market_resolved` events, enable custom features:
+
+```typescript
+import { WSSubscriptionManager, NewMarketEvent, MarketResolvedEvent } from '@nevuamarkets/poly-websockets';
+
+const manager = new WSSubscriptionManager({
+  onNewMarket: async (events: NewMarketEvent[]) => {
+    for (const event of events) {
+      console.log('New market created:', event.question);
+      console.log('Market ID:', event.id);
+      console.log('Asset IDs:', event.assets_ids);
+    }
+  },
+  onMarketResolved: async (events: MarketResolvedEvent[]) => {
+    for (const event of events) {
+      console.log('Market resolved:', event.question);
+      console.log('Winning outcome:', event.winning_outcome);
+    }
+  },
+  onBestBidAsk: async (events) => {
+    for (const event of events) {
+      console.log(`Best bid: ${event.best_bid}, Best ask: ${event.best_ask}`);
+    }
+  }
+}, {
+  enableCustomFeatures: true  // Required for new_market and market_resolved
+});
+
+// Market-level events work even without asset subscriptions
+await manager.addSubscriptions([]);
+```
+
+**Note:** Market-level events (`new_market`, `market_resolved`) are broadcast to all handlers regardless of asset subscriptions. Asset-level events (`book`, `price_change`, `best_bid_ask`, etc.) are only received for subscribed assets.
+
+## API Reference
+
+### WSSubscriptionManager
+
+#### Constructor
+
+```typescript
+new WSSubscriptionManager(handlers: WebSocketHandlers, options?: SubscriptionManagerOptions)
+```
+
+**Parameters:**
+- `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)
+  - `enableCustomFeatures?: boolean` - Enable custom features like `new_market` and `market_resolved` events (default: false)
+
+#### Methods
+
+| 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 |
+
+#### Statistics Object
+
+```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
+
+```typescript
+interface WebSocketHandlers {
+  // Polymarket WebSocket events (asset-level)
+  onBook?: (events: BookEvent[]) => Promise<void>;
+  onLastTradePrice?: (events: LastTradePriceEvent[]) => Promise<void>;
+  onPriceChange?: (events: PriceChangeEvent[]) => Promise<void>;
+  onTickSizeChange?: (events: TickSizeChangeEvent[]) => Promise<void>;
+  onBestBidAsk?: (events: BestBidAskEvent[]) => Promise<void>;
+  
+  // Polymarket WebSocket events (market-level, requires enableCustomFeatures: true)
+  onNewMarket?: (events: NewMarketEvent[]) => Promise<void>;
+  onMarketResolved?: (events: MarketResolvedEvent[]) => Promise<void>;
+  
+  // Derived price update (implements Polymarket's display logic)
+  onPolymarketPriceUpdate?: (events: PolymarketPriceUpdateEvent[]) => 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>;
+}
+```
+
+### Event Types
+
+#### Asset-Level Events
+These events are filtered by subscribed asset IDs:
+
+| 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 |
+| `BestBidAskEvent` | Best bid/ask price updates ([docs](https://docs.polymarket.com/developers/CLOB/websocket/market-channel#best_bid_ask-message)) |
+
+#### Market-Level Events
+These events are broadcast to all handlers (not filtered by subscriptions). Requires `enableCustomFeatures: true`:
+
+| Event | Description |
+|-------|-------------|
+| `NewMarketEvent` | New market creation ([docs](https://docs.polymarket.com/developers/CLOB/websocket/market-channel#new_market-message)) |
+| `MarketResolvedEvent` | Market resolution ([docs](https://docs.polymarket.com/developers/CLOB/websocket/market-channel#market_resolved-message)) |
+
+#### Derived Events
+
+| Event | Description |
+|-------|-------------|
+| `PolymarketPriceUpdateEvent` | Derived price using Polymarket's display logic |
+
+## Multiple Independent Connections
+
+Each `WSSubscriptionManager` instance maintains its own WebSocket connection:
+
+```typescript
+// Two separate connections for different asset groups
+const manager1 = new WSSubscriptionManager(handlers1);
+const manager2 = new WSSubscriptionManager(handlers2);
+
+await manager1.addSubscriptions(['asset-1', 'asset-2']);
+await manager2.addSubscriptions(['asset-3', 'asset-4']);
+```
+
+## Examples
+
+See the [examples](./examples) folder for complete working examples.
+
+## Testing
+
+```bash
+npm test
+```
+
+## License
+
+AGPL-3.0
+
+## Disclaimer
+
+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

@@ -0,0 +1,160 @@
+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 bookCache;
+    private wsClient;
+    private status;
+    private connecting;
+    private subscribedAssetIds;
+    private pendingSubscribeAssetIds;
+    private pendingUnsubscribeAssetIds;
+    private enableCustomFeatures;
+    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 all timers
+     * 2. Close the WebSocket connection
+     * 3. Clear all asset tracking
+     * 4. Clear the order book cache
+     */
+    clearState(): Promise<void>;
+    /**
+     * 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.
+     *
+     * 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.
+     *
+     * @param assetIdsToRemove - The asset IDs to remove subscriptions for.
+     */
+    removeSubscriptions(assetIdsToRemove: string[]): Promise<void>;
+    /**
+     * Get all currently monitored asset IDs.
+     * This includes both successfully subscribed assets and pending subscriptions.
+     *
+     * @returns Array of asset IDs being monitored.
+     */
+    getAssetIds(): string[];
+    /**
+     * Returns statistics about the current state of the subscription manager.
+     */
+    getStatistics(): {
+        openWebSockets: number;
+        assetIds: number;
+        pendingSubscribeCount: number;
+        pendingUnsubscribeCount: number;
+        /** @deprecated Use pendingSubscribeCount + pendingUnsubscribeCount instead */
+        pendingAssetIds: number;
+    };
+    /**
+     * 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;
+    /**
+     * Handles best bid/ask events.
+     */
+    private handleBestBidAskEvents;
+    /**
+     * Handles new market events.
+     * These events bypass asset-level filtering as they are market-level events.
+     */
+    private handleNewMarketEvents;
+    /**
+     * Handles market resolved events.
+     * These events bypass asset-level filtering as they are market-level events.
+     */
+    private handleMarketResolvedEvents;
+}
+export { WSSubscriptionManager, WebSocketHandlers };