@originals/sdk 1.8.1 → 1.8.2

package/src/types/index.ts

@@ -0,0 +1,7 @@
+export * from './common';
+export * from './did';
+export * from './credentials';
+export * from './bitcoin';
+export * from './network';
+
+

package/src/types/network.ts

@@ -0,0 +1,178 @@
+/**
+ * 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
+ */
+
+export type WebVHNetworkName = 'magby' | 'cleffa' | 'pichu';
+
+export type BitcoinNetworkName = 'mainnet' | 'regtest' | 'signet';
+
+export type VersionStability = 'patch' | 'minor' | 'major';
+
+export interface WebVHNetworkConfig {
+  name: WebVHNetworkName;
+  domain: string;
+  stability: VersionStability;
+  description: string;
+  contextUrl: string;
+  bitcoinNetwork: BitcoinNetworkName; // Corresponding Bitcoin network for did:btco migrations
+}
+
+/**
+ * Network configurations for the Originals Protocol WebVH deployments
+ */
+export const WEBVH_NETWORKS: Record<WebVHNetworkName, WebVHNetworkConfig> = {
+  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: WebVHNetworkName = 'pichu';
+
+/**
+ * Get network configuration by name
+ * @param network - Network name
+ * @returns Network configuration
+ */
+export function getNetworkConfig(network: WebVHNetworkName): WebVHNetworkConfig {
+  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: WebVHNetworkName): string {
+  return getNetworkConfig(network).domain;
+}
+
+/**
+ * Get network context URL
+ * @param network - Network name
+ * @returns Context URL for the network
+ */
+export function getNetworkContextUrl(network: WebVHNetworkName): string {
+  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: string, network: WebVHNetworkName): boolean {
+  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 [, , 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: {
+      // TypeScript exhaustiveness check
+      const _exhaustive: never = config.stability;
+      throw new Error(`Unknown stability level: ${String(_exhaustive)}`);
+    }
+  }
+}
+
+/**
+ * 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: string): WebVHNetworkName {
+  // 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: WebVHNetworkName): BitcoinNetworkName {
+  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: BitcoinNetworkName): WebVHNetworkName | undefined {
+  switch (bitcoinNetwork) {
+    case 'mainnet':
+      return 'pichu';
+    case 'signet':
+      return 'cleffa';
+    case 'regtest':
+      return 'magby';
+    default:
+      return undefined;
+  }
+}

package/src/utils/EventLogger.ts

@@ -0,0 +1,298 @@
+/**
+ * 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 { OriginalsEvent, EventTypeMap } from '../events/types';
+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;
+}
+
+/**
+ * Default event logging configuration
+ */
+const DEFAULT_EVENT_CONFIG: EventLoggingConfig = {
+  '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 {
+  private config: EventLoggingConfig;
+  private unsubscribeFns: Array<() => void> = [];
+  
+  constructor(
+    private logger: Logger,
+    private metricsCollector: MetricsCollector
+  ) {
+    this.config = { ...DEFAULT_EVENT_CONFIG };
+  }
+  
+  /**
+   * Subscribe to all events from an EventEmitter
+   */
+  subscribeToEvents(eventEmitter: EventEmitter): void {
+    // Subscribe to each event type
+    const eventTypes: Array<keyof EventTypeMap> = [
+      '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: EventLoggingConfig): void {
+    this.config = { ...this.config, ...config };
+  }
+  
+  /**
+   * Unsubscribe from all events
+   */
+  unsubscribe(): void {
+    for (const unsubscribe of this.unsubscribeFns) {
+      unsubscribe();
+    }
+    this.unsubscribeFns = [];
+  }
+  
+  /**
+   * Handle an event - log and extract metrics
+   */
+  private handleEvent(event: OriginalsEvent): void {
+    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
+   */
+  private logEvent(event: OriginalsEvent, level: LogLevel): void {
+    let message: string;
+    let data: Record<string, unknown>;
+    
+    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
+   */
+  private extractMetrics(event: OriginalsEvent): void {
+    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
+    }
+  }
+}
+