lumefuse-sdk 1.0.0

package/src/client.ts

@@ -0,0 +1,391 @@
+/**
+ * LumeFuse Client - Main SDK Client
+ */
+
+import { createHash } from 'crypto';
+import { DataStream, StreamResult, StreamConfig } from './stream';
+import type {
+  LumeFuseConfig,
+  BitPacket,
+  VerificationResult,
+  ChainStatus,
+  CreditBalance,
+  HealingEvent,
+  SentinelStatus,
+  AuditResult,
+} from './types';
+import {
+  LumeFuseError,
+  AuthenticationError,
+  RateLimitError,
+  ChainIntegrityError,
+  InsufficientCreditsError,
+  NetworkError,
+} from './errors';
+
+const DEFAULT_BASE_URL = 'https://api.lumefuse.io/v1';
+
+/**
+ * LumeFuse SDK Client - The "Born-Signed" Data Integrity Platform
+ * 
+ * This client provides methods to:
+ * - Open data streams for Bit-Packet creation
+ * - Verify data against the BSV ledger
+ * - Check chain integrity
+ * - Monitor healing events
+ * 
+ * @example
+ * ```typescript
+ * import { LumeFuse } from '@lumefuse/sdk';
+ * 
+ * const lf = new LumeFuse({ apiKey: 'lf_your_api_key' });
+ * 
+ * // Create a data stream
+ * const stream = lf.openStream('sensor_data');
+ * await stream.write({ temperature: 72.5 });
+ * const result = await stream.close();
+ * 
+ * // Verify chain integrity
+ * const status = await lf.verifyChain('sensor_data');
+ * console.log(`Chain intact: ${status.chainIntact}`);
+ * ```
+ */
+export class LumeFuse {
+  private apiKey: string;
+  private baseUrl: string;
+  private timeout: number;
+  private autoHeal: boolean;
+
+  constructor(config: LumeFuseConfig) {
+    this.apiKey = config.apiKey || process.env.LUMEFUSE_API_KEY || '';
+    this.baseUrl = config.baseUrl || process.env.LUMEFUSE_BASE_URL || DEFAULT_BASE_URL;
+    this.timeout = config.timeout || 30000;
+    this.autoHeal = config.autoHeal ?? true;
+
+    if (!this.apiKey) {
+      throw new AuthenticationError(
+        'API key is required. Set LUMEFUSE_API_KEY environment variable or pass apiKey in config.'
+      );
+    }
+
+    if (!this.apiKey.startsWith('lf_')) {
+      throw new AuthenticationError(
+        "Invalid API key format. API keys should start with 'lf_'"
+      );
+    }
+  }
+
+  /**
+   * Make an API request
+   */
+  private async request<T = Record<string, unknown>>(
+    method: string,
+    endpoint: string,
+    data?: Record<string, unknown>,
+    params?: Record<string, string>
+  ): Promise<T> {
+    const url = new URL(endpoint, this.baseUrl);
+    
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        url.searchParams.append(key, value);
+      });
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url.toString(), {
+        method,
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+          'X-SDK-Version': 'lumefuse-js/1.0.0',
+        },
+        body: data ? JSON.stringify(data) : undefined,
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeoutId);
+
+      if (response.status === 401) {
+        throw new AuthenticationError('Invalid API key');
+      }
+
+      if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        throw new RateLimitError(
+          'Rate limit exceeded',
+          retryAfter ? parseInt(retryAfter) : null
+        );
+      }
+
+      if (response.status === 402) {
+        throw new InsufficientCreditsError('Insufficient BSV credits');
+      }
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        throw new LumeFuseError(
+          (errorData as Record<string, string>).detail || `Request failed with status ${response.status}`,
+          String(response.status)
+        );
+      }
+
+      return response.json() as Promise<T>;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      
+      if (error instanceof LumeFuseError) {
+        throw error;
+      }
+      
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new NetworkError('Request timeout');
+      }
+      
+      throw new NetworkError(`Network request failed: ${error}`);
+    }
+  }
+
+  // ==================== STREAM API ====================
+
+  /**
+   * Open a new data stream for Bit-Packet creation.
+   * 
+   * This is the core "Latch" - data written to the returned stream is
+   * automatically hashed, linked with Recursive DNA, and anchored to BSV.
+   * 
+   * @param sourceId - Unique identifier for this data source
+   * @param config - Stream configuration options
+   * @returns DataStream for writing data
+   * 
+   * @example
+   * ```typescript
+   * const stream = lf.openStream('medical_lab_results');
+   * await stream.write({ patient_id: 'P-001', glucose: 95 });
+   * await stream.write({ patient_id: 'P-001', glucose: 102 });
+   * const result = await stream.close();
+   * console.log(`Merkle Root: ${result.merkleRoot}`);
+   * ```
+   */
+  openStream(sourceId: string, config?: StreamConfig): DataStream {
+    return new DataStream(sourceId, this, config);
+  }
+
+  // ==================== WRAP API ====================
+
+  /**
+   * Wrap data into a single Bit-Packet with Recursive DNA.
+   */
+  async wrap(sourceId: string, data: unknown): Promise<BitPacket> {
+    let dataStr: string;
+    
+    if (typeof data === 'string') {
+      dataStr = data;
+    } else {
+      dataStr = JSON.stringify(data, Object.keys(data as object).sort());
+    }
+
+    const response = await this.request<Record<string, unknown>>('POST', '/packets/wrap', {
+      source_id: sourceId,
+      data: dataStr,
+    });
+
+    return this.mapBitPacket(response);
+  }
+
+  // ==================== VERIFY API ====================
+
+  /**
+   * Verify data against the BSV ledger.
+   */
+  async verify(data: unknown): Promise<VerificationResult> {
+    let dataHash: string;
+    
+    if (typeof data === 'string') {
+      dataHash = createHash('sha256').update(data).digest('hex');
+    } else if (Buffer.isBuffer(data)) {
+      dataHash = createHash('sha256').update(data).digest('hex');
+    } else {
+      const dataStr = JSON.stringify(data, Object.keys(data as object).sort());
+      dataHash = createHash('sha256').update(dataStr).digest('hex');
+    }
+
+    const response = await this.request<Record<string, unknown>>('POST', '/verify', {
+      data_hash: dataHash,
+    });
+
+    return {
+      verified: response.verified as boolean,
+      sourceId: response.source_id as string,
+      dataHash,
+      expectedHash: response.expected_hash as string | null,
+      txId: response.tx_id as string | null,
+      timestamp: response.timestamp as string | null,
+      message: response.message as string || '',
+      quantumResistant: response.quantum_resistant as boolean ?? true,
+    };
+  }
+
+  /**
+   * Verify the entire Recursive DNA chain for a source.
+   */
+  async verifyChain(sourceId: string, autoHeal?: boolean): Promise<ChainStatus> {
+    const heal = autoHeal ?? this.autoHeal;
+
+    const response = await this.request<Record<string, unknown>>('POST', '/sentinel/verify', {
+      source_id: sourceId,
+      auto_heal: heal,
+    });
+
+    const breakEvent = response.break_event as Record<string, unknown> | null;
+
+    const status: ChainStatus = {
+      sourceId,
+      chainIntact: response.chain_intact as boolean,
+      totalPackets: response.total_packets as number,
+      verifiedPackets: response.total_packets as number,
+      breakSequence: breakEvent?.break_sequence as number | null ?? null,
+      breakTimestamp: breakEvent?.break_timestamp as string | null ?? null,
+      health: 'healthy',
+      quantumResistant: response.quantum_resistant as boolean ?? true,
+      healed: response.healed as boolean ?? false,
+      forensicMessage: response.message as string | null,
+    };
+
+    if (!status.chainIntact && !heal) {
+      throw new ChainIntegrityError(
+        `DNA chain broken at sequence ${status.breakSequence}`,
+        status.breakSequence,
+        status.breakTimestamp
+      );
+    }
+
+    return status;
+  }
+
+  // ==================== SENTINEL API ====================
+
+  /**
+   * Get the current status of the Sentinel (self-healing system).
+   */
+  async getSentinelStatus(): Promise<SentinelStatus> {
+    const response = await this.request<Record<string, unknown>>('GET', '/sentinel/status');
+    
+    const features = response.features as Record<string, boolean>;
+    
+    return {
+      active: response.active as boolean,
+      monitoring: response.monitoring as boolean,
+      auditIntervalSeconds: response.audit_interval_seconds as number,
+      quarantinedSources: response.quarantined_sources as number,
+      features: {
+        continuousAudit: features?.continuous_audit ?? false,
+        autoHeal: features?.auto_heal ?? false,
+        webhooks: features?.webhooks ?? false,
+        quantumResistant: features?.quantum_resistant ?? true,
+      },
+      description: response.description as string,
+    };
+  }
+
+  /**
+   * Manually trigger a full audit of all data sources.
+   */
+  async triggerAudit(): Promise<AuditResult> {
+    const response = await this.request<Record<string, unknown>>('POST', '/sentinel/audit/run');
+    
+    return {
+      auditId: response.audit_id as string,
+      timestamp: response.timestamp as string,
+      sourcesAudited: response.sources_audited as number,
+      packetsVerified: response.packets_verified as number,
+      healthySources: response.healthy_sources as number,
+      infectedSources: response.infected_sources as number,
+      healedSources: response.healed_sources as number,
+      auditDurationMs: response.audit_duration_ms as number,
+    };
+  }
+
+  /**
+   * Manually trigger healing for a specific data break.
+   */
+  async heal(sourceId: string, breakSequence: number): Promise<Record<string, unknown>> {
+    return this.request('POST', '/sentinel/heal', {
+      source_id: sourceId,
+      break_sequence: breakSequence,
+    });
+  }
+
+  /**
+   * Get history of healing events.
+   */
+  async getHealingHistory(sourceId?: string): Promise<HealingEvent[]> {
+    const params = sourceId ? { source_id: sourceId } : undefined;
+    const response = await this.request<Record<string, unknown>>('GET', '/sentinel/healing-history', undefined, params);
+    
+    const events = response.events as Record<string, unknown>[];
+    
+    return events.map(e => ({
+      id: e.id as string,
+      sourceId: e.source_id as string,
+      breakSequence: e.break_sequence as number,
+      originalHash: e.original_payload_hash as string,
+      corruptedHash: e.corrupted_payload_hash as string,
+      recoverySource: e.recovery_source as string,
+      healedAt: e.healed_at as string,
+      success: e.success as boolean,
+      receiptHash: e.verification_tx_id as string | null,
+      message: e.message as string,
+    }));
+  }
+
+  // ==================== CREDITS API ====================
+
+  /**
+   * Get current BSV credit balance.
+   */
+  async getCredits(): Promise<CreditBalance> {
+    const response = await this.request<Record<string, unknown>>('GET', '/credits/balance');
+    
+    return {
+      satoshiBalance: response.satoshi_balance as number,
+      packetsAvailable: response.packets_available as number,
+      totalDeposited: response.total_deposited as number,
+      totalSpent: response.total_spent as number,
+    };
+  }
+
+  // ==================== PACKETS API ====================
+
+  /**
+   * Get all packets for a source.
+   */
+  async getPackets(sourceId: string, limit: number = 100): Promise<BitPacket[]> {
+    const response = await this.request<Record<string, unknown>[]>('GET', '/packets', undefined, {
+      source_id: sourceId,
+      limit: String(limit),
+    });
+    
+    return response.map(p => this.mapBitPacket(p));
+  }
+
+  // ==================== HELPERS ====================
+
+  private mapBitPacket(data: Record<string, unknown>): BitPacket {
+    return {
+      sourceId: data.source_id as string,
+      sequenceNo: data.sequence_no as number,
+      payloadHash: data.payload_hash as string,
+      recursiveDna: data.recursive_dna as string,
+      prevPacketHash: data.prev_packet_hash as string | null,
+      timestamp: data.timestamp as string,
+      txId: data.tx_id as string | null,
+      status: data.status as any,
+      chainValid: data.chain_valid as boolean,
+      originalDataPreview: data.original_data_preview as string,
+    };
+  }
+}

package/src/errors.ts

@@ -0,0 +1,84 @@
+/**
+ * LumeFuse SDK Error Classes
+ */
+
+export class LumeFuseError extends Error {
+  code: string;
+  details: Record<string, unknown>;
+
+  constructor(message: string, code: string = 'LUMEFUSE_ERROR', details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = 'LumeFuseError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export class AuthenticationError extends LumeFuseError {
+  constructor(message: string = 'Invalid or missing API key') {
+    super(message, 'AUTH_ERROR');
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class RateLimitError extends LumeFuseError {
+  retryAfter: number | null;
+
+  constructor(message: string = 'Rate limit exceeded', retryAfter: number | null = null) {
+    super(message, 'RATE_LIMIT');
+    this.name = 'RateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}
+
+export class ChainIntegrityError extends LumeFuseError {
+  breakSequence: number | null;
+  breakTimestamp: string | null;
+
+  constructor(
+    message: string = 'Chain integrity compromised',
+    breakSequence: number | null = null,
+    breakTimestamp: string | null = null
+  ) {
+    super(message, 'CHAIN_BREAK');
+    this.name = 'ChainIntegrityError';
+    this.breakSequence = breakSequence;
+    this.breakTimestamp = breakTimestamp;
+  }
+}
+
+export class InsufficientCreditsError extends LumeFuseError {
+  required: number | null;
+  available: number | null;
+
+  constructor(
+    message: string = 'Insufficient BSV credits',
+    required: number | null = null,
+    available: number | null = null
+  ) {
+    super(message, 'INSUFFICIENT_CREDITS');
+    this.name = 'InsufficientCreditsError';
+    this.required = required;
+    this.available = available;
+  }
+}
+
+export class NetworkError extends LumeFuseError {
+  statusCode: number | null;
+
+  constructor(message: string = 'Network request failed', statusCode: number | null = null) {
+    super(message, 'NETWORK_ERROR');
+    this.name = 'NetworkError';
+    this.statusCode = statusCode;
+  }
+}
+
+export class ValidationError extends LumeFuseError {
+  field: string | null;
+
+  constructor(message: string = 'Validation failed', field: string | null = null) {
+    super(message, 'VALIDATION_ERROR');
+    this.name = 'ValidationError';
+    this.field = field;
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * LumeFuse SDK - Atomic Veracity Protocol
+ * 
+ * The "Born-Signed" SDK for embedding structural DNA into your data.
+ */
+
+export { LumeFuse } from './client';
+export { DataStream } from './stream';
+export type { StreamResult } from './stream';
+export type {
+  BitPacket,
+  VerificationResult,
+  ChainStatus,
+  CreditBalance,
+  HealingEvent,
+  LumeFuseConfig,
+  PacketStatus,
+  ChainHealth,
+} from './types';
+export {
+  LumeFuseError,
+  AuthenticationError,
+  RateLimitError,
+  ChainIntegrityError,
+  InsufficientCreditsError,
+  NetworkError,
+  ValidationError,
+} from './errors';