lumefuse-sdk 1.0.0

package/README.md

@@ -0,0 +1,212 @@
+# LumeFuse JavaScript/TypeScript SDK
+
+The official JavaScript/TypeScript SDK for [LumeFuse](https://lumefuse.io) - Atomic Veracity Protocol for Born-Signed Data.
+
+## Installation
+
+```bash
+npm install @lumefuse/sdk
+# or
+yarn add @lumefuse/sdk
+```
+
+## Quick Start
+
+```typescript
+import { LumeFuse } from '@lumefuse/sdk';
+
+// Initialize the client
+const lf = new LumeFuse({ apiKey: 'lf_your_api_key' });
+
+// Open a data stream (The "Latch")
+const stream = lf.openStream('medical_lab_results');
+
+// Every data point is automatically:
+// 1. Hashed (SHA-256)
+// 2. Linked to previous packet (Recursive DNA)
+// 3. Anchored to BSV ledger
+
+await stream.write({ patient_id: 'P-001', glucose: 95, timestamp: '2026-02-20T14:30:00Z' });
+await stream.write({ patient_id: 'P-001', glucose: 102, timestamp: '2026-02-20T15:30:00Z' });
+
+// Close stream and get the Merkle root
+const result = await stream.close();
+console.log(`Chain Root: ${result.merkleRoot}`);
+console.log(`Total Packets: ${result.totalPackets}`);
+console.log(`BSV TX: ${result.anchorTxid}`);
+```
+
+## Features
+
+### Recursive DNA Binding (The Cryptographic Heartbeat)
+
+Every Bit-Packet contains the DNA of the previous packet:
+
+```
+H_N = SHA256(Data_N + H_{N-1})
+```
+
+This creates an unbreakable chain where altering any packet breaks all subsequent packets.
+
+### Quantum Resistance
+
+The recursive hashing model provides practical resistance against quantum computing attacks.
+
+### Self-Healing Data
+
+The Sentinel system automatically detects and heals data corruption:
+
+```typescript
+// Verify chain integrity
+const status = await lf.verifyChain('medical_lab_results');
+
+if (status.chainIntact) {
+  console.log('Data integrity verified');
+} else {
+  console.log(`Break detected at sequence ${status.breakSequence}`);
+  if (status.healed) {
+    console.log('Data automatically healed!');
+  }
+}
+```
+
+## API Reference
+
+### LumeFuse Client
+
+```typescript
+import { LumeFuse } from '@lumefuse/sdk';
+
+const lf = new LumeFuse({
+  apiKey: 'lf_your_api_key',
+  baseUrl: 'https://api.lumefuse.io/v1', // Optional
+  timeout: 30000, // Optional, in milliseconds
+  autoHeal: true, // Optional
+});
+```
+
+### Data Streams
+
+```typescript
+// Open a stream
+const stream = lf.openStream('source_id', {
+  autoAnchor: true, // Default: true
+  batchSize: 100, // Default: 100
+});
+
+// Write data (any JSON-serializable object)
+await stream.write({ key: 'value' });
+await stream.write(['array', 'of', 'items']);
+await stream.write('plain string');
+
+// Close and get result
+const result = await stream.close();
+```
+
+### Verification
+
+```typescript
+// Verify single data item
+const result = await lf.verify({ key: 'value' });
+console.log(`Verified: ${result.verified}`);
+
+// Verify entire chain
+const status = await lf.verifyChain('source_id');
+console.log(`Chain intact: ${status.chainIntact}`);
+console.log(`Quantum resistant: ${status.quantumResistant}`);
+```
+
+### Sentinel (Self-Healing)
+
+```typescript
+// Get sentinel status
+const status = await lf.getSentinelStatus();
+
+// Manually trigger audit
+const audit = await lf.triggerAudit();
+
+// Manually heal a break
+const result = await lf.heal('source_id', 5);
+
+// Get healing history
+const history = await lf.getHealingHistory('source_id');
+```
+
+### Credits
+
+```typescript
+// Get credit balance
+const balance = await lf.getCredits();
+console.log(`Packets available: ${balance.packetsAvailable}`);
+console.log(`Satoshi balance: ${balance.satoshiBalance}`);
+```
+
+## TypeScript Support
+
+Full TypeScript support with type definitions included:
+
+```typescript
+import type {
+  BitPacket,
+  VerificationResult,
+  ChainStatus,
+  CreditBalance,
+  HealingEvent,
+} from '@lumefuse/sdk';
+```
+
+## Error Handling
+
+```typescript
+import { LumeFuse } from '@lumefuse/sdk';
+import {
+  AuthenticationError,
+  RateLimitError,
+  ChainIntegrityError,
+  InsufficientCreditsError,
+} from '@lumefuse/sdk';
+
+try {
+  const lf = new LumeFuse({ apiKey: 'lf_invalid' });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.log('Invalid API key');
+  }
+}
+
+try {
+  const status = await lf.verifyChain('source', false); // autoHeal = false
+} catch (error) {
+  if (error instanceof ChainIntegrityError) {
+    console.log(`Chain broken at sequence ${error.breakSequence}`);
+  }
+}
+```
+
+## Environment Variables
+
+- `LUMEFUSE_API_KEY` - Your API key
+- `LUMEFUSE_BASE_URL` - Custom API base URL (optional)
+
+## Publishing to npm
+
+```bash
+# Build the package
+npm run build
+
+# Login to npm
+npm login
+
+# Publish
+npm publish --access public
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Support
+
+- Documentation: https://docs.lumefuse.io
+- Email: support@lumefuse.io
+- Enterprise: enterprise@lumefuse.io

package/dist/index.d.mts

@@ -0,0 +1,373 @@
+/**
+ * LumeFuse SDK Type Definitions
+ */
+type PacketStatus = 'pending' | 'anchored' | 'verified' | 'corrupted' | 'healed';
+type ChainHealth = 'healthy' | 'infected' | 'quarantined' | 'healing' | 'healed' | 'terminal';
+interface LumeFuseConfig {
+    /** Your LumeFuse API key (starts with 'lf_') */
+    apiKey: string;
+    /** API base URL (default: https://api.lumefuse.io/v1) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Whether to automatically heal chain breaks (default: true) */
+    autoHeal?: boolean;
+}
+interface BitPacket {
+    /** Unique identifier for the data source */
+    sourceId: string;
+    /** Sequence number in the chain */
+    sequenceNo: number;
+    /** SHA-256 hash of the payload */
+    payloadHash: string;
+    /** Recursive DNA linking to previous packet */
+    recursiveDna: string;
+    /** Previous packet's recursive DNA */
+    prevPacketHash: string | null;
+    /** Creation timestamp */
+    timestamp: string;
+    /** BSV transaction ID (if anchored) */
+    txId: string | null;
+    /** Current status */
+    status: PacketStatus;
+    /** Whether chain is valid at this point */
+    chainValid: boolean;
+    /** Preview of original data */
+    originalDataPreview?: string;
+}
+interface VerificationResult {
+    /** Whether the data was verified */
+    verified: boolean;
+    /** Source ID */
+    sourceId: string;
+    /** Hash of the verified data */
+    dataHash: string;
+    /** Expected hash from ledger */
+    expectedHash: string | null;
+    /** BSV transaction ID */
+    txId: string | null;
+    /** Verification timestamp */
+    timestamp: string | null;
+    /** Human-readable message */
+    message: string;
+    /** Whether protected by quantum-resistant hashing */
+    quantumResistant: boolean;
+}
+interface ChainStatus {
+    /** Source ID */
+    sourceId: string;
+    /** Whether the entire chain is intact */
+    chainIntact: boolean;
+    /** Total number of packets in chain */
+    totalPackets: number;
+    /** Number of verified packets */
+    verifiedPackets: number;
+    /** Sequence number where break occurred (if any) */
+    breakSequence: number | null;
+    /** Timestamp of break (if any) */
+    breakTimestamp: string | null;
+    /** Chain health status */
+    health: ChainHealth;
+    /** Whether protected by quantum-resistant hashing */
+    quantumResistant: boolean;
+    /** Whether chain was healed */
+    healed: boolean;
+    /** Forensic analysis message */
+    forensicMessage: string | null;
+}
+interface CreditBalance {
+    /** Balance in satoshis */
+    satoshiBalance: number;
+    /** Number of packets that can be created */
+    packetsAvailable: number;
+    /** Total satoshis deposited */
+    totalDeposited: number;
+    /** Total satoshis spent */
+    totalSpent: number;
+}
+interface HealingEvent {
+    /** Unique event ID */
+    id: string;
+    /** Source ID */
+    sourceId: string;
+    /** Sequence where break occurred */
+    breakSequence: number;
+    /** Original payload hash */
+    originalHash: string;
+    /** Corrupted payload hash */
+    corruptedHash: string;
+    /** How data was recovered */
+    recoverySource: string;
+    /** When healing completed */
+    healedAt: string;
+    /** Whether healing was successful */
+    success: boolean;
+    /** Immutable receipt hash */
+    receiptHash: string | null;
+    /** Human-readable message */
+    message: string;
+}
+interface SentinelStatus {
+    /** Whether sentinel is active */
+    active: boolean;
+    /** Whether continuous monitoring is running */
+    monitoring: boolean;
+    /** Audit interval in seconds */
+    auditIntervalSeconds: number;
+    /** Number of quarantined sources */
+    quarantinedSources: number;
+    /** Available features */
+    features: {
+        continuousAudit: boolean;
+        autoHeal: boolean;
+        webhooks: boolean;
+        quantumResistant: boolean;
+    };
+    /** Description */
+    description: string;
+}
+interface AuditResult {
+    /** Audit ID */
+    auditId: string;
+    /** Audit timestamp */
+    timestamp: string;
+    /** Number of sources audited */
+    sourcesAudited: number;
+    /** Number of packets verified */
+    packetsVerified: number;
+    /** Number of healthy sources */
+    healthySources: number;
+    /** Number of infected sources */
+    infectedSources: number;
+    /** Number of healed sources */
+    healedSources: number;
+    /** Audit duration in milliseconds */
+    auditDurationMs: number;
+}
+
+/**
+ * LumeFuse DataStream - The "Latch" for Born-Signed Data
+ */
+
+interface StreamResult {
+    /** Source ID */
+    sourceId: string;
+    /** Total packets created */
+    totalPackets: number;
+    /** Merkle root of all packet hashes */
+    merkleRoot: string;
+    /** Last anchor transaction ID */
+    anchorTxid: string | null;
+    /** All created packets */
+    packets: BitPacket[];
+    /** Stream creation timestamp */
+    createdAt: string;
+    /** Whether chain is quantum resistant */
+    quantumResistant: boolean;
+}
+interface StreamConfig {
+    /** Whether to automatically anchor packets */
+    autoAnchor?: boolean;
+    /** Number of packets to batch before anchoring */
+    batchSize?: number;
+}
+/**
+ * A data stream for creating Bit-Packets with Recursive DNA Binding.
+ *
+ * This is the core "Latch" - data written to this stream is automatically:
+ * 1. Hashed (SHA-256)
+ * 2. Linked to previous packet (Recursive DNA)
+ * 3. Queued for BSV anchoring
+ *
+ * @example
+ * ```typescript
+ * const stream = lf.openStream('sensor_data');
+ * await stream.write({ temperature: 72.5, humidity: 45 });
+ * await stream.write({ temperature: 73.1, humidity: 44 });
+ * const result = await stream.close();
+ * console.log(`Merkle Root: ${result.merkleRoot}`);
+ * ```
+ */
+declare class DataStream {
+    private sourceId;
+    private client;
+    private autoAnchor;
+    private batchSize;
+    private packets;
+    private prevRecursiveDna;
+    private sequenceNo;
+    private closed;
+    private createdAt;
+    constructor(sourceId: string, client: any, config?: StreamConfig);
+    /**
+     * Compute SHA-256 hash of data
+     */
+    private computeHash;
+    /**
+     * Compute Recursive DNA - the Cryptographic Heartbeat
+     * Formula: recursive_dna[N] = SHA256(payload_hash[N] + recursive_dna[N-1])
+     */
+    private computeRecursiveDna;
+    /**
+     * Write data to the stream, creating a Bit-Packet with Recursive DNA
+     */
+    write(data: unknown): Promise<BitPacket>;
+    /**
+     * Write multiple data items to the stream
+     */
+    writeMany(dataList: unknown[]): Promise<BitPacket[]>;
+    /**
+     * Anchor pending packets to BSV (internal method)
+     */
+    private anchorBatch;
+    /**
+     * Compute Merkle root of all packet hashes
+     */
+    private computeMerkleRoot;
+    /**
+     * Close the stream and finalize all packets
+     */
+    close(): Promise<StreamResult>;
+    /**
+     * Number of packets written to this stream
+     */
+    get packetCount(): number;
+    /**
+     * Whether the stream is closed
+     */
+    get isClosed(): boolean;
+}
+
+/**
+ * LumeFuse Client - Main SDK Client
+ */
+
+/**
+ * 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}`);
+ * ```
+ */
+declare class LumeFuse {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private autoHeal;
+    constructor(config: LumeFuseConfig);
+    /**
+     * Make an API request
+     */
+    private request;
+    /**
+     * 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;
+    /**
+     * Wrap data into a single Bit-Packet with Recursive DNA.
+     */
+    wrap(sourceId: string, data: unknown): Promise<BitPacket>;
+    /**
+     * Verify data against the BSV ledger.
+     */
+    verify(data: unknown): Promise<VerificationResult>;
+    /**
+     * Verify the entire Recursive DNA chain for a source.
+     */
+    verifyChain(sourceId: string, autoHeal?: boolean): Promise<ChainStatus>;
+    /**
+     * Get the current status of the Sentinel (self-healing system).
+     */
+    getSentinelStatus(): Promise<SentinelStatus>;
+    /**
+     * Manually trigger a full audit of all data sources.
+     */
+    triggerAudit(): Promise<AuditResult>;
+    /**
+     * Manually trigger healing for a specific data break.
+     */
+    heal(sourceId: string, breakSequence: number): Promise<Record<string, unknown>>;
+    /**
+     * Get history of healing events.
+     */
+    getHealingHistory(sourceId?: string): Promise<HealingEvent[]>;
+    /**
+     * Get current BSV credit balance.
+     */
+    getCredits(): Promise<CreditBalance>;
+    /**
+     * Get all packets for a source.
+     */
+    getPackets(sourceId: string, limit?: number): Promise<BitPacket[]>;
+    private mapBitPacket;
+}
+
+/**
+ * LumeFuse SDK Error Classes
+ */
+declare class LumeFuseError extends Error {
+    code: string;
+    details: Record<string, unknown>;
+    constructor(message: string, code?: string, details?: Record<string, unknown>);
+}
+declare class AuthenticationError extends LumeFuseError {
+    constructor(message?: string);
+}
+declare class RateLimitError extends LumeFuseError {
+    retryAfter: number | null;
+    constructor(message?: string, retryAfter?: number | null);
+}
+declare class ChainIntegrityError extends LumeFuseError {
+    breakSequence: number | null;
+    breakTimestamp: string | null;
+    constructor(message?: string, breakSequence?: number | null, breakTimestamp?: string | null);
+}
+declare class InsufficientCreditsError extends LumeFuseError {
+    required: number | null;
+    available: number | null;
+    constructor(message?: string, required?: number | null, available?: number | null);
+}
+declare class NetworkError extends LumeFuseError {
+    statusCode: number | null;
+    constructor(message?: string, statusCode?: number | null);
+}
+declare class ValidationError extends LumeFuseError {
+    field: string | null;
+    constructor(message?: string, field?: string | null);
+}
+
+export { AuthenticationError, type BitPacket, type ChainHealth, ChainIntegrityError, type ChainStatus, type CreditBalance, DataStream, type HealingEvent, InsufficientCreditsError, LumeFuse, type LumeFuseConfig, LumeFuseError, NetworkError, type PacketStatus, RateLimitError, type StreamResult, ValidationError, type VerificationResult };