@deeptick/client 0.1.1

package/README.md

@@ -0,0 +1,225 @@
+# DeepTick TypeScript SDK
+
+> `npm install @deeptick/client`
+
+The TypeScript SDK provides three layers of access to DeepTick market data:
+
+1. **CachedClient** — Download daily Parquet/CSV archives with local disk caching
+2. **DeepTickStream** — Real-time WebSocket streaming with typed callbacks
+3. **DeepTickFeed** — Unified live/replay feed (backtest code = production code)
+4. **Types & Derive** — Full type definitions and client-side derived computations
+
+## Quick Start
+
+```typescript
+import { CachedClient } from '@deeptick/client/cache';
+
+const client = new CachedClient("https://api.deeptick.com");
+
+// Load BTC trades for a date range (cached after first download)
+const batches = await client.loadTrades(
+  "binance_futures",
+  "BTCUSDT",
+  "2026-05-01",
+  "2026-05-02"
+);
+console.log(`Loaded ${batches.length} daily files.`);
+console.log(client.getStats());
+```
+
+## Streaming (Real-Time)
+
+```typescript
+import { DeepTickStream } from '@deeptick/client/streaming';
+
+const stream = new DeepTickStream({
+  url: "wss://api.deeptick.com/v1/stream?api_key=dtk_your_key"
+});
+
+// Typed callbacks for each data type
+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}`);
+});
+
+stream.onDerivativeTicker((exchange, symbol, data) => {
+  console.log(`[${exchange}] ${symbol} funding: ${data.funding_rate}`);
+});
+
+// Connect and subscribe
+await stream.connect();
+await stream.subscribe([
+  "binance_futures.trades.BTCUSDT",
+  "*.book_ticker.*",
+  "*.derivative_ticker.*",
+]);
+
+// Measure latency
+const latency = await stream.ping();
+console.log(`Round-trip: ${latency}ms`);
+```
+
+### Global Callback
+
+```typescript
+stream.onData((exchange, symbol, data) => {
+  // Receives ALL data types
+  console.log(exchange, symbol, data);
+});
+```
+
+## Replay (Historical Tick-by-Tick)
+
+```typescript
+import { DeepTickFeed } from '@deeptick/client/feed';
+
+const feed = DeepTickFeed.replay(
+  "wss://api.deeptick.com/v1/replay/ws",
+  {
+    apiKey: "dtk_your_key",
+    sources: [
+      "binance_futures:trades:BTCUSDT",
+      "binance_futures:book_l2_delta:BTCUSDT",
+    ],
+    from: "2026-05-01",
+    to: "2026-05-02",
+    speed: 0, // max speed
+  }
+);
+
+feed.onData((topic, data) => console.log(topic, data));
+feed.onReplayEnd((stats) => {
+  console.log(`Replay complete: ${stats.totalEvents} events in ${stats.durationS}s`);
+});
+
+await feed.connect();
+```
+
+### Auto Mode (Replay → Live)
+
+```typescript
+const feed = DeepTickFeed.auto(
+  "wss://api.deeptick.com",
+  {
+    apiKey: "dtk_your_key",
+    sources: ["hyperliquid:trades:BTC"],
+    from: "2026-05-01", // replay from here, then switch to live
+  }
+);
+
+feed.onData((topic, data) => process(data)); // same handler!
+feed.onModeChange((from, to) => {
+  console.log(`Switched from ${from} to ${to}`);
+});
+
+await feed.connect();
+```
+
+## Derived Data (Computed On-the-Fly)
+
+```typescript
+import { CachedClient } from '@deeptick/client/cache';
+import { derive, unpackLevels } from '@deeptick/client/types';
+import type {
+  TradeRecord,
+  BookDeltaRecord,
+  BBORecord,
+  CandleRecord,
+  BookSnapshot,
+  ImbalanceRecord,
+  VolumeProfileBucket,
+} from '@deeptick/client/types';
+
+const client = new CachedClient("https://api.deeptick.com");
+
+// ── BBO from L2 deltas ──────────────────────────────────────────────
+const deltas = await client.loadBookDeltas("binance_futures", "BTCUSDT", "2026-05-01");
+const bbo: BBORecord[] = derive.bbo(deltas);
+console.log(`BBO rows: ${bbo.length}`);
+
+// ── Candles at any interval ─────────────────────────────────────────
+const trades = await client.loadTrades("binance_futures", "BTCUSDT", "2026-05-01");
+const candles1m: CandleRecord[] = derive.candles(trades, { intervalMs: 60_000 });
+const candles5m: CandleRecord[] = derive.candles(trades, { intervalMs: 300_000 });
+
+// ── Book snapshots (20 levels every 1 min) ──────────────────────────
+const snapshots: BookSnapshot[] = derive.bookSnapshots(deltas, {
+  depth: 20,
+  intervalMs: 60_000,
+});
+
+// ── Volume profile ──────────────────────────────────────────────────
+const profile: VolumeProfileBucket[] = derive.volumeProfile(trades, {
+  numBuckets: 100,
+});
+
+// ── Order book imbalance ────────────────────────────────────────────
+const imbalance: ImbalanceRecord[] = derive.bookImbalance(deltas, {
+  depth: 5,
+  intervalMs: 1000,
+});
+
+// ── Cross-exchange funding spread ───────────────────────────────────
+const hlFunding = await client.loadFunding("hyperliquid", "BTC", "2026-05-01");
+const bnFunding = await client.loadFunding("binance_futures", "BTCUSDT", "2026-05-01");
+const fundingCross = derive.fundingCross(
+  { hyperliquid: hlFunding, binance_futures: bnFunding },
+  { intervalMs: 3_600_000 }
+);
+
+// ── Cross-exchange basis ────────────────────────────────────────────
+const hlTrades = await client.loadTrades("hyperliquid", "BTC", "2026-05-01");
+const bnTrades = await client.loadTrades("binance_futures", "BTCUSDT", "2026-05-01");
+const basis = derive.crossExchangeBasis(
+  { hyperliquid: hlTrades, binance_futures: bnTrades },
+  { intervalMs: 1000 }
+);
+
+// ── Unpack binary book levels ───────────────────────────────────────
+const packed = new Uint8Array(/* from parquet column */);
+const levels: [number, number][] = unpackLevels(packed);
+// levels = [[price1, size1], [price2, size2], ...]
+```
+
+## Type Definitions
+
+```typescript
+// Wire protocol types for streaming
+interface StreamTrade {
+  exchange: string; symbol: string;
+  timestamp: number; local_timestamp: number;
+  trade_id: string; price: number; amount: number;
+  side: 'buy' | 'sell';
+}
+
+interface StreamBookTicker {
+  exchange: string; symbol: string;
+  timestamp: number; local_timestamp: number;
+  bid_price: number; bid_amount: number;
+  ask_price: number; ask_amount: number;
+}
+
+interface StreamDerivativeTicker {
+  exchange: string; symbol: string;
+  timestamp: number; local_timestamp: number;
+  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;
+}
+```
+
+## Architecture
+
+```
+client-ts/src/
+├── types.ts       # Type definitions + derive namespace (BBO, candles, snapshots)
+├── cache.ts       # CachedClient — HTTP download + disk cache
+├── streaming.ts   # DeepTickStream — real-time WebSocket (Node + Browser)
+└── feed.ts        # DeepTickFeed — unified live/replay feed
+```

package/dist/cache.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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');
+ */
+export interface CacheStats {
+    cacheDir: string;
+    cacheHits: number;
+    cacheMisses: number;
+    hitRatePct: number;
+    bytesDownloaded: number;
+    bytesFromCache: number;
+}
+export declare class CachedClient {
+    private baseUrl;
+    private cacheDir;
+    private maxConcurrency;
+    private apiKey;
+    cacheHits: number;
+    cacheMisses: number;
+    bytesDownloaded: number;
+    bytesFromCache: number;
+    constructor(baseUrl?: string, cacheDir?: string, maxConcurrency?: number, apiKey?: string);
+    private cachePath;
+    private isCached;
+    private downloadDate;
+    private dateRange;
+    load(dataType: string, exchange: string, symbol: string, startDate: string, endDate?: string, columns?: string[]): Promise<string[]>;
+    loadTrades(exchange: string, symbol: string, startDate: string, endDate?: string): Promise<string[]>;
+    loadBookDeltas(exchange: string, symbol: string, startDate: string, endDate?: string): Promise<string[]>;
+    loadDerivativeTicker(exchange: string, symbol: string, startDate: string, endDate?: string): Promise<string[]>;
+    loadFunding(exchange: string, symbol: string, startDate: string, endDate?: string): Promise<string[]>;
+    getStats(): CacheStats;
+    clearCache(): void;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAOH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,MAAM,CAAS;IAEvB,SAAS,SAAK;IACd,WAAW,SAAK;IAChB,eAAe,SAAK;IACpB,cAAc,SAAK;gBAGjB,OAAO,GAAE,MAA2C,EACpD,QAAQ,CAAC,EAAE,MAAM,EACjB,cAAc,GAAE,MAAU,EAC1B,MAAM,GAAE,MAA2C;IAWrD,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,QAAQ;YAMF,YAAY;IA+C1B,OAAO,CAAC,SAAS;IAYX,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,MAAM,EAAE,CAAC;IAiBd,UAAU,CACd,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GACpE,OAAO,CAAC,MAAM,EAAE,CAAC;IAId,cAAc,CAClB,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GACpE,OAAO,CAAC,MAAM,EAAE,CAAC;IAId,oBAAoB,CACxB,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GACpE,OAAO,CAAC,MAAM,EAAE,CAAC;IAId,WAAW,CACf,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GACpE,OAAO,CAAC,MAAM,EAAE,CAAC;IAMpB,QAAQ,IAAI,UAAU;IAYtB,UAAU,IAAI,IAAI;CAInB"}

package/dist/cache.js

@@ -0,0 +1,140 @@
+/**
+ * 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 class CachedClient {
+    baseUrl;
+    cacheDir;
+    maxConcurrency;
+    apiKey;
+    cacheHits = 0;
+    cacheMisses = 0;
+    bytesDownloaded = 0;
+    bytesFromCache = 0;
+    constructor(baseUrl = 'https://deeptick.lacertalabs.xyz', cacheDir, maxConcurrency = 8, apiKey = 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 ────────────────────────────────────────────────────
+    cachePath(exchange, dataType, symbol, date, columns) {
+        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`);
+    }
+    isCached(filePath) {
+        return fs.existsSync(filePath);
+    }
+    // ─── Download ─────────────────────────────────────────────────────
+    async downloadDate(exchange, dataType, symbol, date, columns, format = 'csv') {
+        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 = {};
+            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 ────────────────────────────────────
+    dateRange(start, end) {
+        const dates = [];
+        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, exchange, symbol, startDate, endDate, columns) {
+        const end = endDate || startDate;
+        const dates = this.dateRange(startDate, end);
+        // Parallel download with concurrency limit
+        const results = [];
+        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 !== null);
+    }
+    async loadTrades(exchange, symbol, startDate, endDate) {
+        return this.load('trades', exchange, symbol, startDate, endDate);
+    }
+    async loadBookDeltas(exchange, symbol, startDate, endDate) {
+        return this.load('book_l2_delta', exchange, symbol, startDate, endDate);
+    }
+    async loadDerivativeTicker(exchange, symbol, startDate, endDate) {
+        return this.load('derivative_ticker', exchange, symbol, startDate, endDate);
+    }
+    async loadFunding(exchange, symbol, startDate, endDate) {
+        return this.loadDerivativeTicker(exchange, symbol, startDate, endDate);
+    }
+    // ─── Cache Management ────────────────────────────────────────────
+    getStats() {
+        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() {
+        fs.rmSync(this.cacheDir, { recursive: true, force: true });
+        fs.mkdirSync(this.cacheDir, { recursive: true });
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/feed.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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',
+ *   });
+ */
+export declare 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 declare class DeepTickFeed {
+    private mode;
+    private currentMode;
+    private url;
+    private options;
+    private ws;
+    private messagesReceived;
+    private connected;
+    private dataCallbacks;
+    private replayEndCallbacks;
+    private modeChangeCallbacks;
+    private constructor();
+    static live(url?: string, options?: FeedOptions): DeepTickFeed;
+    static replay(url?: string, options?: FeedOptions): DeepTickFeed;
+    static auto(baseUrl?: string, options?: FeedOptions): DeepTickFeed;
+    /** Register a callback for data events (works identically for live and replay) */
+    onData(cb: DataCallback): this;
+    /** Register a callback for replay completion */
+    onReplayEnd(cb: ReplayEndCallback): this;
+    /** Register a callback for mode changes (replay → live in auto mode) */
+    onModeChange(cb: ModeChangeCallback): this;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    subscribe(channels: string[]): Promise<void>;
+    private startLive;
+    private startReplay;
+    private switchToLive;
+    getStats(): FeedStats;
+}
+export {};
+//# sourceMappingURL=feed.d.ts.map

package/dist/feed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feed.d.ts","sourceRoot":"","sources":["../src/feed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,oBAAY,QAAQ;IAClB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,QAAQ,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,KAAK,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;AACvE,KAAK,iBAAiB,GAAG,CAAC,KAAK,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,CAAC;AACrF,KAAK,kBAAkB,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,KAAK,IAAI,CAAC;AAEjE,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAAW;IACvB,OAAO,CAAC,WAAW,CAAW;IAC9B,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,SAAS,CAAS;IAE1B,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,kBAAkB,CAA2B;IACrD,OAAO,CAAC,mBAAmB,CAA4B;IAEvD,OAAO;IASP,MAAM,CAAC,IAAI,CAAC,GAAG,GAAE,MAAmD,EAAE,OAAO,GAAE,WAAgB,GAAG,YAAY;IAI9G,MAAM,CAAC,MAAM,CAAC,GAAG,GAAE,MAAsD,EAAE,OAAO,GAAE,WAAgB,GAAG,YAAY;IAInH,MAAM,CAAC,IAAI,CAAC,OAAO,GAAE,MAAyC,EAAE,OAAO,GAAE,WAAgB,GAAG,YAAY;IAUxG,kFAAkF;IAClF,MAAM,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI;IAK9B,gDAAgD;IAChD,WAAW,CAAC,EAAE,EAAE,iBAAiB,GAAG,IAAI;IAKxC,wEAAwE;IACxE,YAAY,CAAC,EAAE,EAAE,kBAAkB,GAAG,IAAI;IAOpC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAsExB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASlD,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,WAAW;YAaL,YAAY;IAgD1B,QAAQ,IAAI,SAAS;CAStB"}