@0xarchive/sdk 0.5.4 → 0.6.1

package/dist/index.mjs

@@ -682,6 +682,186 @@ var LiquidationsResource = class {
   }
 };
 
+// src/resources/data-quality.ts
+var DataQualityResource = class {
+  constructor(http, basePath = "/v1/data-quality") {
+    this.http = http;
+    this.basePath = basePath;
+  }
+  // ===========================================================================
+  // Status Endpoints
+  // ===========================================================================
+  /**
+   * Get overall system health status
+   *
+   * @returns StatusResponse with overall status, per-exchange status,
+   *          per-data-type status, and active incident count
+   *
+   * @example
+   * ```typescript
+   * const status = await client.dataQuality.status();
+   * console.log(`Overall: ${status.status}`);
+   * for (const [exchange, info] of Object.entries(status.exchanges)) {
+   *   console.log(`${exchange}: ${info.status}`);
+   * }
+   * ```
+   */
+  async status() {
+    return this.http.get(`${this.basePath}/status`);
+  }
+  // ===========================================================================
+  // Coverage Endpoints
+  // ===========================================================================
+  /**
+   * Get data coverage summary for all exchanges
+   *
+   * @returns CoverageResponse with coverage info for all exchanges and data types
+   *
+   * @example
+   * ```typescript
+   * const coverage = await client.dataQuality.coverage();
+   * for (const exchange of coverage.exchanges) {
+   *   console.log(`${exchange.exchange}:`);
+   *   for (const [dtype, info] of Object.entries(exchange.dataTypes)) {
+   *     console.log(`  ${dtype}: ${info.totalRecords} records`);
+   *   }
+   * }
+   * ```
+   */
+  async coverage() {
+    return this.http.get(`${this.basePath}/coverage`);
+  }
+  /**
+   * Get data coverage for a specific exchange
+   *
+   * @param exchange - Exchange name ('hyperliquid' or 'lighter')
+   * @returns ExchangeCoverage with coverage info for all data types on this exchange
+   *
+   * @example
+   * ```typescript
+   * const hl = await client.dataQuality.exchangeCoverage('hyperliquid');
+   * console.log(`Orderbook earliest: ${hl.dataTypes.orderbook.earliest}`);
+   * ```
+   */
+  async exchangeCoverage(exchange) {
+    return this.http.get(
+      `${this.basePath}/coverage/${exchange.toLowerCase()}`
+    );
+  }
+  /**
+   * Get data coverage for a specific symbol on an exchange
+   *
+   * Includes gap detection showing periods where data may be missing.
+   *
+   * @param exchange - Exchange name ('hyperliquid' or 'lighter')
+   * @param symbol - Symbol name (e.g., 'BTC', 'ETH')
+   * @returns SymbolCoverageResponse with per-data-type coverage including gaps
+   *
+   * @example
+   * ```typescript
+   * const btc = await client.dataQuality.symbolCoverage('hyperliquid', 'BTC');
+   * const oi = btc.dataTypes.open_interest;
+   * console.log(`OI completeness: ${oi.completeness}%`);
+   * console.log(`Gaps found: ${oi.gaps.length}`);
+   * for (const gap of oi.gaps.slice(0, 3)) {
+   *   console.log(`  ${gap.durationMinutes} min gap at ${gap.start}`);
+   * }
+   * ```
+   */
+  async symbolCoverage(exchange, symbol) {
+    return this.http.get(
+      `${this.basePath}/coverage/${exchange.toLowerCase()}/${symbol.toUpperCase()}`
+    );
+  }
+  // ===========================================================================
+  // Incidents Endpoints
+  // ===========================================================================
+  /**
+   * List incidents with filtering and pagination
+   *
+   * @param params - Filter and pagination options
+   * @returns IncidentsResponse with list of incidents and pagination info
+   *
+   * @example
+   * ```typescript
+   * // Get all open incidents
+   * const result = await client.dataQuality.listIncidents({ status: 'open' });
+   * for (const incident of result.incidents) {
+   *   console.log(`${incident.severity}: ${incident.title}`);
+   * }
+   * ```
+   */
+  async listIncidents(params) {
+    return this.http.get(
+      `${this.basePath}/incidents`,
+      params
+    );
+  }
+  /**
+   * Get a specific incident by ID
+   *
+   * @param incidentId - The incident ID
+   * @returns Incident details
+   *
+   * @example
+   * ```typescript
+   * const incident = await client.dataQuality.getIncident('inc_123');
+   * console.log(`Status: ${incident.status}`);
+   * console.log(`Root cause: ${incident.rootCause}`);
+   * ```
+   */
+  async getIncident(incidentId) {
+    return this.http.get(`${this.basePath}/incidents/${incidentId}`);
+  }
+  // ===========================================================================
+  // Latency Endpoints
+  // ===========================================================================
+  /**
+   * Get current latency metrics for all exchanges
+   *
+   * @returns LatencyResponse with WebSocket, REST API, and data freshness metrics
+   *
+   * @example
+   * ```typescript
+   * const latency = await client.dataQuality.latency();
+   * for (const [exchange, metrics] of Object.entries(latency.exchanges)) {
+   *   console.log(`${exchange}:`);
+   *   if (metrics.websocket) {
+   *     console.log(`  WS current: ${metrics.websocket.currentMs}ms`);
+   *   }
+   *   console.log(`  OB lag: ${metrics.dataFreshness.orderbookLagMs}ms`);
+   * }
+   * ```
+   */
+  async latency() {
+    return this.http.get(`${this.basePath}/latency`);
+  }
+  // ===========================================================================
+  // SLA Endpoints
+  // ===========================================================================
+  /**
+   * Get SLA compliance metrics for a specific month
+   *
+   * @param params - Optional year and month (defaults to current month)
+   * @returns SlaResponse with SLA targets, actual metrics, and compliance status
+   *
+   * @example
+   * ```typescript
+   * const sla = await client.dataQuality.sla({ year: 2026, month: 1 });
+   * console.log(`Period: ${sla.period}`);
+   * console.log(`Uptime: ${sla.actual.uptime}% (${sla.actual.uptimeStatus})`);
+   * console.log(`Completeness: ${sla.actual.dataCompleteness.overall}%`);
+   * console.log(`API P99: ${sla.actual.apiLatencyP99Ms}ms`);
+   * ```
+   */
+  async sla(params) {
+    return this.http.get(
+      `${this.basePath}/sla`,
+      params
+    );
+  }
+};
+
 // src/exchanges.ts
 var HyperliquidClient = class {
   /**
@@ -772,6 +952,10 @@ var OxArchive = class {
    * Lighter.xyz exchange data (August 2025+)
    */
   lighter;
+  /**
+   * Data quality metrics: status, coverage, incidents, latency, SLA
+   */
+  dataQuality;
   /**
    * @deprecated Use client.hyperliquid.orderbook instead
    */
@@ -809,6 +993,7 @@ var OxArchive = class {
     });
     this.hyperliquid = new HyperliquidClient(this.http);
     this.lighter = new LighterClient(this.http);
+    this.dataQuality = new DataQualityResource(this.http);
     const legacyBase = "/v1/hyperliquid";
     this.orderbook = new OrderBookResource(this.http, legacyBase);
     this.trades = new TradesResource(this.http, legacyBase);
@@ -913,6 +1098,7 @@ var OxArchiveWs = class {
   streamCompleteHandlers = [];
   orderbookHandlers = [];
   tradesHandlers = [];
+  gapHandlers = [];
   constructor(options) {
     this.options = {
       apiKey: options.apiKey,
@@ -1202,6 +1388,25 @@ var OxArchiveWs = class {
   onStreamComplete(handler) {
     this.streamCompleteHandlers.push(handler);
   }
+  /**
+   * Handle gap detected events during replay or streaming.
+   * Called when there's a gap in the historical data exceeding the threshold.
+   * Thresholds: 2 minutes for orderbook/candles/liquidations, 60 minutes for trades.
+   *
+   * @param handler - Callback receiving channel, coin, gap start/end timestamps (ms), and duration (minutes)
+   *
+   * @example
+   * ```typescript
+   * ws.onGap((channel, coin, gapStart, gapEnd, durationMinutes) => {
+   *   console.warn(`Gap detected in ${channel} ${coin}: ${durationMinutes} minutes`);
+   *   console.warn(`  From: ${new Date(gapStart).toISOString()}`);
+   *   console.warn(`  To:   ${new Date(gapEnd).toISOString()}`);
+   * });
+   * ```
+   */
+  onGap(handler) {
+    this.gapHandlers.push(handler);
+  }
   /**
    * Get current connection state
    */
@@ -1344,6 +1549,13 @@ var OxArchiveWs = class {
         }
         break;
       }
+      case "gap_detected": {
+        const msg = message;
+        for (const handler of this.gapHandlers) {
+          handler(msg.channel, msg.coin, msg.gap_start, msg.gap_end, msg.duration_minutes);
+        }
+        break;
+      }
       case "data": {
         if (message.channel === "orderbook") {
           const orderbook = transformOrderbook(message.coin, message.data);