@nevuamarkets/poly-websockets 0.0.1 → 0.0.3

package/README.md

@@ -2,6 +2,8 @@
 
 A TypeScript library for real-time Polymarket WebSocket price alerts with automatic connection management and intelligent reconnection handling.
 
+Powering [Nevua Markets](https://nevua.markets)
+
 ## Installation
 
 ```bash
@@ -10,11 +12,11 @@ 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)
+- 🔄 **Automatic Connection Management**: Handles WebSocket connections, reconnections, and cleanup for grouped assetId (i.e. clobTokenId) subscriptions
+- 📊 **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)
 - 🚦 **Rate Limiting**: Built-in rate limiting to respect Polymarket API limits
-- 🔗 **Group Management**: Efficiently manages multiple asset subscriptions across connection groups
+- 🔗 **Group Management**: Efficiently manages multiple asset subscriptions across connection groups **without losing events** when subscribing / unsubscribing assets.
 - 💪 **TypeScript Support**: Full TypeScript definitions for all events and handlers
 
 ## Quick Start
@@ -64,14 +66,7 @@ new WSSubscriptionManager(handlers: WebSocketHandlers, options?: SubscriptionMan
 - `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
+  - `burstLimiter?: Bottleneck` - Custom rate limiter instance. If none is provided, one will be created and used internally in the component.
 
 #### Methods
 
@@ -84,7 +79,7 @@ Adds new asset subscriptions. The manager will:
 
 ##### `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.
+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>`
 
@@ -105,7 +100,7 @@ interface WebSocketHandlers {
   onPriceChange?: (events: PriceChangeEvent[]) => Promise<void>;
   onTickSizeChange?: (events: TickSizeChangeEvent[]) => Promise<void>;
   
-  // Aggregated price update event (recommended for most use cases)
+  // Derived polymarket price update event
   onPolymarketPriceUpdate?: (events: PolymarketPriceUpdateEvent[]) => Promise<void>;
   
   // Connection lifecycle events
@@ -117,24 +112,22 @@ interface WebSocketHandlers {
 
 #### 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
+- See // https://docs.polymarket.com/developers/CLOB/websocket/market-channel#book-message
 
 **PriceChangeEvent**
-- Individual price level changes in the order book
-- More granular than book events
+- See https://docs.polymarket.com/developers/CLOB/websocket/market-channel#price-change-message
+
+**onTickSizeChange**
+- See https://docs.polymarket.com/developers/CLOB/websocket/market-channel#tick-size-change-message
 
 **LastTradePriceEvent**
-- Real-time trade executions
-- Includes trade side, size, and price
+- Currently undocumented, but is emitted when a trade occurs
 
-## Advanced Usage
+**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
 
@@ -142,10 +135,10 @@ interface WebSocketHandlers {
 import Bottleneck from 'bottleneck';
 
 const customLimiter = new Bottleneck({
-  reservoir: 3,
-  reservoirRefreshAmount: 3,
+  reservoir: 10,
+  reservoirRefreshAmount: 10,
   reservoirRefreshInterval: 1000,
-  maxConcurrent: 3
+  maxConcurrent: 10
 });
 
 const manager = new WSSubscriptionManager(handlers, {
@@ -153,55 +146,6 @@ const manager = new WSSubscriptionManager(handlers, {
 });
 ```
 
-### 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:
@@ -211,10 +155,8 @@ Check the [examples](./examples) folder for complete working examples including:
 
 ## Error Handling
 
-The library includes comprehensive error handling:
+The library includes 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nevuamarkets/poly-websockets",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Plug-and-play Polymarket WebSocket price alerts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,7 +10,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "prepare": "npm run build",
+    "prepare": "npm run build && npm run test",
     "test": "vitest run"
   },
   "repository": {
@@ -19,10 +19,14 @@
   },
   "keywords": [
     "polymarket",
+    "polymarket-api",
     "websocket",
     "price",
     "market",
-    "alerts"
+    "alerts",
+    "real-time",
+    "trading",
+    "prediction-markets"
   ],
   "author": "Konstantinos Lekkas",
   "license": "AGPL-3.0",

package/src/types/PolymarketWebSocket.ts

@@ -221,7 +221,7 @@ export type WebSocketHandlers = {
         and denotes the probability of an event happening. Read more about it here:
         https://docs.polymarket.com/polymarket-learn/trading/how-are-prices-calculated#future-price
 
-        This is an aggregate event that is not emmited by the Polymarket WebSocket directly.
+        This is a derived event that is not emmited by the Polymarket WebSocket directly.
     */
     onPolymarketPriceUpdate?: (events: PolymarketPriceUpdateEvent[]) => Promise<void>;