@originals/sdk 1.4.3 → 1.5.0

package/dist/types/network.js

@@ -0,0 +1,145 @@
+/**
+ * WebVH Network Configuration
+ *
+ * Defines the three deployment networks for the Originals Protocol:
+ * - magby: Development network (patch versions) → Bitcoin regtest
+ * - cleffa: Staging network (minor versions) → Bitcoin signet
+ * - pichu: Production network (major versions) → Bitcoin mainnet
+ */
+/**
+ * Network configurations for the Originals Protocol WebVH deployments
+ */
+export const WEBVH_NETWORKS = {
+    magby: {
+        name: 'magby',
+        domain: 'magby.originals.build',
+        stability: 'patch',
+        description: 'Development network - accepts all patch versions (most unstable)',
+        contextUrl: 'https://magby.originals.build/context',
+        bitcoinNetwork: 'regtest', // Development → regtest
+    },
+    cleffa: {
+        name: 'cleffa',
+        domain: 'cleffa.originals.build',
+        stability: 'minor',
+        description: 'Staging network - accepts minor releases',
+        contextUrl: 'https://cleffa.originals.build/context',
+        bitcoinNetwork: 'signet', // Staging → signet
+    },
+    pichu: {
+        name: 'pichu',
+        domain: 'pichu.originals.build',
+        stability: 'major',
+        description: 'Production network - accepts major releases only (most stable)',
+        contextUrl: 'https://pichu.originals.build/context',
+        bitcoinNetwork: 'mainnet', // Production → mainnet
+    },
+};
+/**
+ * Default network for backward compatibility
+ */
+export const DEFAULT_WEBVH_NETWORK = 'pichu';
+/**
+ * Get network configuration by name
+ * @param network - Network name
+ * @returns Network configuration
+ */
+export function getNetworkConfig(network) {
+    const config = WEBVH_NETWORKS[network];
+    if (!config) {
+        throw new Error(`Invalid WebVH network: ${network}. Valid networks: magby, cleffa, pichu`);
+    }
+    return config;
+}
+/**
+ * Get network domain
+ * @param network - Network name
+ * @returns Network domain
+ */
+export function getNetworkDomain(network) {
+    return getNetworkConfig(network).domain;
+}
+/**
+ * Get network context URL
+ * @param network - Network name
+ * @returns Context URL for the network
+ */
+export function getNetworkContextUrl(network) {
+    return getNetworkConfig(network).contextUrl;
+}
+/**
+ * Validate that a version string matches the network's stability requirements
+ * @param version - Semver version string (e.g., "1.2.3")
+ * @param network - Network name
+ * @returns True if the version is allowed on this network
+ */
+export function validateVersionForNetwork(version, network) {
+    const config = getNetworkConfig(network);
+    // Parse semver (basic parsing, assumes format X.Y.Z)
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)(?:-.*)?$/);
+    if (!match) {
+        throw new Error(`Invalid version format: ${version}. Expected semver format (e.g., 1.2.3)`);
+    }
+    const [, major, minor, patch] = match;
+    switch (config.stability) {
+        case 'major':
+            // Pichu: Only allow major releases (X.0.0)
+            return minor === '0' && patch === '0';
+        case 'minor':
+            // Cleffa: Allow minor releases (X.Y.0)
+            return patch === '0';
+        case 'patch':
+            // Magby: Allow all versions including patches
+            return true;
+        default:
+            throw new Error(`Unknown stability level: ${config.stability}`);
+    }
+}
+/**
+ * Get the appropriate network for a given version
+ * Returns the most restrictive network that accepts this version
+ * @param version - Semver version string
+ * @returns Recommended network name
+ */
+export function getRecommendedNetworkForVersion(version) {
+    // Try networks from most restrictive to least restrictive
+    if (validateVersionForNetwork(version, 'pichu')) {
+        return 'pichu';
+    }
+    if (validateVersionForNetwork(version, 'cleffa')) {
+        return 'cleffa';
+    }
+    return 'magby';
+}
+/**
+ * Get the corresponding Bitcoin network for a WebVH network
+ * This ensures consistent environment mapping across the stack:
+ * - magby (dev) → regtest (dev)
+ * - cleffa (staging) → signet (staging)
+ * - pichu (production) → mainnet (production)
+ *
+ * @param webvhNetwork - WebVH network name
+ * @returns Corresponding Bitcoin network name
+ */
+export function getBitcoinNetworkForWebVH(webvhNetwork) {
+    return getNetworkConfig(webvhNetwork).bitcoinNetwork;
+}
+/**
+ * Get the WebVH network that corresponds to a Bitcoin network
+ * This is the reverse mapping of getBitcoinNetworkForWebVH
+ *
+ * @param bitcoinNetwork - Bitcoin network name
+ * @returns Corresponding WebVH network name, or undefined if no mapping exists
+ */
+export function getWebVHNetworkForBitcoin(bitcoinNetwork) {
+    switch (bitcoinNetwork) {
+        case 'mainnet':
+            return 'pichu';
+        case 'signet':
+            return 'cleffa';
+        case 'regtest':
+            return 'magby';
+        default:
+            return undefined;
+    }
+}

package/dist/utils/EventLogger.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Event Logger - Integration between Event System and Logger
+ *
+ * Features:
+ * - Auto-subscribe to EventEmitter events
+ * - Configurable logging levels per event type
+ * - Automatic metrics extraction from events
+ * - Performance tracking
+ */
+import type { EventEmitter } from '../events/EventEmitter';
+import type { Logger, LogLevel } from './Logger';
+import type { MetricsCollector } from './MetricsCollector';
+/**
+ * Event logging configuration
+ */
+export interface EventLoggingConfig {
+    'asset:created'?: LogLevel | false;
+    'asset:migrated'?: LogLevel | false;
+    'asset:transferred'?: LogLevel | false;
+    'resource:published'?: LogLevel | false;
+    'credential:issued'?: LogLevel | false;
+    'resource:version:created'?: LogLevel | false;
+    'verification:completed'?: LogLevel | false;
+    'batch:started'?: LogLevel | false;
+    'batch:completed'?: LogLevel | false;
+    'batch:failed'?: LogLevel | false;
+    'migration:started'?: LogLevel | false;
+    'migration:validated'?: LogLevel | false;
+    'migration:checkpointed'?: LogLevel | false;
+    'migration:in_progress'?: LogLevel | false;
+    'migration:anchoring'?: LogLevel | false;
+    'migration:completed'?: LogLevel | false;
+    'migration:failed'?: LogLevel | false;
+    'migration:rolledback'?: LogLevel | false;
+    'migration:quarantine'?: LogLevel | false;
+    'batch:progress'?: LogLevel | false;
+}
+/**
+ * EventLogger class for integrating events with logging and metrics
+ */
+export declare class EventLogger {
+    private logger;
+    private metricsCollector;
+    private config;
+    private unsubscribeFns;
+    constructor(logger: Logger, metricsCollector: MetricsCollector);
+    /**
+     * Subscribe to all events from an EventEmitter
+     */
+    subscribeToEvents(eventEmitter: EventEmitter): void;
+    /**
+     * Configure which events to log at which levels
+     */
+    configureEventLogging(config: EventLoggingConfig): void;
+    /**
+     * Unsubscribe from all events
+     */
+    unsubscribe(): void;
+    /**
+     * Handle an event - log and extract metrics
+     */
+    private handleEvent;
+    /**
+     * Log an event at the specified level
+     */
+    private logEvent;
+    /**
+     * Extract metrics from an event
+     */
+    private extractMetrics;
+}

package/dist/utils/EventLogger.js

@@ -0,0 +1,232 @@
+/**
+ * Event Logger - Integration between Event System and Logger
+ *
+ * Features:
+ * - Auto-subscribe to EventEmitter events
+ * - Configurable logging levels per event type
+ * - Automatic metrics extraction from events
+ * - Performance tracking
+ */
+/**
+ * Default event logging configuration
+ */
+const DEFAULT_EVENT_CONFIG = {
+    'asset:created': 'info',
+    'asset:migrated': 'info',
+    'asset:transferred': 'info',
+    'resource:published': 'info',
+    'credential:issued': 'info',
+    'resource:version:created': 'info',
+    'verification:completed': 'info',
+    'batch:started': 'info',
+    'batch:completed': 'info',
+    'batch:failed': 'warn',
+    'migration:started': 'info',
+    'migration:validated': 'info',
+    'migration:checkpointed': 'info',
+    'migration:in_progress': 'info',
+    'migration:anchoring': 'info',
+    'migration:completed': 'info',
+    'migration:failed': 'warn',
+    'migration:rolledback': 'warn',
+    'migration:quarantine': 'error',
+    'batch:progress': 'debug'
+};
+/**
+ * EventLogger class for integrating events with logging and metrics
+ */
+export class EventLogger {
+    constructor(logger, metricsCollector) {
+        this.logger = logger;
+        this.metricsCollector = metricsCollector;
+        this.unsubscribeFns = [];
+        this.config = { ...DEFAULT_EVENT_CONFIG };
+    }
+    /**
+     * Subscribe to all events from an EventEmitter
+     */
+    subscribeToEvents(eventEmitter) {
+        // Subscribe to each event type
+        const eventTypes = [
+            'asset:created',
+            'asset:migrated',
+            'asset:transferred',
+            'resource:published',
+            'credential:issued',
+            'resource:version:created',
+            'verification:completed',
+            'batch:started',
+            'batch:completed',
+            'batch:failed'
+        ];
+        for (const eventType of eventTypes) {
+            const unsubscribe = eventEmitter.on(eventType, (event) => {
+                this.handleEvent(event);
+            });
+            this.unsubscribeFns.push(unsubscribe);
+        }
+    }
+    /**
+     * Configure which events to log at which levels
+     */
+    configureEventLogging(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Unsubscribe from all events
+     */
+    unsubscribe() {
+        for (const unsubscribe of this.unsubscribeFns) {
+            unsubscribe();
+        }
+        this.unsubscribeFns = [];
+    }
+    /**
+     * Handle an event - log and extract metrics
+     */
+    handleEvent(event) {
+        const eventType = event.type;
+        const logLevel = this.config[eventType];
+        // Always extract metrics from the event (even if logging is disabled)
+        this.extractMetrics(event);
+        // Skip logging if disabled for this event type
+        if (logLevel === false) {
+            return;
+        }
+        // Log the event
+        if (logLevel) {
+            this.logEvent(event, logLevel);
+        }
+    }
+    /**
+     * Log an event at the specified level
+     */
+    logEvent(event, level) {
+        let message;
+        let data;
+        switch (event.type) {
+            case 'asset:created':
+                message = 'Asset created';
+                data = {
+                    assetId: event.asset.id,
+                    layer: event.asset.layer,
+                    resourceCount: event.asset.resourceCount
+                };
+                break;
+            case 'asset:migrated':
+                message = 'Asset migrated';
+                data = {
+                    assetId: event.asset.id,
+                    fromLayer: event.asset.fromLayer,
+                    toLayer: event.asset.toLayer,
+                    details: event.details
+                };
+                break;
+            case 'asset:transferred':
+                message = 'Asset transferred';
+                data = {
+                    assetId: event.asset.id,
+                    layer: event.asset.layer,
+                    from: event.from,
+                    to: event.to,
+                    transactionId: event.transactionId
+                };
+                break;
+            case 'resource:published':
+                message = 'Resource published';
+                data = {
+                    assetId: event.asset.id,
+                    resourceId: event.resource.id,
+                    url: event.resource.url,
+                    publisherDid: event.publisherDid
+                };
+                break;
+            case 'credential:issued':
+                message = 'Credential issued';
+                data = {
+                    assetId: event.asset.id,
+                    credentialType: event.credential.type,
+                    issuer: event.credential.issuer
+                };
+                break;
+            case 'resource:version:created':
+                message = 'Resource version created';
+                data = {
+                    assetId: event.asset.id,
+                    resourceId: event.resource.id,
+                    fromVersion: event.resource.fromVersion,
+                    toVersion: event.resource.toVersion,
+                    changes: event.changes
+                };
+                break;
+            case 'verification:completed':
+                message = 'Verification completed';
+                data = {
+                    assetId: event.asset.id,
+                    result: event.result,
+                    checks: event.checks
+                };
+                break;
+            case 'batch:started':
+                message = 'Batch operation started';
+                data = {
+                    batchId: event.batchId,
+                    operation: event.operation,
+                    itemCount: event.itemCount
+                };
+                break;
+            case 'batch:completed':
+                message = 'Batch operation completed';
+                data = {
+                    batchId: event.batchId,
+                    operation: event.operation,
+                    results: event.results
+                };
+                break;
+            case 'batch:failed':
+                message = 'Batch operation failed';
+                data = {
+                    batchId: event.batchId,
+                    operation: event.operation,
+                    error: event.error,
+                    partialResults: event.partialResults
+                };
+                break;
+            default:
+                return; // Unknown event type
+        }
+        // Call the appropriate log method based on level
+        switch (level) {
+            case 'debug':
+                this.logger.debug(message, data);
+                break;
+            case 'info':
+                this.logger.info(message, data);
+                break;
+            case 'warn':
+                this.logger.warn(message, data);
+                break;
+            case 'error':
+                this.logger.error(message, undefined, data);
+                break;
+        }
+    }
+    /**
+     * Extract metrics from an event
+     */
+    extractMetrics(event) {
+        switch (event.type) {
+            case 'asset:created':
+                this.metricsCollector.recordAssetCreated();
+                break;
+            case 'asset:migrated':
+                this.metricsCollector.recordMigration(event.asset.fromLayer, event.asset.toLayer);
+                break;
+            case 'asset:transferred':
+                this.metricsCollector.recordTransfer();
+                break;
+            // Other events don't need explicit metric recording
+            // as they're tracked elsewhere
+        }
+    }
+}

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