@catalyst-team/poly-sdk 0.1.0

package/src/clients/websocket-manager.ts

@@ -0,0 +1,267 @@
+/**
+ * WebSocket Manager
+ *
+ * Wraps @nevuamarkets/poly-websockets for real-time market data:
+ * - Price updates (derived from order book and trades)
+ * - Order book snapshots
+ * - Last trade price events
+ *
+ * Features:
+ * - Automatic connection management
+ * - Rate limiting built-in
+ * - Price caching for quick access
+ * - EventEmitter-based event distribution
+ */
+
+import { EventEmitter } from 'events';
+import type { PriceUpdate, BookUpdate } from '../core/types.js';
+
+// Note: poly-websockets types (these match the library's exports)
+interface PolymarketPriceUpdateEvent {
+  event_type: 'price_update';
+  asset_id: string;
+  timestamp: string;
+  price: string;
+  midpoint: string;
+  spread: string;
+}
+
+interface BookEvent {
+  market: string;
+  asset_id: string;
+  timestamp: string;
+  bids: Array<{ price: string; size: string }>;
+  asks: Array<{ price: string; size: string }>;
+  event_type: 'book';
+}
+
+interface LastTradePriceEvent {
+  asset_id: string;
+  event_type: 'last_trade_price';
+  price: string;
+  side: 'BUY' | 'SELL';
+  size: string;
+  timestamp: string;
+}
+
+export interface WebSocketManagerConfig {
+  maxMarketsPerWS?: number;
+  enableLogging?: boolean;
+}
+
+export interface WebSocketManagerEvents {
+  priceUpdate: (update: PriceUpdate) => void;
+  bookUpdate: (update: BookUpdate) => void;
+  lastTrade: (trade: { assetId: string; price: number; side: 'BUY' | 'SELL'; size: number; timestamp: number }) => void;
+  connected: (info: { groupId: string; assetIds: string[] }) => void;
+  disconnected: (info: { groupId: string; code: number; reason: string }) => void;
+  error: (error: Error) => void;
+}
+
+export class WebSocketManager extends EventEmitter {
+  private wsManager: unknown; // WSSubscriptionManager instance
+  private subscriptions: Set<string> = new Set();
+  private priceCache: Map<string, PriceUpdate> = new Map();
+  private bookCache: Map<string, BookUpdate> = new Map();
+  private initialized = false;
+  private config: WebSocketManagerConfig;
+
+  constructor(config: WebSocketManagerConfig = {}) {
+    super();
+    this.config = {
+      maxMarketsPerWS: config.maxMarketsPerWS || 100,
+      enableLogging: config.enableLogging ?? false,
+    };
+  }
+
+  /**
+   * Initialize the WebSocket manager (lazy initialization)
+   */
+  private async ensureInitialized(): Promise<void> {
+    if (this.initialized) return;
+
+    try {
+      // Dynamic import to handle the package not being installed
+      const { WSSubscriptionManager } = await import('@nevuamarkets/poly-websockets');
+
+      this.wsManager = new WSSubscriptionManager(
+        {
+          onPolymarketPriceUpdate: this.handlePriceUpdate.bind(this),
+          onBook: this.handleBookUpdate.bind(this),
+          onLastTradePrice: this.handleLastTradePrice.bind(this),
+          onWSOpen: this.handleOpen.bind(this),
+          onWSClose: this.handleClose.bind(this),
+          onError: this.handleError.bind(this),
+        },
+        {
+          maxMarketsPerWS: this.config.maxMarketsPerWS,
+        }
+      );
+
+      this.initialized = true;
+    } catch (error) {
+      throw new Error(
+        'Failed to initialize WebSocket manager. Make sure @nevuamarkets/poly-websockets is installed.'
+      );
+    }
+  }
+
+  // ===== Subscription Management =====
+
+  /**
+   * Subscribe to asset price updates
+   */
+  async subscribe(assetIds: string[]): Promise<void> {
+    await this.ensureInitialized();
+
+    const newIds = assetIds.filter((id) => !this.subscriptions.has(id));
+    if (newIds.length === 0) return;
+
+    const manager = this.wsManager as { addSubscriptions: (ids: string[]) => Promise<void> };
+    await manager.addSubscriptions(newIds);
+    newIds.forEach((id) => this.subscriptions.add(id));
+  }
+
+  /**
+   * Unsubscribe from asset price updates
+   */
+  async unsubscribe(assetIds: string[]): Promise<void> {
+    if (!this.initialized) return;
+
+    const existingIds = assetIds.filter((id) => this.subscriptions.has(id));
+    if (existingIds.length === 0) return;
+
+    const manager = this.wsManager as { removeSubscriptions: (ids: string[]) => Promise<void> };
+    await manager.removeSubscriptions(existingIds);
+    existingIds.forEach((id) => {
+      this.subscriptions.delete(id);
+      this.priceCache.delete(id);
+      this.bookCache.delete(id);
+    });
+  }
+
+  /**
+   * Unsubscribe from all assets and cleanup
+   */
+  async unsubscribeAll(): Promise<void> {
+    if (!this.initialized) return;
+
+    const manager = this.wsManager as { clearState: () => Promise<void> };
+    await manager.clearState();
+    this.subscriptions.clear();
+    this.priceCache.clear();
+    this.bookCache.clear();
+  }
+
+  // ===== Price Cache Access =====
+
+  /**
+   * Get cached price for an asset
+   */
+  getPrice(assetId: string): PriceUpdate | undefined {
+    return this.priceCache.get(assetId);
+  }
+
+  /**
+   * Get all cached prices
+   */
+  getAllPrices(): Map<string, PriceUpdate> {
+    return new Map(this.priceCache);
+  }
+
+  /**
+   * Get cached order book for an asset
+   */
+  getBook(assetId: string): BookUpdate | undefined {
+    return this.bookCache.get(assetId);
+  }
+
+  // ===== State Query =====
+
+  /**
+   * Get subscribed asset IDs
+   */
+  getSubscribedAssets(): string[] {
+    return Array.from(this.subscriptions);
+  }
+
+  /**
+   * Get connection statistics
+   */
+  getStatistics(): { groups: number; subscriptions: number } | null {
+    if (!this.initialized) return null;
+
+    const manager = this.wsManager as { getStatistics: () => { groups: number; subscriptions: number } };
+    return manager.getStatistics();
+  }
+
+  /**
+   * Check if initialized
+   */
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  // ===== Event Handlers =====
+
+  private async handlePriceUpdate(events: PolymarketPriceUpdateEvent[]): Promise<void> {
+    for (const event of events) {
+      const update: PriceUpdate = {
+        assetId: event.asset_id,
+        price: parseFloat(event.price),
+        midpoint: parseFloat(event.midpoint),
+        spread: parseFloat(event.spread),
+        timestamp: parseInt(event.timestamp, 10),
+      };
+      this.priceCache.set(event.asset_id, update);
+      this.emit('priceUpdate', update);
+    }
+  }
+
+  private async handleBookUpdate(events: BookEvent[]): Promise<void> {
+    for (const event of events) {
+      // Parse and sort bids descending (highest price = best bid first)
+      const bids = event.bids
+        .map((l) => ({ price: parseFloat(l.price), size: parseFloat(l.size) }))
+        .sort((a, b) => b.price - a.price);
+
+      // Parse and sort asks ascending (lowest price = best ask first)
+      const asks = event.asks
+        .map((l) => ({ price: parseFloat(l.price), size: parseFloat(l.size) }))
+        .sort((a, b) => a.price - b.price);
+
+      const update: BookUpdate = {
+        assetId: event.asset_id,
+        bids,
+        asks,
+        timestamp: parseInt(event.timestamp, 10),
+      };
+      this.bookCache.set(event.asset_id, update);
+      this.emit('bookUpdate', update);
+    }
+  }
+
+  private async handleLastTradePrice(events: LastTradePriceEvent[]): Promise<void> {
+    for (const event of events) {
+      this.emit('lastTrade', {
+        assetId: event.asset_id,
+        price: parseFloat(event.price),
+        side: event.side,
+        size: parseFloat(event.size),
+        timestamp: parseInt(event.timestamp, 10),
+      });
+    }
+  }
+
+  private async handleOpen(groupId: string, assetIds: string[]): Promise<void> {
+    this.emit('connected', { groupId, assetIds });
+  }
+
+  private async handleClose(groupId: string, code: number, reason: string): Promise<void> {
+    this.emit('disconnected', { groupId, code, reason });
+  }
+
+  private async handleError(error: Error): Promise<void> {
+    this.emit('error', error);
+  }
+}

package/src/core/cache-adapter-bridge.ts

@@ -0,0 +1,94 @@
+/**
+ * Bridge adapter between legacy Cache class and new CacheAdapter interface
+ *
+ * This allows the SDK to work with both:
+ * 1. Legacy internal Cache (synchronous, millisecond TTL)
+ * 2. New CacheAdapter interface (async, second TTL)
+ */
+
+import type { CacheAdapter } from '@prediction-router/cache';
+import { Cache } from './cache.js';
+
+/**
+ * Wraps the legacy Cache class to implement CacheAdapter interface
+ */
+export class LegacyCacheAdapter implements CacheAdapter {
+  constructor(private cache: Cache) {}
+
+  async get<T>(key: string): Promise<T | null> {
+    const value = this.cache.get<T>(key);
+    return value === undefined ? null : value;
+  }
+
+  async set<T>(key: string, value: T, ttl?: number): Promise<void> {
+    // Convert seconds to milliseconds (CacheAdapter uses seconds, Cache uses ms)
+    const ttlMs = ttl ? ttl * 1000 : 60000; // Default 60s
+    this.cache.set(key, value, ttlMs);
+  }
+
+  async del(key: string): Promise<void> {
+    this.cache.invalidate(key);
+  }
+
+  async exists(key: string): Promise<boolean> {
+    const value = this.cache.get(key);
+    return value !== undefined;
+  }
+
+  async clear(): Promise<void> {
+    this.cache.clear();
+  }
+}
+
+/**
+ * Wraps a CacheAdapter to provide the legacy Cache interface
+ * This allows using new cache adapters with code expecting the old Cache class
+ */
+export class CacheAdapterWrapper {
+  constructor(private adapter: CacheAdapter) {}
+
+  get<T>(key: string): T | undefined {
+    // Note: This makes an async operation sync, which may cause issues
+    // However, we need to maintain backward compatibility
+    let result: T | undefined;
+    this.adapter.get<T>(key).then((value) => {
+      result = value ?? undefined;
+    });
+    return result;
+  }
+
+  set<T>(key: string, value: T, ttlMs: number): void {
+    // Convert milliseconds to seconds
+    const ttlSeconds = Math.ceil(ttlMs / 1000);
+    void this.adapter.set(key, value, ttlSeconds);
+  }
+
+  async getOrSet<T>(
+    key: string,
+    ttlMs: number,
+    factory: () => Promise<T>
+  ): Promise<T> {
+    const cached = await this.adapter.get<T>(key);
+    if (cached !== null) return cached;
+
+    const value = await factory();
+    const ttlSeconds = Math.ceil(ttlMs / 1000);
+    await this.adapter.set(key, value, ttlSeconds);
+    return value;
+  }
+
+  invalidate(pattern: string): void {
+    // CacheAdapter doesn't have pattern matching, so we can't implement this
+    // This is a limitation of the adapter approach
+    console.warn('invalidate(pattern) not supported with external cache adapter');
+  }
+
+  clear(): void {
+    void this.adapter.clear?.();
+  }
+
+  size(): number {
+    // CacheAdapter doesn't expose size, return -1 to indicate unknown
+    return -1;
+  }
+}

package/src/core/cache.ts

@@ -0,0 +1,85 @@
+/**
+ * Simple in-memory cache with TTL support
+ */
+
+interface CacheEntry<T> {
+  value: T;
+  expiresAt: number;
+}
+
+export class Cache {
+  private store: Map<string, CacheEntry<unknown>> = new Map();
+
+  /**
+   * Get a cached value
+   */
+  get<T>(key: string): T | undefined {
+    const entry = this.store.get(key);
+    if (!entry) return undefined;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return undefined;
+    }
+    return entry.value as T;
+  }
+
+  /**
+   * Set a cached value with TTL
+   */
+  set<T>(key: string, value: T, ttlMs: number): void {
+    this.store.set(key, {
+      value,
+      expiresAt: Date.now() + ttlMs,
+    });
+  }
+
+  /**
+   * Get a cached value or set it if not present
+   */
+  async getOrSet<T>(
+    key: string,
+    ttlMs: number,
+    factory: () => Promise<T>
+  ): Promise<T> {
+    const cached = this.get<T>(key);
+    if (cached !== undefined) return cached;
+    const value = await factory();
+    this.set(key, value, ttlMs);
+    return value;
+  }
+
+  /**
+   * Invalidate all keys matching a pattern
+   */
+  invalidate(pattern: string): void {
+    for (const key of this.store.keys()) {
+      if (key.includes(pattern)) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Clear all cached values
+   */
+  clear(): void {
+    this.store.clear();
+  }
+
+  /**
+   * Get the number of cached entries
+   */
+  size(): number {
+    return this.store.size;
+  }
+}
+
+/**
+ * Cache TTL constants (in milliseconds)
+ */
+export const CACHE_TTL = {
+  MARKET_INFO: 60 * 1000, // 1 minute
+  WALLET_POSITIONS: 5 * 60 * 1000, // 5 minutes
+  LEADERBOARD: 60 * 60 * 1000, // 1 hour
+  TICK_SIZE: 24 * 60 * 60 * 1000, // 24 hours
+};

package/src/core/errors.ts

@@ -0,0 +1,117 @@
+/**
+ * Unified error handling for Polymarket SDK
+ */
+
+export enum ErrorCode {
+  // Network errors
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  TIMEOUT = 'TIMEOUT',
+  RATE_LIMITED = 'RATE_LIMITED',
+
+  // Authentication errors
+  AUTH_FAILED = 'AUTH_FAILED',
+  API_KEY_EXPIRED = 'API_KEY_EXPIRED',
+  INVALID_SIGNATURE = 'INVALID_SIGNATURE',
+
+  // Data errors
+  MARKET_NOT_FOUND = 'MARKET_NOT_FOUND',
+  WALLET_NOT_FOUND = 'WALLET_NOT_FOUND',
+  INVALID_RESPONSE = 'INVALID_RESPONSE',
+
+  // Trading errors
+  INSUFFICIENT_BALANCE = 'INSUFFICIENT_BALANCE',
+  ORDER_REJECTED = 'ORDER_REJECTED',
+  ORDER_FAILED = 'ORDER_FAILED',
+  MARKET_CLOSED = 'MARKET_CLOSED',
+
+  // API errors
+  API_ERROR = 'API_ERROR',
+
+  // Internal errors
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+}
+
+export class PolymarketError extends Error {
+  constructor(
+    public code: ErrorCode,
+    message: string,
+    public retryable: boolean = false,
+    public originalError?: Error
+  ) {
+    super(message);
+    this.name = 'PolymarketError';
+  }
+
+  /**
+   * Create error from HTTP response status
+   */
+  static fromHttpError(status: number, body?: unknown): PolymarketError {
+    const bodyMessage =
+      body && typeof body === 'object' && 'message' in body
+        ? String((body as { message: unknown }).message)
+        : '';
+
+    switch (status) {
+      case 429:
+        return new PolymarketError(
+          ErrorCode.RATE_LIMITED,
+          bodyMessage || 'Rate limited',
+          true
+        );
+      case 401:
+        return new PolymarketError(
+          ErrorCode.AUTH_FAILED,
+          bodyMessage || 'Authentication failed'
+        );
+      case 403:
+        return new PolymarketError(
+          ErrorCode.AUTH_FAILED,
+          bodyMessage || 'Forbidden'
+        );
+      case 404:
+        return new PolymarketError(
+          ErrorCode.MARKET_NOT_FOUND,
+          bodyMessage || 'Resource not found'
+        );
+      case 400:
+        return new PolymarketError(
+          ErrorCode.INVALID_RESPONSE,
+          bodyMessage || 'Bad request'
+        );
+      default:
+        return new PolymarketError(
+          ErrorCode.NETWORK_ERROR,
+          bodyMessage || `HTTP ${status}`,
+          status >= 500
+        );
+    }
+  }
+}
+
+/**
+ * Retry decorator for async functions
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: { maxRetries?: number; delay?: number } = {}
+): Promise<T> {
+  const { maxRetries = 3, delay = 1000 } = options;
+
+  let lastError: Error | undefined;
+
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error as Error;
+      if (error instanceof PolymarketError && !error.retryable) {
+        throw error;
+      }
+      if (i < maxRetries - 1) {
+        await new Promise((r) => setTimeout(r, delay * Math.pow(2, i)));
+      }
+    }
+  }
+
+  throw lastError;
+}

package/src/core/rate-limiter.ts

@@ -0,0 +1,74 @@
+/**
+ * Rate Limiter for Polymarket APIs
+ * - Data API: 100ms minimum interval
+ * - Gamma API: 10 req/s
+ * - CLOB API: 10 req/s
+ */
+
+import Bottleneck from 'bottleneck';
+
+export enum ApiType {
+  DATA_API = 'data-api',
+  GAMMA_API = 'gamma-api',
+  CLOB_API = 'clob-api',
+}
+
+const API_LIMITS: Record<ApiType, Bottleneck.ConstructorOptions> = {
+  [ApiType.DATA_API]: {
+    minTime: 100, // 100ms minimum interval
+    maxConcurrent: 5,
+  },
+  [ApiType.GAMMA_API]: {
+    reservoir: 10,
+    reservoirRefreshAmount: 10,
+    reservoirRefreshInterval: 1000,
+  },
+  [ApiType.CLOB_API]: {
+    reservoir: 10,
+    reservoirRefreshAmount: 10,
+    reservoirRefreshInterval: 1000,
+  },
+};
+
+export class RateLimiter {
+  private limiters: Map<ApiType, Bottleneck> = new Map();
+
+  constructor() {
+    for (const [type, config] of Object.entries(API_LIMITS)) {
+      this.limiters.set(type as ApiType, new Bottleneck(config));
+    }
+  }
+
+  /**
+   * Execute a function with rate limiting
+   */
+  async execute<T>(api: ApiType, fn: () => Promise<T>): Promise<T> {
+    const limiter = this.limiters.get(api);
+    if (!limiter) throw new Error(`Unknown API type: ${api}`);
+    return limiter.schedule(fn);
+  }
+
+  /**
+   * Execute multiple functions in order with rate limiting
+   */
+  async executeBatch<T>(api: ApiType, fns: (() => Promise<T>)[]): Promise<T[]> {
+    const results: T[] = [];
+    for (const fn of fns) {
+      results.push(await this.execute(api, fn));
+    }
+    return results;
+  }
+
+  /**
+   * Get current limiter statistics
+   */
+  getStats(api: ApiType): { running: number; queued: number } | null {
+    const limiter = this.limiters.get(api);
+    if (!limiter) return null;
+    const counts = limiter.counts();
+    return {
+      running: counts.RUNNING,
+      queued: counts.QUEUED,
+    };
+  }
+}