@originals/sdk 1.4.3 → 1.5.0

package/dist/utils/Logger.js

@@ -0,0 +1,257 @@
+/**
+ * Enhanced Logger for Originals SDK
+ *
+ * Features:
+ * - Multiple log levels (debug, info, warn, error)
+ * - Child loggers with hierarchical context
+ * - Performance timing with startTimer
+ * - Multiple output destinations
+ * - Data sanitization for sensitive information
+ * - Async-safe operations
+ */
+/**
+ * Console log output implementation
+ */
+export class ConsoleLogOutput {
+    write(entry) {
+        const timestamp = entry.timestamp;
+        const level = entry.level.toUpperCase().padEnd(5);
+        const context = entry.context;
+        const message = entry.message;
+        const durationStr = entry.duration !== undefined ? ` (${entry.duration.toFixed(2)}ms)` : '';
+        const dataStr = entry.data ? ` ${JSON.stringify(entry.data)}` : '';
+        const logMessage = `[${timestamp}] ${level} [${context}] ${message}${durationStr}${dataStr}`;
+        switch (entry.level) {
+            case 'debug':
+                console.debug(logMessage);
+                break;
+            case 'info':
+                console.info(logMessage);
+                break;
+            case 'warn':
+                console.warn(logMessage);
+                break;
+            case 'error':
+                console.error(logMessage);
+                break;
+        }
+    }
+}
+/**
+ * File log output implementation (async)
+ */
+export class FileLogOutput {
+    constructor(filePath) {
+        this.filePath = filePath;
+        this.buffer = [];
+        this.flushTimeout = null;
+        this.flushInterval = 1000; // Flush every 1 second
+    }
+    async write(entry) {
+        // Format as JSON line
+        const line = JSON.stringify(entry) + '\n';
+        this.buffer.push(line);
+        // Schedule flush
+        if (!this.flushTimeout) {
+            this.flushTimeout = setTimeout(() => this.flush(), this.flushInterval);
+        }
+    }
+    async flush() {
+        if (this.buffer.length === 0) {
+            return;
+        }
+        const lines = this.buffer.join('');
+        this.buffer = [];
+        this.flushTimeout = null;
+        try {
+            // Use Bun's file API for efficient file writing
+            const file = Bun.file(this.filePath);
+            const exists = await file.exists();
+            if (exists) {
+                // Append to existing file
+                const content = await file.text();
+                await Bun.write(this.filePath, content + lines);
+            }
+            else {
+                // Create new file
+                await Bun.write(this.filePath, lines);
+            }
+        }
+        catch (err) {
+            // Fallback to console on file write error
+            console.error('Failed to write log file:', err);
+        }
+    }
+}
+/**
+ * Main Logger class
+ */
+export class Logger {
+    constructor(context, config) {
+        this.context = context;
+        this.outputs = [];
+        this.minLevel = config.logging?.level || 'info';
+        this.includeTimestamps = config.logging?.includeTimestamps !== false;
+        this.includeContext = config.logging?.includeContext !== false;
+        this.sanitizeLogs = config.logging?.sanitizeLogs !== false;
+        // Set up default outputs
+        if (config.logging?.outputs && config.logging.outputs.length > 0) {
+            this.outputs = [...config.logging.outputs];
+        }
+        else {
+            // Default to console output
+            this.outputs = [new ConsoleLogOutput()];
+        }
+    }
+    /**
+     * Log a debug message
+     */
+    debug(message, data) {
+        this.log('debug', message, data);
+    }
+    /**
+     * Log an info message
+     */
+    info(message, data) {
+        this.log('info', message, data);
+    }
+    /**
+     * Log a warning message
+     */
+    warn(message, data) {
+        this.log('warn', message, data);
+    }
+    /**
+     * Log an error message
+     */
+    error(message, error, data) {
+        const errorData = error ? {
+            ...data,
+            error: {
+                name: error.name,
+                message: error.message,
+                stack: error.stack
+            }
+        } : data;
+        this.log('error', message, errorData);
+    }
+    /**
+     * Start a timer for performance tracking
+     * Returns a function that stops the timer and logs the duration
+     */
+    startTimer(operation) {
+        const startTime = performance.now();
+        return () => {
+            const duration = performance.now() - startTime;
+            this.log('debug', `${operation} completed`, undefined, duration);
+        };
+    }
+    /**
+     * Create a child logger with nested context
+     */
+    child(childContext) {
+        const newLogger = Object.create(Logger.prototype);
+        newLogger.context = `${this.context}:${childContext}`;
+        newLogger.outputs = this.outputs;
+        newLogger.minLevel = this.minLevel;
+        newLogger.includeTimestamps = this.includeTimestamps;
+        newLogger.includeContext = this.includeContext;
+        newLogger.sanitizeLogs = this.sanitizeLogs;
+        return newLogger;
+    }
+    /**
+     * Set a single output (replaces existing outputs)
+     */
+    setOutput(output) {
+        this.outputs = [output];
+    }
+    /**
+     * Add an output to the existing outputs
+     */
+    addOutput(output) {
+        this.outputs.push(output);
+    }
+    /**
+     * Internal log method
+     */
+    log(level, message, data, duration) {
+        // Check if we should log this level
+        if (Logger.LEVEL_PRIORITY[level] < Logger.LEVEL_PRIORITY[this.minLevel]) {
+            return;
+        }
+        // Sanitize data if needed
+        const sanitizedData = this.sanitizeLogs ? this.sanitize(data) : data;
+        // Create log entry
+        const entry = {
+            timestamp: this.includeTimestamps ? new Date().toISOString() : '',
+            level,
+            context: this.includeContext ? this.context : '',
+            message,
+            data: sanitizedData,
+            duration
+        };
+        // Write to all outputs (fire and forget for async outputs)
+        for (const output of this.outputs) {
+            try {
+                const result = output.write(entry);
+                // If result is a promise, don't await it (non-blocking)
+                if (result instanceof Promise) {
+                    result.catch(err => {
+                        // Silently fail for async outputs to avoid blocking
+                        if (typeof console !== 'undefined' && console.error) {
+                            console.error('Log output error:', err);
+                        }
+                    });
+                }
+            }
+            catch (err) {
+                // Continue even if one output fails
+                if (typeof console !== 'undefined' && console.error) {
+                    console.error('Log output error:', err);
+                }
+            }
+        }
+    }
+    /**
+     * Sanitize sensitive data from logs
+     */
+    sanitize(data) {
+        if (!data) {
+            return data;
+        }
+        // Handle arrays
+        if (Array.isArray(data)) {
+            return data.map(item => this.sanitize(item));
+        }
+        // Handle objects
+        if (typeof data === 'object') {
+            const sanitized = {};
+            for (const [key, value] of Object.entries(data)) {
+                const lowerKey = key.toLowerCase();
+                // Sanitize sensitive keys
+                if (lowerKey.includes('private') ||
+                    lowerKey.includes('key') ||
+                    lowerKey.includes('secret') ||
+                    lowerKey.includes('password') ||
+                    lowerKey.includes('token') ||
+                    lowerKey.includes('credential')) {
+                    sanitized[key] = '[REDACTED]';
+                }
+                else {
+                    // Recursively sanitize nested objects
+                    sanitized[key] = this.sanitize(value);
+                }
+            }
+            return sanitized;
+        }
+        // Return primitive values as-is
+        return data;
+    }
+}
+// Log level priorities
+Logger.LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3
+};

package/dist/utils/MetricsCollector.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Metrics Collector for Originals SDK
+ *
+ * Features:
+ * - Track operation counts and performance
+ * - Asset lifecycle metrics (created, migrated, transferred)
+ * - Error tracking by error code
+ * - Cache statistics (optional)
+ * - Export in JSON and Prometheus formats
+ * - Memory-efficient storage
+ */
+import type { LayerType } from '../types';
+/**
+ * Operation-specific metrics
+ */
+export interface OperationMetrics {
+    count: number;
+    totalTime: number;
+    avgTime: number;
+    minTime: number;
+    maxTime: number;
+    errorCount: number;
+}
+/**
+ * Complete metrics snapshot
+ */
+export interface Metrics {
+    assetsCreated: number;
+    assetsMigrated: Record<string, number>;
+    assetsTransferred: number;
+    operationTimes: Record<string, OperationMetrics>;
+    errors: Record<string, number>;
+    cacheStats?: {
+        hits: number;
+        misses: number;
+        hitRate: number;
+    };
+    startTime: string;
+    uptime: number;
+}
+/**
+ * MetricsCollector class
+ */
+export declare class MetricsCollector {
+    private assetsCreatedCount;
+    private assetsMigratedMap;
+    private assetsTransferredCount;
+    private operationMetrics;
+    private errorCounts;
+    private cacheHits;
+    private cacheMisses;
+    private readonly startTime;
+    constructor();
+    /**
+     * Record an operation with timing and success status
+     */
+    recordOperation(operation: string, duration: number, success: boolean): void;
+    /**
+     * Start tracking an operation, returns completion function
+     */
+    startOperation(operation: string): () => void;
+    /**
+     * Record an asset creation
+     */
+    recordAssetCreated(): void;
+    /**
+     * Record an asset migration between layers
+     */
+    recordMigration(from: LayerType, to: LayerType): void;
+    /**
+     * Record an asset transfer
+     */
+    recordTransfer(): void;
+    /**
+     * Record an error by error code
+     */
+    recordError(code: string, operation?: string): void;
+    /**
+     * Record a cache hit
+     */
+    recordCacheHit(): void;
+    /**
+     * Record a cache miss
+     */
+    recordCacheMiss(): void;
+    /**
+     * Get a snapshot of all metrics
+     */
+    getMetrics(): Metrics;
+    /**
+     * Get metrics for a specific operation
+     */
+    getOperationMetrics(operation: string): OperationMetrics | null;
+    /**
+     * Reset all metrics
+     */
+    reset(): void;
+    /**
+     * Export metrics in the specified format
+     */
+    export(format: 'json' | 'prometheus'): string;
+    /**
+     * Export metrics as JSON
+     */
+    private exportJSON;
+    /**
+     * Export metrics in Prometheus format
+     */
+    private exportPrometheus;
+}

package/dist/utils/MetricsCollector.js

@@ -0,0 +1,264 @@
+/**
+ * Metrics Collector for Originals SDK
+ *
+ * Features:
+ * - Track operation counts and performance
+ * - Asset lifecycle metrics (created, migrated, transferred)
+ * - Error tracking by error code
+ * - Cache statistics (optional)
+ * - Export in JSON and Prometheus formats
+ * - Memory-efficient storage
+ */
+/**
+ * MetricsCollector class
+ */
+export class MetricsCollector {
+    constructor() {
+        this.assetsCreatedCount = 0;
+        this.assetsMigratedMap = new Map();
+        this.assetsTransferredCount = 0;
+        this.operationMetrics = new Map();
+        this.errorCounts = new Map();
+        this.cacheHits = 0;
+        this.cacheMisses = 0;
+        this.startTime = new Date().toISOString();
+    }
+    /**
+     * Record an operation with timing and success status
+     */
+    recordOperation(operation, duration, success) {
+        if (!this.operationMetrics.has(operation)) {
+            this.operationMetrics.set(operation, {
+                count: 0,
+                totalTime: 0,
+                minTime: Infinity,
+                maxTime: -Infinity,
+                errorCount: 0
+            });
+        }
+        const metrics = this.operationMetrics.get(operation);
+        metrics.count++;
+        metrics.totalTime += duration;
+        metrics.minTime = Math.min(metrics.minTime, duration);
+        metrics.maxTime = Math.max(metrics.maxTime, duration);
+        if (!success) {
+            metrics.errorCount++;
+        }
+    }
+    /**
+     * Start tracking an operation, returns completion function
+     */
+    startOperation(operation) {
+        const startTime = performance.now();
+        return (success = true) => {
+            const duration = performance.now() - startTime;
+            this.recordOperation(operation, duration, success);
+        };
+    }
+    /**
+     * Record an asset creation
+     */
+    recordAssetCreated() {
+        this.assetsCreatedCount++;
+    }
+    /**
+     * Record an asset migration between layers
+     */
+    recordMigration(from, to) {
+        // Create transition key
+        const fromShort = from.split(':')[1]; // "peer", "webvh", "btco"
+        const toShort = to.split(':')[1];
+        const transitionKey = `${fromShort}→${toShort}`;
+        const current = this.assetsMigratedMap.get(transitionKey) || 0;
+        this.assetsMigratedMap.set(transitionKey, current + 1);
+    }
+    /**
+     * Record an asset transfer
+     */
+    recordTransfer() {
+        this.assetsTransferredCount++;
+    }
+    /**
+     * Record an error by error code
+     */
+    recordError(code, operation) {
+        // Track error by code
+        const current = this.errorCounts.get(code) || 0;
+        this.errorCounts.set(code, current + 1);
+        // If operation is provided, increment its error count
+        if (operation && this.operationMetrics.has(operation)) {
+            this.operationMetrics.get(operation).errorCount++;
+        }
+    }
+    /**
+     * Record a cache hit
+     */
+    recordCacheHit() {
+        this.cacheHits++;
+    }
+    /**
+     * Record a cache miss
+     */
+    recordCacheMiss() {
+        this.cacheMisses++;
+    }
+    /**
+     * Get a snapshot of all metrics
+     */
+    getMetrics() {
+        const operationTimes = {};
+        for (const [operation, metrics] of this.operationMetrics.entries()) {
+            operationTimes[operation] = {
+                count: metrics.count,
+                totalTime: metrics.totalTime,
+                avgTime: metrics.count > 0 ? metrics.totalTime / metrics.count : 0,
+                minTime: metrics.minTime === Infinity ? 0 : metrics.minTime,
+                maxTime: metrics.maxTime === -Infinity ? 0 : metrics.maxTime,
+                errorCount: metrics.errorCount
+            };
+        }
+        const assetsMigrated = {};
+        for (const [key, count] of this.assetsMigratedMap.entries()) {
+            assetsMigrated[key] = count;
+        }
+        const errors = {};
+        for (const [code, count] of this.errorCounts.entries()) {
+            errors[code] = count;
+        }
+        const totalCacheRequests = this.cacheHits + this.cacheMisses;
+        const cacheStats = totalCacheRequests > 0 ? {
+            hits: this.cacheHits,
+            misses: this.cacheMisses,
+            hitRate: this.cacheHits / totalCacheRequests
+        } : undefined;
+        return {
+            assetsCreated: this.assetsCreatedCount,
+            assetsMigrated,
+            assetsTransferred: this.assetsTransferredCount,
+            operationTimes,
+            errors,
+            cacheStats,
+            startTime: this.startTime,
+            uptime: Date.now() - new Date(this.startTime).getTime()
+        };
+    }
+    /**
+     * Get metrics for a specific operation
+     */
+    getOperationMetrics(operation) {
+        const metrics = this.operationMetrics.get(operation);
+        if (!metrics) {
+            return null;
+        }
+        return {
+            count: metrics.count,
+            totalTime: metrics.totalTime,
+            avgTime: metrics.count > 0 ? metrics.totalTime / metrics.count : 0,
+            minTime: metrics.minTime === Infinity ? 0 : metrics.minTime,
+            maxTime: metrics.maxTime === -Infinity ? 0 : metrics.maxTime,
+            errorCount: metrics.errorCount
+        };
+    }
+    /**
+     * Reset all metrics
+     */
+    reset() {
+        this.assetsCreatedCount = 0;
+        this.assetsMigratedMap.clear();
+        this.assetsTransferredCount = 0;
+        this.operationMetrics.clear();
+        this.errorCounts.clear();
+        this.cacheHits = 0;
+        this.cacheMisses = 0;
+    }
+    /**
+     * Export metrics in the specified format
+     */
+    export(format) {
+        if (format === 'json') {
+            return this.exportJSON();
+        }
+        else if (format === 'prometheus') {
+            return this.exportPrometheus();
+        }
+        throw new Error(`Unsupported export format: ${format}`);
+    }
+    /**
+     * Export metrics as JSON
+     */
+    exportJSON() {
+        return JSON.stringify(this.getMetrics(), null, 2);
+    }
+    /**
+     * Export metrics in Prometheus format
+     */
+    exportPrometheus() {
+        const lines = [];
+        const metrics = this.getMetrics();
+        // Asset metrics
+        lines.push('# HELP originals_assets_created_total Total number of assets created');
+        lines.push('# TYPE originals_assets_created_total counter');
+        lines.push(`originals_assets_created_total ${metrics.assetsCreated}`);
+        lines.push('');
+        lines.push('# HELP originals_assets_transferred_total Total number of assets transferred');
+        lines.push('# TYPE originals_assets_transferred_total counter');
+        lines.push(`originals_assets_transferred_total ${metrics.assetsTransferred}`);
+        lines.push('');
+        // Migration metrics
+        lines.push('# HELP originals_assets_migrated_total Total number of assets migrated by layer transition');
+        lines.push('# TYPE originals_assets_migrated_total counter');
+        for (const [transition, count] of Object.entries(metrics.assetsMigrated)) {
+            const [from, to] = transition.split('→');
+            lines.push(`originals_assets_migrated_total{from="${from}",to="${to}"} ${count}`);
+        }
+        lines.push('');
+        // Operation metrics
+        for (const [operation, opMetrics] of Object.entries(metrics.operationTimes)) {
+            const safeOpName = operation.replace(/[^a-zA-Z0-9_]/g, '_');
+            lines.push(`# HELP originals_operation_${safeOpName}_total Total number of ${operation} operations`);
+            lines.push(`# TYPE originals_operation_${safeOpName}_total counter`);
+            lines.push(`originals_operation_${safeOpName}_total ${opMetrics.count}`);
+            lines.push('');
+            lines.push(`# HELP originals_operation_${safeOpName}_duration_milliseconds Duration of ${operation} operations`);
+            lines.push(`# TYPE originals_operation_${safeOpName}_duration_milliseconds summary`);
+            lines.push(`originals_operation_${safeOpName}_duration_milliseconds{quantile="0.0"} ${opMetrics.minTime}`);
+            lines.push(`originals_operation_${safeOpName}_duration_milliseconds{quantile="0.5"} ${opMetrics.avgTime}`);
+            lines.push(`originals_operation_${safeOpName}_duration_milliseconds{quantile="1.0"} ${opMetrics.maxTime}`);
+            lines.push(`originals_operation_${safeOpName}_duration_milliseconds_sum ${opMetrics.totalTime}`);
+            lines.push(`originals_operation_${safeOpName}_duration_milliseconds_count ${opMetrics.count}`);
+            lines.push('');
+            lines.push(`# HELP originals_operation_${safeOpName}_errors_total Total number of errors in ${operation} operations`);
+            lines.push(`# TYPE originals_operation_${safeOpName}_errors_total counter`);
+            lines.push(`originals_operation_${safeOpName}_errors_total ${opMetrics.errorCount}`);
+            lines.push('');
+        }
+        // Error metrics
+        lines.push('# HELP originals_errors_total Total number of errors by code');
+        lines.push('# TYPE originals_errors_total counter');
+        for (const [code, count] of Object.entries(metrics.errors)) {
+            lines.push(`originals_errors_total{code="${code}"} ${count}`);
+        }
+        lines.push('');
+        // Cache metrics
+        if (metrics.cacheStats) {
+            lines.push('# HELP originals_cache_hits_total Total number of cache hits');
+            lines.push('# TYPE originals_cache_hits_total counter');
+            lines.push(`originals_cache_hits_total ${metrics.cacheStats.hits}`);
+            lines.push('');
+            lines.push('# HELP originals_cache_misses_total Total number of cache misses');
+            lines.push('# TYPE originals_cache_misses_total counter');
+            lines.push(`originals_cache_misses_total ${metrics.cacheStats.misses}`);
+            lines.push('');
+            lines.push('# HELP originals_cache_hit_rate Cache hit rate');
+            lines.push('# TYPE originals_cache_hit_rate gauge');
+            lines.push(`originals_cache_hit_rate ${metrics.cacheStats.hitRate}`);
+            lines.push('');
+        }
+        // System metrics
+        lines.push('# HELP originals_uptime_milliseconds SDK uptime in milliseconds');
+        lines.push('# TYPE originals_uptime_milliseconds gauge');
+        lines.push(`originals_uptime_milliseconds ${metrics.uptime}`);
+        lines.push('');
+        return lines.join('\n');
+    }
+}

package/dist/utils/bitcoin-address.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Bitcoin network types supported by the validation
+ */
+export type BitcoinNetwork = 'mainnet' | 'regtest' | 'signet';
+/**
+ * Validates a Bitcoin address format and checksum for the given network.
+ *
+ * This function uses bitcoinjs-lib's address.toOutputScript() which performs:
+ * - Format validation (bech32, base58check)
+ * - Checksum verification
+ * - Network prefix validation
+ *
+ * @param address - The Bitcoin address to validate
+ * @param network - The network to validate against ('mainnet', 'regtest', 'signet')
+ * @returns true if the address is valid for the network
+ * @throws Error with descriptive message if validation fails
+ *
+ * @example
+ * ```typescript
+ * // Valid mainnet address
+ * validateBitcoinAddress('bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq', 'mainnet'); // true
+ *
+ * // Invalid checksum
+ * validateBitcoinAddress('bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdd', 'mainnet'); // throws
+ *
+ * // Wrong network
+ * validateBitcoinAddress('bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq', 'testnet'); // throws
+ * ```
+ */
+export declare function validateBitcoinAddress(address: string, network: BitcoinNetwork): boolean;
+/**
+ * Validates a Bitcoin address and returns a boolean instead of throwing
+ *
+ * @param address - The Bitcoin address to validate
+ * @param network - The network to validate against
+ * @returns true if valid, false otherwise
+ */
+export declare function isValidBitcoinAddress(address: string, network: BitcoinNetwork): boolean;