@originals/sdk 1.1.0

package/dist/utils/Logger.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 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
+ */
+import type { OriginalsConfig } from '../types';
+/**
+ * Log level type
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Structured log entry
+ */
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    context: string;
+    message: string;
+    data?: any;
+    duration?: number;
+    traceId?: string;
+}
+/**
+ * Log output interface for custom outputs
+ */
+export interface LogOutput {
+    write(entry: LogEntry): void | Promise<void>;
+}
+/**
+ * Console log output implementation
+ */
+export declare class ConsoleLogOutput implements LogOutput {
+    write(entry: LogEntry): void;
+}
+/**
+ * File log output implementation (async)
+ */
+export declare class FileLogOutput implements LogOutput {
+    private filePath;
+    private buffer;
+    private flushTimeout;
+    private readonly flushInterval;
+    constructor(filePath: string);
+    write(entry: LogEntry): Promise<void>;
+    private flush;
+}
+/**
+ * Main Logger class
+ */
+export declare class Logger {
+    private context;
+    private outputs;
+    private minLevel;
+    private includeTimestamps;
+    private includeContext;
+    private sanitizeLogs;
+    private static readonly LEVEL_PRIORITY;
+    constructor(context: string, config: OriginalsConfig);
+    /**
+     * Log a debug message
+     */
+    debug(message: string, data?: any): void;
+    /**
+     * Log an info message
+     */
+    info(message: string, data?: any): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, data?: any): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, error?: Error, data?: any): void;
+    /**
+     * Start a timer for performance tracking
+     * Returns a function that stops the timer and logs the duration
+     */
+    startTimer(operation: string): () => void;
+    /**
+     * Create a child logger with nested context
+     */
+    child(childContext: string): Logger;
+    /**
+     * Set a single output (replaces existing outputs)
+     */
+    setOutput(output: LogOutput): void;
+    /**
+     * Add an output to the existing outputs
+     */
+    addOutput(output: LogOutput): void;
+    /**
+     * Internal log method
+     */
+    private log;
+    /**
+     * Sanitize sensitive data from logs
+     */
+    private sanitize;
+}

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;
+}