@deeptick/client 0.1.1

package/src/streaming.ts

@@ -0,0 +1,468 @@
+/**
+ * DeepTick TypeScript Client — Real-time Streaming
+ *
+ * Connects to the DeepTick WebSocket endpoint and delivers live market data.
+ * Works in both Node.js (via `ws` package) and browser environments.
+ *
+ * Install:
+ *   npm install @deeptick/client    # includes streaming
+ *   # Node.js also needs: npm install ws
+ *
+ * Usage:
+ *   import { DeepTickStream } from '@deeptick/client';
+ *
+ *   const stream = new DeepTickStream('wss://deeptick.lacertalabs.xyz/v1/stream');
+ *
+ *   stream.onTrade((exchange, symbol, trade) => {
+ *     console.log(`[${exchange}] ${symbol}: ${trade.price} x ${trade.amount}`);
+ *   });
+ *
+ *   stream.onBookTicker((exchange, symbol, ticker) => {
+ *     console.log(`[${exchange}] ${symbol}: ${ticker.bid_price}/${ticker.ask_price}`);
+ *   });
+ *
+ *   await stream.connect();
+ *   await stream.subscribe(['hyperliquid.trades.BTC', '*.book_ticker.*']);
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+/** Wire protocol frame from server */
+export interface StreamFrame {
+  type: 'data' | 'heartbeat' | 'welcome' | 'subscribed' | 'unsubscribed' | 'pong' | 'error';
+  topic?: string;
+  data?: Record<string, any>;
+  ts?: number;
+  connection_id?: string;
+  channels?: string[];
+  message?: string;
+  client_ts?: number;
+}
+
+/** Trade data from stream */
+export interface StreamTrade {
+  exchange: string;
+  symbol: string;
+  timestamp: number;
+  local_timestamp: number;
+  trade_id: string;
+  price: number;
+  amount: number;
+  side: 'buy' | 'sell';
+  data_type: 'trades';
+}
+
+/** Native top-of-book ticker data from stream */
+export interface StreamBookTicker {
+  exchange: string;
+  symbol: string;
+  timestamp: number;
+  local_timestamp: number;
+  bid_price: number;
+  bid_amount: number;
+  ask_price: number;
+  ask_amount: number;
+  data_type: 'book_ticker';
+}
+
+/** Book delta data from stream */
+export interface StreamBookDelta {
+  exchange: string;
+  symbol: string;
+  timestamp: number;
+  local_timestamp: number;
+  is_snapshot: boolean;
+  bids_packed: string;  // base64-encoded binary
+  asks_packed: string;
+  data_type: 'book_l2_delta';
+}
+
+/** Derivative ticker data from stream */
+export interface StreamDerivativeTicker {
+  exchange: string;
+  symbol: string;
+  timestamp: number;
+  local_timestamp: number;
+  funding_timestamp: number | null;
+  funding_rate: number | null;
+  predicted_funding_rate: number | null;
+  open_interest: number | null;
+  last_price: number | null;
+  mark_price: number | null;
+  index_price: number | null;
+  data_type: 'derivative_ticker';
+}
+
+/** Callback signature for data handlers */
+export type DataCallback<T = Record<string, any>> = (
+  exchange: string,
+  symbol: string,
+  data: T
+) => void;
+
+/** Streaming client options */
+export interface DeepTickStreamOptions {
+  /** WebSocket URL (default: wss://deeptick.lacertalabs.xyz/v1/stream) */
+  url?: string;
+  /** Auto-reconnect on disconnect (default: true) */
+  reconnect?: boolean;
+  /** Initial reconnect delay in ms (default: 1000) */
+  reconnectDelay?: number;
+  /** Max reconnect delay in ms (default: 30000) */
+  reconnectMaxDelay?: number;
+  /** Max queued messages before dropping (default: 10000) */
+  maxQueueSize?: number;
+}
+
+// ─── Streaming Client ───────────────────────────────────────────────
+
+export class DeepTickStream {
+  private url: string;
+  private reconnect: boolean;
+  private reconnectDelay: number;
+  private reconnectMaxDelay: number;
+  private currentDelay: number;
+  private maxQueueSize: number;
+
+  private ws: WebSocket | null = null;
+  private connected = false;
+  private stopped = false;
+  private channels: string[] = [];
+  private connectionId: string | null = null;
+
+  // Callbacks by data type
+  private tradeCallbacks: DataCallback<StreamTrade>[] = [];
+  private bookTickerCallbacks: DataCallback<StreamBookTicker>[] = [];
+  private bookDeltaCallbacks: DataCallback<StreamBookDelta>[] = [];
+  private derivativeTickerCallbacks: DataCallback<StreamDerivativeTicker>[] = [];
+  private liquidationCallbacks: DataCallback[] = [];
+  private globalCallbacks: DataCallback[] = [];
+
+  // Event callbacks
+  private connectCallbacks: (() => void)[] = [];
+  private disconnectCallbacks: ((reason: string) => void)[] = [];
+  private errorCallbacks: ((error: Error) => void)[] = [];
+
+  // Metrics
+  public messagesReceived = 0;
+  public reconnectCount = 0;
+  public lastMessageTime = 0;
+
+  // Pending resolve for subscribe/connect
+  private pendingSubscribe: ((value: void) => void) | null = null;
+  private pendingConnect: ((value: void) => void) | null = null;
+
+  constructor(urlOrOptions?: string | DeepTickStreamOptions) {
+    const opts: DeepTickStreamOptions =
+      typeof urlOrOptions === 'string' ? { url: urlOrOptions } : urlOrOptions ?? {};
+
+    this.url = opts.url ?? 'wss://deeptick.lacertalabs.xyz/v1/stream';
+    this.reconnect = opts.reconnect ?? true;
+    this.reconnectDelay = opts.reconnectDelay ?? 1000;
+    this.reconnectMaxDelay = opts.reconnectMaxDelay ?? 30_000;
+    this.currentDelay = this.reconnectDelay;
+    this.maxQueueSize = opts.maxQueueSize ?? 10_000;
+  }
+
+  // ─── Callback Registration ──────────────────────────────────────
+
+  /** Register callback for trade data */
+  onTrade(cb: DataCallback<StreamTrade>): this {
+    this.tradeCallbacks.push(cb);
+    return this;
+  }
+
+  /** Register callback for native top-of-book ticker data */
+  onBookTicker(cb: DataCallback<StreamBookTicker>): this {
+    this.bookTickerCallbacks.push(cb);
+    return this;
+  }
+
+  /** Deprecated alias for onBookTicker. */
+  onBBO(cb: DataCallback<StreamBookTicker>): this {
+    return this.onBookTicker(cb);
+  }
+
+  /** Register callback for book delta data */
+  onBookDelta(cb: DataCallback<StreamBookDelta>): this {
+    this.bookDeltaCallbacks.push(cb);
+    return this;
+  }
+
+  /** Register callback for derivative ticker data */
+  onDerivativeTicker(cb: DataCallback<StreamDerivativeTicker>): this {
+    this.derivativeTickerCallbacks.push(cb);
+    return this;
+  }
+
+  /** Deprecated alias for onDerivativeTicker. */
+  onFunding(cb: DataCallback<StreamDerivativeTicker>): this {
+    return this.onDerivativeTicker(cb);
+  }
+
+  /** Deprecated alias for onDerivativeTicker. */
+  onOpenInterest(cb: DataCallback<StreamDerivativeTicker>): this {
+    return this.onDerivativeTicker(cb);
+  }
+
+  /** Register callback for liquidation data */
+  onLiquidation(cb: DataCallback): this {
+    this.liquidationCallbacks.push(cb);
+    return this;
+  }
+
+  /** Register callback for ALL data types */
+  onData(cb: DataCallback): this {
+    this.globalCallbacks.push(cb);
+    return this;
+  }
+
+  /** Register callback for connection events */
+  onConnect(cb: () => void): this {
+    this.connectCallbacks.push(cb);
+    return this;
+  }
+
+  /** Register callback for disconnection events */
+  onDisconnect(cb: (reason: string) => void): this {
+    this.disconnectCallbacks.push(cb);
+    return this;
+  }
+
+  /** Register callback for errors */
+  onError(cb: (error: Error) => void): this {
+    this.errorCallbacks.push(cb);
+    return this;
+  }
+
+  // ─── Connection Management ──────────────────────────────────────
+
+  /** Connect to the DeepTick streaming endpoint */
+  async connect(): Promise<void> {
+    this.stopped = false;
+
+    return new Promise((resolve, reject) => {
+      try {
+        // Use browser WebSocket or Node.js ws
+        this.ws = new WebSocket(this.url);
+
+        this.ws.onopen = () => {
+          // Wait for welcome message before resolving
+          this.pendingConnect = resolve;
+        };
+
+        this.ws.onmessage = (event: MessageEvent) => {
+          this.handleMessage(event.data as string);
+        };
+
+        this.ws.onclose = (event: CloseEvent) => {
+          const reason = event.reason || `code ${event.code}`;
+          this.connected = false;
+          this.disconnectCallbacks.forEach(cb => cb(reason));
+
+          if (this.reconnect && !this.stopped) {
+            this.scheduleReconnect();
+          }
+        };
+
+        this.ws.onerror = (event: Event) => {
+          const error = new Error('WebSocket error');
+          this.errorCallbacks.forEach(cb => cb(error));
+          if (!this.connected) {
+            reject(error);
+          }
+        };
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+
+  /** Disconnect from the streaming endpoint */
+  disconnect(): void {
+    this.stopped = true;
+    this.connected = false;
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  /** Subscribe to data channels */
+  async subscribe(channels: string[]): Promise<void> {
+    this.channels = channels;
+    if (!this.connected || !this.ws) {
+      throw new Error('Not connected. Call connect() first.');
+    }
+
+    return new Promise<void>((resolve) => {
+      this.pendingSubscribe = resolve;
+      this.ws!.send(JSON.stringify({
+        action: 'subscribe',
+        channels,
+      }));
+    });
+  }
+
+  /** Unsubscribe from specific channels */
+  unsubscribe(channels: string[]): void {
+    this.channels = this.channels.filter(c => !channels.includes(c));
+    if (this.connected && this.ws) {
+      this.ws.send(JSON.stringify({
+        action: 'unsubscribe',
+        channels,
+      }));
+    }
+  }
+
+  /** Send ping and measure round-trip latency (ms) */
+  async ping(): Promise<number> {
+    if (!this.connected || !this.ws) {
+      throw new Error('Not connected');
+    }
+
+    const t0 = Date.now();
+    return new Promise<number>((resolve) => {
+      const handler = (event: MessageEvent) => {
+        const frame = JSON.parse(event.data as string) as StreamFrame;
+        if (frame.type === 'pong') {
+          this.ws?.removeEventListener('message', handler as any);
+          resolve(Date.now() - t0);
+        }
+      };
+      this.ws!.addEventListener('message', handler as any);
+      this.ws!.send(JSON.stringify({
+        action: 'ping',
+        ts: t0 * 1_000_000,  // ns
+      }));
+    });
+  }
+
+  /** Get streaming client statistics */
+  getStats(): {
+    connected: boolean;
+    connectionId: string | null;
+    url: string;
+    channels: string[];
+    messagesReceived: number;
+    reconnectCount: number;
+    lastMessageAgeMs: number;
+  } {
+    return {
+      connected: this.connected,
+      connectionId: this.connectionId,
+      url: this.url,
+      channels: this.channels,
+      messagesReceived: this.messagesReceived,
+      reconnectCount: this.reconnectCount,
+      lastMessageAgeMs: this.lastMessageTime > 0
+        ? Date.now() - this.lastMessageTime
+        : -1,
+    };
+  }
+
+  // ─── Internal ───────────────────────────────────────────────────
+
+  private handleMessage(raw: string): void {
+    let frame: StreamFrame;
+    try {
+      frame = JSON.parse(raw);
+    } catch {
+      return;
+    }
+
+    this.messagesReceived++;
+    this.lastMessageTime = Date.now();
+
+    switch (frame.type) {
+      case 'welcome':
+        this.connectionId = frame.connection_id ?? null;
+        this.connected = true;
+        this.currentDelay = this.reconnectDelay;
+        this.connectCallbacks.forEach(cb => cb());
+        // Resolve pending connect promise
+        if (this.pendingConnect) {
+          this.pendingConnect();
+          this.pendingConnect = null;
+        }
+        // Resubscribe on reconnect
+        if (this.channels.length > 0) {
+          this.ws?.send(JSON.stringify({
+            action: 'subscribe',
+            channels: this.channels,
+          }));
+        }
+        break;
+
+      case 'subscribed':
+        if (this.pendingSubscribe) {
+          this.pendingSubscribe();
+          this.pendingSubscribe = null;
+        }
+        break;
+
+      case 'data':
+        this.dispatchData(frame.topic ?? '', frame.data ?? {});
+        break;
+
+      case 'heartbeat':
+        // Connection alive
+        break;
+
+      case 'error':
+        const error = new Error(frame.message ?? 'Unknown server error');
+        this.errorCallbacks.forEach(cb => cb(error));
+        break;
+    }
+  }
+
+  private dispatchData(topic: string, data: Record<string, any>): void {
+    // Parse topic: "exchange.data_type.symbol"
+    const parts = topic.split('.', 3);
+    if (parts.length < 3) return;
+
+    const [exchange, dataType, symbol] = parts;
+
+    // Route to type-specific callbacks
+    switch (dataType) {
+      case 'trades':
+        this.tradeCallbacks.forEach(cb => cb(exchange, symbol, data as StreamTrade));
+        break;
+      case 'book_ticker':
+        this.bookTickerCallbacks.forEach(cb => cb(exchange, symbol, data as StreamBookTicker));
+        break;
+      case 'book_l2_delta':
+        this.bookDeltaCallbacks.forEach(cb => cb(exchange, symbol, data as StreamBookDelta));
+        break;
+      case 'derivative_ticker':
+        this.derivativeTickerCallbacks.forEach(cb => cb(exchange, symbol, data as StreamDerivativeTicker));
+        break;
+      case 'liquidations':
+        this.liquidationCallbacks.forEach(cb => cb(exchange, symbol, data));
+        break;
+    }
+
+    // Global callbacks
+    this.globalCallbacks.forEach(cb => cb(exchange, symbol, data));
+  }
+
+  private scheduleReconnect(): void {
+    this.reconnectCount++;
+    console.log(
+      `[deeptick] Reconnecting in ${this.currentDelay}ms (attempt #${this.reconnectCount})`
+    );
+
+    setTimeout(async () => {
+      try {
+        await this.connect();
+      } catch {
+        // connect() failed, onclose will fire and trigger another retry
+      }
+    }, this.currentDelay);
+
+    this.currentDelay = Math.min(this.currentDelay * 2, this.reconnectMaxDelay);
+  }
+}
+
+// ─── Re-export types from types.ts ──────────────────────────────────
+export type { TradeRecord, BBORecord, BookDeltaRecord, CandleRecord } from './types.js';

package/src/types.ts

@@ -0,0 +1,246 @@
+/**
+ * DeepTick TypeScript Client — Derived Data Computations
+ * 
+ * All derived data types are computed client-side from raw Phase 1 data.
+ * Uses Apache Arrow JS for zero-copy Parquet reads.
+ * 
+ * Install: npm install @deeptick/client apache-arrow parquet-wasm
+ * 
+ * Usage:
+ *   import { DeepTick, derive } from '@deeptick/client';
+ * 
+ *   const dt = new DeepTick({ dataDir: './data/merged' });
+ *   const trades = await dt.loadTrades('hyperliquid', 'BTC', '2026-05-01');
+ *   const candles = derive.candles(trades, { intervalMs: 60_000 });
+ *   const bbo = derive.bbo(await dt.loadBookDeltas('hyperliquid', 'BTC', '2026-05-01'));
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+export interface TradeRecord {
+  timestamp: bigint;
+  local_timestamp: bigint;
+  price: number;
+  amount: number;
+  side: 'buy' | 'sell';
+  trade_id: string;
+}
+
+export interface BookDeltaRecord {
+  timestamp: bigint;
+  local_timestamp: bigint;
+  is_snapshot: boolean;
+  bids_packed: Uint8Array;  // binary-packed float64 pairs
+  asks_packed: Uint8Array;
+  bid_count: number;
+  ask_count: number;
+  sequence: bigint | null;
+}
+
+export interface BBORecord {
+  timestamp: bigint;
+  local_timestamp: bigint;
+  bid_price: number;
+  bid_amount: number;
+  ask_price: number;
+  ask_amount: number;
+}
+
+export interface CandleRecord {
+  timestamp: bigint;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume: number;
+  buy_volume: number;
+  sell_volume: number;
+  trades_count: number;
+  vwap: number;
+}
+
+export interface BookSnapshot {
+  timestamp: bigint;
+  local_timestamp: bigint;
+  bids: [number, number][];  // [price, amount][]
+  asks: [number, number][];
+  bid_depth: number;
+  ask_depth: number;
+}
+
+export interface VolumeProfileBucket {
+  price_level: number;
+  volume: number;
+  buy_volume: number;
+  sell_volume: number;
+  trade_count: number;
+}
+
+export interface ImbalanceRecord {
+  timestamp: bigint;
+  imbalance: number;  // -1.0 to +1.0
+  bid_volume: number;
+  ask_volume: number;
+}
+
+export interface FundingCrossRecord {
+  timestamp: bigint;
+  rates: Record<string, number>;           // exchange → rate
+  spreads: Record<string, number>;         // "exA_vs_exB" → spread
+  annualized_spreads: Record<string, number>; // annualized %
+}
+
+// ─── Derived Data Functions ─────────────────────────────────────────
+// All functions are pure: raw data in → derived data out. Nothing stored.
+
+export namespace derive {
+  /**
+   * Derive BBO time series from L2 book deltas.
+   * Replays delta stream maintaining full book state.
+   */
+  export function bbo(deltas: BookDeltaRecord[]): BBORecord[] {
+    const bids = new Map<number, number>();
+    const asks = new Map<number, number>();
+    const result: BBORecord[] = [];
+
+    for (const d of deltas) {
+      const bidsRaw = unpackLevels(d.bids_packed);
+      const asksRaw = unpackLevels(d.asks_packed);
+
+      if (d.is_snapshot) {
+        bids.clear();
+        asks.clear();
+        for (const [p, s] of bidsRaw) {
+          if (s > 0) bids.set(p, s);
+        }
+        for (const [p, s] of asksRaw) {
+          if (s > 0) asks.set(p, s);
+        }
+      } else {
+        for (const [p, s] of bidsRaw) {
+          if (s > 0) {
+            bids.set(p, s);
+          } else {
+            bids.delete(p);
+          }
+        }
+        for (const [p, s] of asksRaw) {
+          if (s > 0) {
+            asks.set(p, s);
+          } else {
+            asks.delete(p);
+          }
+        }
+      }
+
+      if (bids.size > 0 && asks.size > 0) {
+        let bestBidPx = -Infinity;
+        let bestBidSz = 0;
+        for (const [p, s] of bids.entries()) {
+          if (p > bestBidPx) {
+            bestBidPx = p;
+            bestBidSz = s;
+          }
+        }
+
+        let bestAskPx = Infinity;
+        let bestAskSz = 0;
+        for (const [p, s] of asks.entries()) {
+          if (p < bestAskPx) {
+            bestAskPx = p;
+            bestAskSz = s;
+          }
+        }
+
+        if (bestBidPx !== -Infinity && bestAskPx !== Infinity) {
+          result.push({
+            timestamp: d.timestamp,
+            local_timestamp: d.local_timestamp,
+            bid_price: bestBidPx,
+            bid_amount: bestBidSz,
+            ask_price: bestAskPx,
+            ask_amount: bestAskSz,
+          });
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Derive periodic L2 snapshots from delta stream.
+   * @param depth - 20 for standard, 1000 for deep book
+   * @param intervalMs - snapshot interval (default: 60000 = 1 min)
+   */
+  export function bookSnapshots(
+    deltas: BookDeltaRecord[],
+    options?: { depth?: number; intervalMs?: number }
+  ): BookSnapshot[] {
+    throw new Error("Not implemented yet. Feel free to contribute!");
+  }
+
+  /**
+   * Derive OHLCV candles from trades at any interval.
+   * Includes VWAP and buy/sell volume split.
+   */
+  export function candles(
+    trades: TradeRecord[],
+    options?: { intervalMs?: number }
+  ): CandleRecord[] {
+    throw new Error("Not implemented yet. Feel free to contribute!");
+  }
+
+  /**
+   * Derive volume profile from trades.
+   * @param priceBucketSize - auto-calculated if not provided
+   */
+  export function volumeProfile(
+    trades: TradeRecord[],
+    options?: { priceBucketSize?: number; numBuckets?: number }
+  ): VolumeProfileBucket[] {
+    throw new Error("Not implemented yet. Feel free to contribute!");
+  }
+
+  /**
+   * Derive order book imbalance from L2 deltas.
+   * imbalance = (bid_vol - ask_vol) / (bid_vol + ask_vol) at top N levels
+   */
+  export function bookImbalance(
+    deltas: BookDeltaRecord[],
+    options?: { depth?: number; intervalMs?: number }
+  ): ImbalanceRecord[] {
+    throw new Error("Not implemented yet. Feel free to contribute!");
+  }
+
+  /**
+   * Derive cross-exchange funding rate spreads.
+   * Takes funding data from multiple exchanges for same underlying.
+   */
+  export function fundingCross(
+    fundingByExchange: Record<string, { timestamp: bigint; funding_rate: number }[]>,
+    options?: { intervalMs?: number }
+  ): FundingCrossRecord[] {
+    throw new Error("Not implemented yet. Feel free to contribute!");
+  }
+
+  /**
+   * Derive cross-exchange basis (price spread in bps).
+   */
+  export function crossExchangeBasis(
+    tradesByExchange: Record<string, TradeRecord[]>,
+    options?: { intervalMs?: number }
+  ): { timestamp: bigint; prices: Record<string, number>; basis_bps: Record<string, number> }[] {
+    throw new Error("Not implemented yet. Feel free to contribute!");
+  }
+}
+
+// ─── Utility: Unpack binary-packed book levels ──────────────────────
+
+export function unpackLevels(packed: Uint8Array): [number, number][] {
+  const view = new DataView(packed.buffer, packed.byteOffset, packed.byteLength);
+  const pairs: [number, number][] = [];
+  for (let i = 0; i < packed.byteLength; i += 16) {
+    pairs.push([view.getFloat64(i, true), view.getFloat64(i + 8, true)]);
+  }
+  return pairs;
+}