@catalyst-team/poly-sdk 0.2.0 → 0.2.1

package/src/core/unified-cache.ts

@@ -1,153 +0,0 @@
-/**
- * Unified cache interface for poly-sdk
- *
- * Bridges between:
- * 1. Legacy internal Cache (synchronous get/set with millisecond TTL)
- * 2. New CacheAdapter interface (async with second TTL)
- *
- * This allows the SDK to accept external cache adapters while maintaining
- * backward compatibility with existing code.
- */
-
-import type { CacheAdapter } from '@catalyst-team/cache';
-import { Cache, CACHE_TTL } from './cache.js';
-
-/**
- * Unified cache interface that works with both legacy Cache and CacheAdapter
- *
- * Key features:
- * - Async API (compatible with CacheAdapter)
- * - Millisecond TTL (compatible with existing SDK code)
- * - getOrSet helper for cache-aside pattern
- */
-export interface UnifiedCache {
-  get<T>(key: string): Promise<T | undefined>;
-  set<T>(key: string, value: T, ttlMs: number): Promise<void>;
-  getOrSet<T>(key: string, ttlMs: number, factory: () => Promise<T>): Promise<T>;
-  invalidate(pattern: string): Promise<void>;
-  clear(): void;
-}
-
-/**
- * Wraps the legacy Cache class to provide async interface
- */
-export class LegacyCacheWrapper implements UnifiedCache {
-  constructor(private cache: Cache) {}
-
-  async get<T>(key: string): Promise<T | undefined> {
-    return this.cache.get<T>(key);
-  }
-
-  async set<T>(key: string, value: T, ttlMs: number): Promise<void> {
-    this.cache.set(key, value, ttlMs);
-  }
-
-  async getOrSet<T>(
-    key: string,
-    ttlMs: number,
-    factory: () => Promise<T>
-  ): Promise<T> {
-    return this.cache.getOrSet(key, ttlMs, factory);
-  }
-
-  async invalidate(pattern: string): Promise<void> {
-    this.cache.invalidate(pattern);
-  }
-
-  clear(): void {
-    this.cache.clear();
-  }
-}
-
-/**
- * Wraps a CacheAdapter to provide legacy-compatible interface
- *
- * Main differences:
- * - Converts milliseconds to seconds for TTL
- * - Returns undefined instead of null for missing keys
- * - Implements getOrSet helper
- * - Implements pattern-based invalidation (limited support)
- */
-export class CacheAdapterWrapper implements UnifiedCache {
-  constructor(private adapter: CacheAdapter) {}
-
-  async get<T>(key: string): Promise<T | undefined> {
-    const value = await this.adapter.get<T>(key);
-    return value ?? undefined;
-  }
-
-  async set<T>(key: string, value: T, ttlMs: number): Promise<void> {
-    // Convert milliseconds to seconds
-    const ttlSeconds = Math.ceil(ttlMs / 1000);
-
-    // Check if this is a CacheManager (has getStats method)
-    if ('getStats' in this.adapter) {
-      // This is a CacheManager - use CacheSetOptions signature
-      await (this.adapter as any).set(key, value, { ttl: ttlSeconds });
-    } else {
-      // This is a regular CacheAdapter - use simple signature
-      await 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);
-
-    // Check if this is a CacheManager
-    if ('getStats' in this.adapter) {
-      // This is a CacheManager
-      await (this.adapter as any).set(key, value, { ttl: ttlSeconds });
-    } else {
-      // This is a regular CacheAdapter
-      await this.adapter.set(key, value, ttlSeconds);
-    }
-    return value;
-  }
-
-  async invalidate(pattern: string): Promise<void> {
-    // CacheAdapter doesn't have pattern matching
-    // Best we can do is warn - this is a limitation
-    console.warn(
-      `invalidate(pattern="${pattern}") not fully supported with external cache adapter`
-    );
-  }
-
-  clear(): void {
-    void this.adapter.clear?.();
-  }
-}
-
-/**
- * Create a UnifiedCache from either legacy Cache or CacheAdapter
- */
-export function createUnifiedCache(
-  cache?: CacheAdapter | Cache
-): UnifiedCache {
-  if (!cache) {
-    // No cache provided, create default legacy cache
-    return new LegacyCacheWrapper(new Cache());
-  }
-
-  // Check if it's a CacheAdapter (has async get method)
-  if ('get' in cache && typeof cache.get === 'function') {
-    const testResult = cache.get('test');
-    if (testResult instanceof Promise) {
-      // It's a CacheAdapter
-      return new CacheAdapterWrapper(cache as CacheAdapter);
-    }
-  }
-
-  // It's a legacy Cache
-  return new LegacyCacheWrapper(cache as Cache);
-}
-
-// Re-export CACHE_TTL for convenience
-export { CACHE_TTL };

package/src/index.ts

@@ -1,461 +0,0 @@
-/**
- * @catalyst-team/poly-sdk
- *
- * Unified SDK for Polymarket APIs
- * - Data API (positions, activity, trades, leaderboard)
- * - Gamma API (markets, events, trending)
- * - CLOB API (orderbook, market info, trading)
- * - Services (WalletService, MarketService)
- */
-
-// Core infrastructure
-export { RateLimiter, ApiType } from './core/rate-limiter.js';
-export { Cache, CACHE_TTL } from './core/cache.js';
-export { PolymarketError, ErrorCode, withRetry } from './core/errors.js';
-export * from './core/types.js';
-
-// Cache integration (new)
-export type { UnifiedCache } from './core/unified-cache.js';
-export { createUnifiedCache } from './core/unified-cache.js';
-
-// API Clients
-export { DataApiClient } from './clients/data-api.js';
-export type {
-  Position,
-  Activity,
-  Trade,
-  LeaderboardEntry,
-  LeaderboardPage,
-} from './clients/data-api.js';
-
-export { GammaApiClient } from './clients/gamma-api.js';
-export type {
-  GammaMarket,
-  GammaEvent,
-  MarketSearchParams,
-} from './clients/gamma-api.js';
-
-export { ClobApiClient } from './clients/clob-api.js';
-export type {
-  ClobMarket,
-  ClobToken,
-  Orderbook,
-  OrderbookLevel,
-} from './clients/clob-api.js';
-
-// Services
-export { WalletService } from './services/wallet-service.js';
-export type {
-  WalletProfile,
-  WalletActivitySummary,
-  SellActivityResult,
-} from './services/wallet-service.js';
-
-export { MarketService, getIntervalMs as getIntervalMsService } from './services/market-service.js';
-
-// Real-time
-export { WebSocketManager } from './clients/websocket-manager.js';
-export type { WebSocketManagerConfig, WebSocketManagerEvents } from './clients/websocket-manager.js';
-
-export { RealtimeService } from './services/realtime-service.js';
-export type { Subscription, MarketSubscriptionHandlers } from './services/realtime-service.js';
-
-// ArbitrageService (Real-time arbitrage detection, execution, rebalancing, and settlement)
-export { ArbitrageService } from './services/arbitrage-service.js';
-export type {
-  ArbitrageMarketConfig,
-  ArbitrageServiceConfig,
-  ArbitrageOpportunity as ArbitrageServiceOpportunity,
-  ArbitrageExecutionResult,
-  ArbitrageServiceEvents,
-  OrderbookState,
-  BalanceState,
-  // Rebalancer types
-  RebalanceAction,
-  RebalanceResult,
-  // Settle types
-  SettleResult,
-  // Clear position types (smart settle)
-  ClearPositionResult,
-  ClearAction,
-  // Scanning types
-  ScanCriteria,
-  ScanResult,
-} from './services/arbitrage-service.js';
-
-// Trading
-export { TradingClient, POLYGON_MAINNET, POLYGON_AMOY } from './clients/trading-client.js';
-export type {
-  Side,
-  OrderType,
-  ApiCredentials,
-  OrderParams,
-  MarketOrderParams,
-  Order,
-  OrderResult,
-  TradeInfo,
-  TradingClientConfig,
-  // Rewards types
-  UserEarning,
-  MarketReward,
-  OrderScoring,
-} from './clients/trading-client.js';
-
-// CTF (Conditional Token Framework)
-// NOTE: USDC_CONTRACT is USDC.e (bridged), required for Polymarket CTF
-// NATIVE_USDC_CONTRACT is native USDC, NOT compatible with CTF
-export {
-  CTFClient,
-  CTF_CONTRACT,
-  USDC_CONTRACT,           // USDC.e (0x2791...) - Required for CTF
-  NATIVE_USDC_CONTRACT,    // Native USDC (0x3c49...) - NOT for CTF
-  NEG_RISK_CTF_EXCHANGE,
-  NEG_RISK_ADAPTER,
-  USDC_DECIMALS,
-  calculateConditionId,
-  parseUsdc,
-  formatUsdc,
-} from './clients/ctf-client.js';
-export type {
-  CTFConfig,
-  SplitResult,
-  MergeResult,
-  RedeemResult,
-  PositionBalance,
-  MarketResolution,
-  GasEstimate,
-  TransactionStatus,
-  TokenIds,
-} from './clients/ctf-client.js';
-export { RevertReason } from './clients/ctf-client.js';
-
-// Bridge (Cross-chain Deposits)
-export {
-  BridgeClient,
-  SUPPORTED_CHAINS,
-  BRIDGE_TOKENS,
-  estimateBridgeOutput,
-  getExplorerUrl,
-  depositUsdc,
-  swapAndDeposit,
-  getSupportedDepositTokens,
-} from './clients/bridge-client.js';
-export type {
-  BridgeSupportedAsset,
-  DepositAddress,
-  CreateDepositResponse,
-  DepositStatus,
-  BridgeConfig,
-  DepositResult,
-  DepositOptions,
-  SwapAndDepositOptions,
-  SwapAndDepositResult,
-} from './clients/bridge-client.js';
-
-// Swap Service (DEX swaps on Polygon)
-export {
-  SwapService,
-  QUICKSWAP_ROUTER,
-  POLYGON_TOKENS,
-  TOKEN_DECIMALS,
-} from './services/swap-service.js';
-export type {
-  SupportedToken,
-  SwapQuote,
-  SwapResult,
-  TokenBalance,
-  TransferResult,
-} from './services/swap-service.js';
-
-// Authorization (ERC20/ERC1155 Approvals)
-export { AuthorizationService } from './services/authorization-service.js';
-export type {
-  AllowanceInfo,
-  AllowancesResult,
-  ApprovalTxResult,
-  ApprovalsResult,
-  AuthorizationServiceConfig,
-} from './services/authorization-service.js';
-
-// Price Utilities
-export {
-  roundPrice,
-  roundSize,
-  validatePrice,
-  validateSize,
-  calculateBuyAmount,
-  calculateSellPayout,
-  calculateSharesForAmount,
-  calculateSpread,
-  calculateMidpoint,
-  formatPrice,
-  formatUSDC,
-  calculatePnL,
-  checkArbitrage,
-  getEffectivePrices,
-  ROUNDING_CONFIG,
-} from './utils/price-utils.js';
-export type { TickSize } from './utils/price-utils.js';
-
-// NOTE: MCP tools have been moved to @catalyst-team/poly-mcp package
-// See packages/poly-mcp/
-
-// ===== Main SDK Class =====
-
-import { RateLimiter } from './core/rate-limiter.js';
-import { DataApiClient } from './clients/data-api.js';
-import { GammaApiClient } from './clients/gamma-api.js';
-import { ClobApiClient } from './clients/clob-api.js';
-import { WalletService } from './services/wallet-service.js';
-import { MarketService } from './services/market-service.js';
-import type { UnifiedMarket, ProcessedOrderbook, ArbitrageOpportunity, KLineInterval, KLineCandle, DualKLineData, PolySDKOptions } from './core/types.js';
-import { PolymarketError, ErrorCode } from './core/errors.js';
-import { createUnifiedCache, type UnifiedCache } from './core/unified-cache.js';
-
-// Re-export for backward compatibility
-export interface PolymarketSDKConfig extends PolySDKOptions {}
-
-export class PolymarketSDK {
-  // Infrastructure
-  private rateLimiter: RateLimiter;
-  private cache: UnifiedCache;
-
-  // API Clients
-  public readonly dataApi: DataApiClient;
-  public readonly gammaApi: GammaApiClient;
-  public readonly clobApi: ClobApiClient;
-
-  // Services
-  public readonly wallets: WalletService;
-  public readonly markets: MarketService;
-
-  constructor(config: PolymarketSDKConfig = {}) {
-    // Initialize infrastructure
-    this.rateLimiter = new RateLimiter();
-
-    // Create unified cache (supports both legacy Cache and CacheAdapter)
-    this.cache = createUnifiedCache(config.cache);
-
-    // Initialize API clients
-    this.dataApi = new DataApiClient(this.rateLimiter, this.cache);
-    this.gammaApi = new GammaApiClient(this.rateLimiter, this.cache);
-    this.clobApi = new ClobApiClient(this.rateLimiter, this.cache, {
-      chainId: config.chainId,
-      signer: config.signer,
-      creds: config.creds,
-    });
-
-    // Initialize services
-    this.wallets = new WalletService(this.dataApi, this.cache);
-    this.markets = new MarketService(this.gammaApi, this.clobApi, this.dataApi, this.cache);
-  }
-
-  // ===== Unified Market Access =====
-
-  /**
-   * Get market by slug or condition ID
-   * Uses Gamma for slug, CLOB for conditionId
-   */
-  async getMarket(identifier: string): Promise<UnifiedMarket> {
-    const isConditionId =
-      identifier.startsWith('0x') || /^\d+$/.test(identifier);
-
-    if (isConditionId) {
-      return this.getMarketByConditionId(identifier);
-    } else {
-      return this.getMarketBySlug(identifier);
-    }
-  }
-
-  private async getMarketBySlug(slug: string): Promise<UnifiedMarket> {
-    // Gamma as primary source for slug
-    const gammaMarket = await this.gammaApi.getMarketBySlug(slug);
-    if (!gammaMarket) {
-      throw new PolymarketError(
-        ErrorCode.MARKET_NOT_FOUND,
-        `Market not found: ${slug}`
-      );
-    }
-
-    // Enrich with CLOB data
-    try {
-      const clobMarket = await this.clobApi.getMarket(gammaMarket.conditionId);
-      return this.mergeMarkets(gammaMarket, clobMarket);
-    } catch {
-      return this.fromGammaMarket(gammaMarket);
-    }
-  }
-
-  private async getMarketByConditionId(
-    conditionId: string
-  ): Promise<UnifiedMarket> {
-    // CLOB as primary source for conditionId (more reliable)
-    try {
-      const clobMarket = await this.clobApi.getMarket(conditionId);
-
-      // Try to enrich with Gamma data
-      try {
-        const gammaMarket =
-          await this.gammaApi.getMarketByConditionId(conditionId);
-        if (gammaMarket) {
-          return this.mergeMarkets(gammaMarket, clobMarket);
-        }
-      } catch {
-        // Gamma enrichment failed, use CLOB only
-      }
-
-      return this.fromClobMarket(clobMarket);
-    } catch {
-      throw new PolymarketError(
-        ErrorCode.MARKET_NOT_FOUND,
-        `Market not found: ${conditionId}`
-      );
-    }
-  }
-
-  // ===== Orderbook Analysis =====
-
-  /**
-   * Get processed orderbook with analytics
-   */
-  async getOrderbook(conditionId: string): Promise<ProcessedOrderbook> {
-    return this.clobApi.getProcessedOrderbook(conditionId);
-  }
-
-  /**
-   * Detect arbitrage opportunity
-   *
-   * 使用有效价格计算套利机会（正确考虑镜像订单）
-   * 详细文档见: docs/01-polymarket-orderbook-arbitrage.md
-   */
-  async detectArbitrage(
-    conditionId: string,
-    threshold = 0.005
-  ): Promise<ArbitrageOpportunity | null> {
-    const orderbook = await this.getOrderbook(conditionId);
-    const { effectivePrices, longArbProfit, shortArbProfit } = orderbook.summary;
-
-    if (longArbProfit > threshold) {
-      return {
-        type: 'long',
-        profit: longArbProfit,
-        action: `Buy YES @ ${effectivePrices.effectiveBuyYes.toFixed(4)} + Buy NO @ ${effectivePrices.effectiveBuyNo.toFixed(4)}, merge for 1 USDC`,
-        expectedProfit: longArbProfit,
-      };
-    }
-
-    if (shortArbProfit > threshold) {
-      return {
-        type: 'short',
-        profit: shortArbProfit,
-        action: `Split 1 USDC, Sell YES @ ${effectivePrices.effectiveSellYes.toFixed(4)} + Sell NO @ ${effectivePrices.effectiveSellNo.toFixed(4)}`,
-        expectedProfit: shortArbProfit,
-      };
-    }
-
-    return null;
-  }
-
-  // ===== Helper Methods =====
-
-  private mergeMarkets(
-    gamma: import('./clients/gamma-api.js').GammaMarket,
-    clob: import('./clients/clob-api.js').ClobMarket
-  ): UnifiedMarket {
-    const yesToken = clob.tokens.find((t) => t.outcome === 'Yes');
-    const noToken = clob.tokens.find((t) => t.outcome === 'No');
-
-    return {
-      conditionId: clob.conditionId,
-      slug: gamma.slug,
-      question: clob.question,
-      description: clob.description || gamma.description,
-      tokens: {
-        yes: {
-          tokenId: yesToken?.tokenId || '',
-          price: yesToken?.price || gamma.outcomePrices[0] || 0.5,
-        },
-        no: {
-          tokenId: noToken?.tokenId || '',
-          price: noToken?.price || gamma.outcomePrices[1] || 0.5,
-        },
-      },
-      volume: gamma.volume,
-      volume24hr: gamma.volume24hr,
-      liquidity: gamma.liquidity,
-      spread: gamma.spread,
-      active: clob.active,
-      closed: clob.closed,
-      acceptingOrders: clob.acceptingOrders,
-      endDate: clob.endDateIso ? new Date(clob.endDateIso) : new Date(),
-      source: 'merged',
-    };
-  }
-
-  private fromGammaMarket(
-    gamma: import('./clients/gamma-api.js').GammaMarket
-  ): UnifiedMarket {
-    return {
-      conditionId: gamma.conditionId,
-      slug: gamma.slug,
-      question: gamma.question,
-      description: gamma.description,
-      tokens: {
-        yes: { tokenId: '', price: gamma.outcomePrices[0] || 0.5 },
-        no: { tokenId: '', price: gamma.outcomePrices[1] || 0.5 },
-      },
-      volume: gamma.volume,
-      volume24hr: gamma.volume24hr,
-      liquidity: gamma.liquidity,
-      spread: gamma.spread,
-      active: gamma.active,
-      closed: gamma.closed,
-      acceptingOrders: !gamma.closed,
-      endDate: gamma.endDate,
-      source: 'gamma',
-    };
-  }
-
-  private fromClobMarket(
-    clob: import('./clients/clob-api.js').ClobMarket
-  ): UnifiedMarket {
-    const yesToken = clob.tokens.find((t) => t.outcome === 'Yes');
-    const noToken = clob.tokens.find((t) => t.outcome === 'No');
-
-    return {
-      conditionId: clob.conditionId,
-      slug: clob.marketSlug,
-      question: clob.question,
-      description: clob.description,
-      tokens: {
-        yes: { tokenId: yesToken?.tokenId || '', price: yesToken?.price || 0.5 },
-        no: { tokenId: noToken?.tokenId || '', price: noToken?.price || 0.5 },
-      },
-      volume: 0, // CLOB doesn't have volume
-      volume24hr: undefined,
-      liquidity: 0,
-      spread: undefined,
-      active: clob.active,
-      closed: clob.closed,
-      acceptingOrders: clob.acceptingOrders,
-      endDate: clob.endDateIso ? new Date(clob.endDateIso) : new Date(),
-      source: 'clob',
-    };
-  }
-
-  // ===== Cache Management =====
-
-  /**
-   * Clear all cached data
-   */
-  clearCache(): void {
-    this.cache.clear();
-  }
-
-  /**
-   * Invalidate cache for a specific market
-   */
-  invalidateMarketCache(conditionId: string): void {
-    this.cache.invalidate(conditionId);
-  }
-}