@deeptick/client 0.1.1

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@deeptick/client",
+  "version": "0.1.1",
+  "description": "DeepTick TypeScript SDK — high-frequency crypto market data",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./streaming": "./dist/streaming.js",
+    "./feed": "./dist/feed.js",
+    "./cache": "./dist/cache.js",
+    "./types": "./dist/types.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/ws": "^8.5.12",
+    "@types/node": "^22.0.0"
+  },
+  "peerDependencies": {
+    "apache-arrow": ">=15.0.0",
+    "parquet-wasm": ">=0.6.0"
+  },
+  "peerDependenciesMeta": {
+    "apache-arrow": { "optional": true },
+    "parquet-wasm": { "optional": true }
+  },
+  "keywords": [
+    "deeptick",
+    "crypto",
+    "market-data",
+    "order-book",
+    "websocket",
+    "streaming",
+    "parquet",
+    "hft"
+  ],
+  "license": "MIT",
+  "author": "DeepTick",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deeptick/deeptick"
+  }
+}

package/src/cache.ts

@@ -0,0 +1,206 @@
+/**
+ * DeepTick TypeScript Client — Caching + Parallel Downloads.
+ *
+ * Disk-based cache for downloaded data so repeat queries are instant.
+ * Parallel multi-day fetches via Promise.all.
+ *
+ * Usage:
+ *   import { CachedClient } from '@deeptick/client';
+ *
+ *   const client = new CachedClient('https://deeptick.lacertalabs.xyz');
+ *
+ *   // First call: downloads from server, caches locally
+ *   const trades = await client.loadTrades('hyperliquid', 'BTC', '2026-05-01', '2026-05-07');
+ *
+ *   // Second call: instant from disk cache
+ *   const trades2 = await client.loadTrades('hyperliquid', 'BTC', '2026-05-01', '2026-05-07');
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as crypto from 'crypto';
+
+export interface CacheStats {
+  cacheDir: string;
+  cacheHits: number;
+  cacheMisses: number;
+  hitRatePct: number;
+  bytesDownloaded: number;
+  bytesFromCache: number;
+}
+
+export class CachedClient {
+  private baseUrl: string;
+  private cacheDir: string;
+  private maxConcurrency: number;
+  private apiKey: string;
+
+  cacheHits = 0;
+  cacheMisses = 0;
+  bytesDownloaded = 0;
+  bytesFromCache = 0;
+
+  constructor(
+    baseUrl: string = 'https://deeptick.lacertalabs.xyz',
+    cacheDir?: string,
+    maxConcurrency: number = 8,
+    apiKey: string = process.env.DEEPTICK_API_KEY ?? '',
+  ) {
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.cacheDir = cacheDir || path.join(os.homedir(), '.deeptick', 'cache');
+    this.maxConcurrency = maxConcurrency;
+    this.apiKey = apiKey;
+    fs.mkdirSync(this.cacheDir, { recursive: true });
+  }
+
+  // ─── Cache Key ────────────────────────────────────────────────────
+
+  private cachePath(
+    exchange: string, dataType: string, symbol: string, date: string,
+    columns?: string[],
+  ): string {
+    const safeSymbol = symbol.replace(/\//g, '-').replace(/:/g, '-');
+    let colHash = '';
+    if (columns && columns.length > 0) {
+      const sorted = [...columns].sort().join(',');
+      colHash = '_' + crypto.createHash('md5').update(sorted).digest('hex').slice(0, 8);
+    }
+    return path.join(
+      this.cacheDir, exchange, dataType, safeSymbol,
+      `${date}${colHash}.bin`,
+    );
+  }
+
+  private isCached(filePath: string): boolean {
+    return fs.existsSync(filePath);
+  }
+
+  // ─── Download ─────────────────────────────────────────────────────
+
+  private async downloadDate(
+    exchange: string, dataType: string, symbol: string, date: string,
+    columns?: string[], format: string = 'csv',
+  ): Promise<string | null> {
+    const cp = this.cachePath(exchange, dataType, symbol, date, columns);
+
+    if (this.isCached(cp)) {
+      this.cacheHits++;
+      this.bytesFromCache += fs.statSync(cp).size;
+      return fs.readFileSync(cp, 'utf-8');
+    }
+
+    this.cacheMisses++;
+
+    let url = `${this.baseUrl}/v1/data/${exchange}/${dataType}/${symbol}/${date}?format=${format}`;
+    if (columns && columns.length > 0) {
+      url += `&columns=${columns.join(',')}`;
+    }
+
+    try {
+      const headers: Record<string, string> = {};
+      if (this.apiKey) {
+        headers['X-API-Key'] = this.apiKey;
+      }
+      const resp = await fetch(url, { headers });
+      if (!resp.ok) {
+        if (resp.status === 404) return null;
+        throw new Error(`HTTP ${resp.status}`);
+      }
+
+      const data = await resp.text();
+      this.bytesDownloaded += Buffer.byteLength(data);
+
+      // Cache to disk
+      const dir = path.dirname(cp);
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(cp, data);
+
+      return data;
+    } catch (err) {
+      console.error(`[cache] Download error for ${exchange}/${dataType}/${symbol}/${date}:`, err);
+      return null;
+    }
+  }
+
+  // ─── Parallel Multi-Day Loader ────────────────────────────────────
+
+  private dateRange(start: string, end: string): string[] {
+    const dates: string[] = [];
+    const current = new Date(start + 'T00:00:00Z');
+    const endDate = new Date(end + 'T00:00:00Z');
+
+    while (current <= endDate) {
+      dates.push(current.toISOString().split('T')[0]);
+      current.setUTCDate(current.getUTCDate() + 1);
+    }
+    return dates;
+  }
+
+  async load(
+    dataType: string,
+    exchange: string,
+    symbol: string,
+    startDate: string,
+    endDate?: string,
+    columns?: string[],
+  ): Promise<string[]> {
+    const end = endDate || startDate;
+    const dates = this.dateRange(startDate, end);
+
+    // Parallel download with concurrency limit
+    const results: (string | null)[] = [];
+    for (let i = 0; i < dates.length; i += this.maxConcurrency) {
+      const batch = dates.slice(i, i + this.maxConcurrency);
+      const batchResults = await Promise.all(
+        batch.map(d => this.downloadDate(exchange, dataType, symbol, d, columns)),
+      );
+      results.push(...batchResults);
+    }
+
+    return results.filter((r): r is string => r !== null);
+  }
+
+  async loadTrades(
+    exchange: string, symbol: string, startDate: string, endDate?: string,
+  ): Promise<string[]> {
+    return this.load('trades', exchange, symbol, startDate, endDate);
+  }
+
+  async loadBookDeltas(
+    exchange: string, symbol: string, startDate: string, endDate?: string,
+  ): Promise<string[]> {
+    return this.load('book_l2_delta', exchange, symbol, startDate, endDate);
+  }
+
+  async loadDerivativeTicker(
+    exchange: string, symbol: string, startDate: string, endDate?: string,
+  ): Promise<string[]> {
+    return this.load('derivative_ticker', exchange, symbol, startDate, endDate);
+  }
+
+  async loadFunding(
+    exchange: string, symbol: string, startDate: string, endDate?: string,
+  ): Promise<string[]> {
+    return this.loadDerivativeTicker(exchange, symbol, startDate, endDate);
+  }
+
+  // ─── Cache Management ────────────────────────────────────────────
+
+  getStats(): CacheStats {
+    const total = this.cacheHits + this.cacheMisses;
+    return {
+      cacheDir: this.cacheDir,
+      cacheHits: this.cacheHits,
+      cacheMisses: this.cacheMisses,
+      hitRatePct: total > 0 ? Math.round((this.cacheHits / total) * 1000) / 10 : 0,
+      bytesDownloaded: this.bytesDownloaded,
+      bytesFromCache: this.bytesFromCache,
+    };
+  }
+
+  clearCache(): void {
+    fs.rmSync(this.cacheDir, { recursive: true, force: true });
+    fs.mkdirSync(this.cacheDir, { recursive: true });
+  }
+}

package/src/feed.ts

@@ -0,0 +1,290 @@
+/**
+ * DeepTick TypeScript Unified Feed — Seamless Live ↔ Replay switching.
+ *
+ * Same interface for both live streaming and historical replay.
+ * Backtest code = production code.
+ *
+ * Usage:
+ *   import { DeepTickFeed, FeedMode } from '@deeptick/client';
+ *
+ *   // Live mode
+ *   const feed = DeepTickFeed.live('wss://deeptick.lacertalabs.xyz/v1/stream');
+ *   feed.onData((topic, data) => console.log(topic, data));
+ *   await feed.connect();
+ *   await feed.subscribe(['hyperliquid.trades.BTC']);
+ *
+ *   // Replay mode — same callback, historical data
+ *   const feed = DeepTickFeed.replay('wss://deeptick.lacertalabs.xyz/v1/replay/ws', {
+ *     sources: ['hyperliquid:trades:BTC'],
+ *     from: '2026-05-01',
+ *     to: '2026-05-03',
+ *     speed: 10,
+ *   });
+ *   feed.onData((topic, data) => console.log(topic, data)); // Same handler!
+ *   await feed.connect();
+ *
+ *   // Auto mode — replay then switch to live
+ *   const feed = DeepTickFeed.auto('wss://deeptick.lacertalabs.xyz', {
+ *     sources: ['hyperliquid:trades:BTC'],
+ *     from: '2026-05-01',
+ *   });
+ */
+
+import WebSocket from 'ws';
+
+export enum FeedMode {
+  LIVE = 'live',
+  REPLAY = 'replay',
+  AUTO = 'auto',
+}
+
+export interface FeedOptions {
+  channels?: string[];
+  sources?: string[];
+  from?: string;
+  to?: string;
+  speed?: number;
+  reconnect?: boolean;
+  apiKey?: string;
+}
+
+export interface FeedStats {
+  mode: FeedMode;
+  currentMode: FeedMode;
+  messagesReceived: number;
+  connected: boolean;
+  url: string;
+}
+
+type DataCallback = (topic: string, data: Record<string, any>) => void;
+type ReplayEndCallback = (stats: { totalEvents: number; durationS: number }) => void;
+type ModeChangeCallback = (from: FeedMode, to: FeedMode) => void;
+
+export class DeepTickFeed {
+  private mode: FeedMode;
+  private currentMode: FeedMode;
+  private url: string;
+  private options: FeedOptions;
+  private ws: WebSocket | null = null;
+  private messagesReceived = 0;
+  private connected = false;
+
+  private dataCallbacks: DataCallback[] = [];
+  private replayEndCallbacks: ReplayEndCallback[] = [];
+  private modeChangeCallbacks: ModeChangeCallback[] = [];
+
+  private constructor(mode: FeedMode, url: string, options: FeedOptions = {}) {
+    this.mode = mode;
+    this.currentMode = mode;
+    this.url = url;
+    this.options = options;
+  }
+
+  // ─── Factory Methods ─────────────────────────────────────────────
+
+  static live(url: string = 'wss://deeptick.lacertalabs.xyz/v1/stream', options: FeedOptions = {}): DeepTickFeed {
+    return new DeepTickFeed(FeedMode.LIVE, url, options);
+  }
+
+  static replay(url: string = 'wss://deeptick.lacertalabs.xyz/v1/replay/ws', options: FeedOptions = {}): DeepTickFeed {
+    return new DeepTickFeed(FeedMode.REPLAY, url, options);
+  }
+
+  static auto(baseUrl: string = 'wss://deeptick.lacertalabs.xyz', options: FeedOptions = {}): DeepTickFeed {
+    const today = new Date().toISOString().split('T')[0];
+    return new DeepTickFeed(FeedMode.AUTO, `${baseUrl}/v1/replay/ws`, {
+      ...options,
+      to: today,
+    });
+  }
+
+  // ─── Callbacks ───────────────────────────────────────────────────
+
+  /** Register a callback for data events (works identically for live and replay) */
+  onData(cb: DataCallback): this {
+    this.dataCallbacks.push(cb);
+    return this;
+  }
+
+  /** Register a callback for replay completion */
+  onReplayEnd(cb: ReplayEndCallback): this {
+    this.replayEndCallbacks.push(cb);
+    return this;
+  }
+
+  /** Register a callback for mode changes (replay → live in auto mode) */
+  onModeChange(cb: ModeChangeCallback): this {
+    this.modeChangeCallbacks.push(cb);
+    return this;
+  }
+
+  // ─── Connection ──────────────────────────────────────────────────
+
+  async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const urlWithKey = this.options.apiKey
+        ? `${this.url}?api_key=${this.options.apiKey}`
+        : this.url;
+
+      this.ws = new WebSocket(urlWithKey);
+
+      this.ws.on('open', () => {
+        this.connected = true;
+      });
+
+      this.ws.on('message', (raw: WebSocket.Data) => {
+        const frame = JSON.parse(raw.toString());
+        this.messagesReceived++;
+
+        switch (frame.type) {
+          case 'welcome':
+            // Start feed based on mode
+            if (this.mode === FeedMode.LIVE) {
+              this.startLive();
+            } else {
+              this.startReplay();
+            }
+            resolve();
+            break;
+
+          case 'data':
+            for (const cb of this.dataCallbacks) {
+              cb(frame.topic, frame.data);
+            }
+            break;
+
+          case 'replay_end':
+            for (const cb of this.replayEndCallbacks) {
+              cb({
+                totalEvents: frame.total_events,
+                durationS: frame.duration_s,
+              });
+            }
+
+            if (this.currentMode === FeedMode.AUTO) {
+              // Switch to live
+              this.switchToLive();
+            }
+            break;
+
+          case 'subscribed':
+          case 'replay_start':
+          case 'heartbeat':
+            break;
+
+          case 'error':
+            console.error('[feed] Server error:', frame.message);
+            break;
+        }
+      });
+
+      this.ws.on('close', () => {
+        this.connected = false;
+      });
+
+      this.ws.on('error', (err) => {
+        if (!this.connected) {
+          reject(err);
+        }
+      });
+    });
+  }
+
+  async disconnect(): Promise<void> {
+    this.connected = false;
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  async subscribe(channels: string[]): Promise<void> {
+    this.options.channels = channels;
+    if (this.connected && this.currentMode === FeedMode.LIVE && this.ws) {
+      this.ws.send(JSON.stringify({ action: 'subscribe', channels }));
+    }
+  }
+
+  // ─── Internal ────────────────────────────────────────────────────
+
+  private startLive(): void {
+    if (this.options.channels && this.ws) {
+      this.ws.send(JSON.stringify({
+        action: 'subscribe',
+        channels: this.options.channels,
+      }));
+    }
+    this.currentMode = FeedMode.LIVE;
+  }
+
+  private startReplay(): void {
+    if (this.ws) {
+      this.ws.send(JSON.stringify({
+        action: 'replay',
+        sources: this.options.sources || [],
+        from: this.options.from || '',
+        to: this.options.to || '',
+        speed: this.options.speed || 0,
+      }));
+    }
+    this.currentMode = FeedMode.REPLAY;
+  }
+
+  private async switchToLive(): Promise<void> {
+    const oldMode = this.currentMode;
+
+    // Close replay connection
+    if (this.ws) {
+      this.ws.close();
+    }
+
+    // Connect to live endpoint
+    const liveUrl = this.url.replace('/v1/replay/ws', '/v1/stream');
+    const urlWithKey = this.options.apiKey
+      ? `${liveUrl}?api_key=${this.options.apiKey}`
+      : liveUrl;
+
+    return new Promise((resolve) => {
+      this.ws = new WebSocket(urlWithKey);
+
+      this.ws.on('open', () => {
+        this.connected = true;
+      });
+
+      this.ws.on('message', (raw: WebSocket.Data) => {
+        const frame = JSON.parse(raw.toString());
+        this.messagesReceived++;
+
+        if (frame.type === 'welcome') {
+          // Build channels from sources
+          if (!this.options.channels && this.options.sources) {
+            this.options.channels = this.options.sources.map(s => s.replace(/:/g, '.'));
+          }
+          this.startLive();
+          for (const cb of this.modeChangeCallbacks) {
+            cb(oldMode, FeedMode.LIVE);
+          }
+          resolve();
+        } else if (frame.type === 'data') {
+          for (const cb of this.dataCallbacks) {
+            cb(frame.topic, frame.data);
+          }
+        }
+      });
+
+      this.ws.on('close', () => {
+        this.connected = false;
+      });
+    });
+  }
+
+  getStats(): FeedStats {
+    return {
+      mode: this.mode,
+      currentMode: this.currentMode,
+      messagesReceived: this.messagesReceived,
+      connected: this.connected,
+      url: this.url,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @deeptick/client — TypeScript SDK for DeepTick market data
+ *
+ * Three layers:
+ *   1. CachedClient  — Download + cache daily archives
+ *   2. DeepTickStream — Real-time WebSocket streaming
+ *   3. DeepTickFeed   — Unified live/replay feed
+ *   4. derive         — Client-side derived computations
+ *
+ * Usage:
+ *   import { DeepTickStream } from '@deeptick/client';
+ *   import { CachedClient } from '@deeptick/client/cache';
+ *   import { DeepTickFeed } from '@deeptick/client/feed';
+ *   import { derive } from '@deeptick/client/types';
+ */
+
+// Re-export everything
+export { DeepTickStream } from './streaming.js';
+export type {
+  StreamFrame,
+  StreamTrade,
+  StreamBookTicker,
+  StreamBookDelta,
+  StreamDerivativeTicker,
+  DataCallback,
+  DeepTickStreamOptions,
+} from './streaming.js';
+
+export { DeepTickFeed, FeedMode } from './feed.js';
+export type { FeedOptions, FeedStats } from './feed.js';
+
+export { CachedClient } from './cache.js';
+export type { CacheStats } from './cache.js';
+
+export { derive, unpackLevels } from './types.js';
+export type {
+  TradeRecord,
+  BookDeltaRecord,
+  BBORecord,
+  CandleRecord,
+  BookSnapshot,
+  VolumeProfileBucket,
+  ImbalanceRecord,
+  FundingCrossRecord,
+} from './types.js';