@originals/sdk 1.1.0

package/src/events/EventEmitter.ts

@@ -0,0 +1,222 @@
+/**
+ * Type-safe EventEmitter for Originals SDK
+ * 
+ * Features:
+ * - Type-safe event emission and subscription
+ * - Support for both sync and async handlers
+ * - Error isolation (one failing handler doesn't affect others)
+ * - Event namespacing
+ * - Performance optimized (<1ms overhead per event)
+ */
+
+import type { OriginalsEvent, EventHandler, EventTypeMap } from './types';
+
+/**
+ * EventEmitter class for managing event subscriptions and emissions
+ */
+export class EventEmitter {
+  private handlers: Map<string, Set<EventHandler>> = new Map();
+  private onceHandlers: Map<string, Set<EventHandler>> = new Map();
+  
+  /**
+   * Subscribe to an event
+   * 
+   * @param eventType - The type of event to listen for
+   * @param handler - The handler function to call when the event is emitted
+   * @returns A function to unsubscribe the handler
+   * 
+   * @example
+   * ```typescript
+   * const unsubscribe = emitter.on('asset:created', (event) => {
+   *   console.log('Asset created:', event.asset.id);
+   * });
+   * 
+   * // Later, to unsubscribe:
+   * unsubscribe();
+   * ```
+   */
+  on<K extends keyof EventTypeMap>(
+    eventType: K,
+    handler: EventHandler<EventTypeMap[K]>
+  ): () => void {
+    if (!this.handlers.has(eventType)) {
+      this.handlers.set(eventType, new Set());
+    }
+    
+    this.handlers.get(eventType)!.add(handler as EventHandler);
+    
+    // Return unsubscribe function
+    return () => this.off(eventType, handler);
+  }
+  
+  /**
+   * Subscribe to an event for a single emission
+   * 
+   * @param eventType - The type of event to listen for
+   * @param handler - The handler function to call when the event is emitted (only once)
+   * @returns A function to unsubscribe the handler
+   * 
+   * @example
+   * ```typescript
+   * emitter.once('asset:migrated', (event) => {
+   *   console.log('Asset migrated once:', event.asset.id);
+   * });
+   * ```
+   */
+  once<K extends keyof EventTypeMap>(
+    eventType: K,
+    handler: EventHandler<EventTypeMap[K]>
+  ): () => void {
+    if (!this.onceHandlers.has(eventType)) {
+      this.onceHandlers.set(eventType, new Set());
+    }
+    
+    this.onceHandlers.get(eventType)!.add(handler as EventHandler);
+    
+    // Return unsubscribe function
+    return () => {
+      const handlers = this.onceHandlers.get(eventType);
+      if (handlers) {
+        handlers.delete(handler as EventHandler);
+      }
+    };
+  }
+  
+  /**
+   * Unsubscribe from an event
+   * 
+   * @param eventType - The type of event to stop listening for
+   * @param handler - The handler function to remove
+   * 
+   * @example
+   * ```typescript
+   * const handler = (event) => console.log(event);
+   * emitter.on('asset:created', handler);
+   * emitter.off('asset:created', handler);
+   * ```
+   */
+  off<K extends keyof EventTypeMap>(
+    eventType: K,
+    handler: EventHandler<EventTypeMap[K]>
+  ): void {
+    const handlers = this.handlers.get(eventType);
+    if (handlers) {
+      handlers.delete(handler as EventHandler);
+    }
+    
+    const onceHandlers = this.onceHandlers.get(eventType);
+    if (onceHandlers) {
+      onceHandlers.delete(handler as EventHandler);
+    }
+  }
+  
+  /**
+   * Emit an event to all subscribed handlers
+   * 
+   * @param event - The event to emit
+   * 
+   * Features:
+   * - Handlers are called in subscription order
+   * - Async handlers are awaited
+   * - Errors in handlers are isolated (logged but don't affect other handlers)
+   * - Once handlers are automatically removed after execution
+   * 
+   * @example
+   * ```typescript
+   * emitter.emit({
+   *   type: 'asset:created',
+   *   timestamp: new Date().toISOString(),
+   *   asset: { id: 'did:peer:123', layer: 'did:peer', resourceCount: 1 }
+   * });
+   * ```
+   */
+  async emit<K extends keyof EventTypeMap>(event: EventTypeMap[K]): Promise<void> {
+    const eventType = event.type as K;
+    
+    // Get regular handlers
+    const handlers = this.handlers.get(eventType);
+    if (handlers && handlers.size > 0) {
+      // Create array to avoid modification during iteration
+      const handlerArray = Array.from(handlers);
+      
+      for (const handler of handlerArray) {
+        try {
+          await handler(event as OriginalsEvent);
+        } catch (error) {
+          // Error isolation: log but don't throw
+          // This ensures one failing handler doesn't affect others
+          if (typeof console !== 'undefined' && console.error) {
+            console.error(`Event handler error for ${eventType}:`, error);
+          }
+        }
+      }
+    }
+    
+    // Get and execute once handlers
+    const onceHandlers = this.onceHandlers.get(eventType);
+    if (onceHandlers && onceHandlers.size > 0) {
+      // Create array to avoid modification during iteration
+      const onceHandlerArray = Array.from(onceHandlers);
+      
+      // Clear once handlers before execution
+      this.onceHandlers.delete(eventType);
+      
+      for (const handler of onceHandlerArray) {
+        try {
+          await handler(event as OriginalsEvent);
+        } catch (error) {
+          // Error isolation: log but don't throw
+          if (typeof console !== 'undefined' && console.error) {
+            console.error(`Event handler error (once) for ${eventType}:`, error);
+          }
+        }
+      }
+    }
+  }
+  
+  /**
+   * Remove all handlers for a specific event type, or all handlers if no type specified
+   * 
+   * @param eventType - Optional event type to clear handlers for
+   * 
+   * @example
+   * ```typescript
+   * // Remove all handlers for 'asset:created'
+   * emitter.removeAllListeners('asset:created');
+   * 
+   * // Remove all handlers for all events
+   * emitter.removeAllListeners();
+   * ```
+   */
+  removeAllListeners<K extends keyof EventTypeMap>(eventType?: K): void {
+    if (eventType) {
+      this.handlers.delete(eventType);
+      this.onceHandlers.delete(eventType);
+    } else {
+      this.handlers.clear();
+      this.onceHandlers.clear();
+    }
+  }
+  
+  /**
+   * Get the number of handlers for a specific event type
+   * 
+   * @param eventType - The event type to check
+   * @returns The number of handlers subscribed to this event type
+   */
+  listenerCount<K extends keyof EventTypeMap>(eventType: K): number {
+    const handlers = this.handlers.get(eventType);
+    const onceHandlers = this.onceHandlers.get(eventType);
+    return (handlers?.size || 0) + (onceHandlers?.size || 0);
+  }
+  
+  /**
+   * Check if there are any handlers for a specific event type
+   * 
+   * @param eventType - The event type to check
+   * @returns True if there are any handlers subscribed
+   */
+  hasListeners<K extends keyof EventTypeMap>(eventType: K): boolean {
+    return this.listenerCount(eventType) > 0;
+  }
+}

package/src/events/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Events module for the Originals SDK
+ * 
+ * Provides a type-safe event system for tracking asset lifecycle operations
+ */
+
+export { EventEmitter } from './EventEmitter';
+export type {
+  BaseEvent,
+  AssetCreatedEvent,
+  AssetMigratedEvent,
+  AssetTransferredEvent,
+  ResourcePublishedEvent,
+  CredentialIssuedEvent,
+  VerificationCompletedEvent,
+  OriginalsEvent,
+  EventHandler,
+  EventTypeMap
+} from './types';

package/src/events/types.ts

@@ -0,0 +1,331 @@
+/**
+ * Event types for the Originals SDK asset lifecycle operations
+ * 
+ * All events follow a consistent structure:
+ * - type: Namespaced event name (e.g., 'asset:created')
+ * - timestamp: ISO 8601 timestamp of when the event occurred
+ * - Specific payload data relevant to the event
+ */
+
+import { LayerType } from '../types';
+
+/**
+ * Base event interface that all events extend
+ */
+export interface BaseEvent {
+  type: string;
+  timestamp: string;
+}
+
+/**
+ * Emitted when a new asset is created
+ */
+export interface AssetCreatedEvent extends BaseEvent {
+  type: 'asset:created';
+  asset: {
+    id: string;
+    layer: LayerType;
+    resourceCount: number;
+    createdAt: string;
+  };
+}
+
+/**
+ * Emitted when an asset migrates between layers
+ * 
+ * Note: The `details` field is populated differently based on the target layer:
+ * - For did:webvh migrations: `details` is undefined (web publishing has no transaction details)
+ * - For did:btco migrations: `details` includes Bitcoin transaction information
+ *   (transactionId, inscriptionId, satoshi, commitTxId, revealTxId, feeRate)
+ */
+export interface AssetMigratedEvent extends BaseEvent {
+  type: 'asset:migrated';
+  asset: {
+    id: string;
+    fromLayer: LayerType;
+    toLayer: LayerType;
+  };
+  details?: {
+    transactionId?: string;
+    inscriptionId?: string;
+    satoshi?: string;
+    commitTxId?: string;
+    revealTxId?: string;
+    feeRate?: number;
+  };
+}
+
+/**
+ * Emitted when an asset's ownership is transferred
+ */
+export interface AssetTransferredEvent extends BaseEvent {
+  type: 'asset:transferred';
+  asset: {
+    id: string;
+    layer: LayerType;
+  };
+  from: string;
+  to: string;
+  transactionId: string;
+}
+
+/**
+ * Emitted when a resource is published to web storage
+ */
+export interface ResourcePublishedEvent extends BaseEvent {
+  type: 'resource:published';
+  asset: {
+    id: string;
+  };
+  resource: {
+    id: string;
+    url: string;
+    contentType: string;
+    hash: string;
+  };
+  publisherDid: string;
+}
+
+/**
+ * Emitted when a verifiable credential is issued for an asset
+ */
+export interface CredentialIssuedEvent extends BaseEvent {
+  type: 'credential:issued';
+  asset: {
+    id: string;
+  };
+  credential: {
+    type: string[];
+    issuer: string;
+  };
+}
+
+/**
+ * Emitted when a new resource version is created
+ */
+export interface ResourceVersionCreatedEvent extends BaseEvent {
+  type: 'resource:version:created';
+  asset: {
+    id: string;
+  };
+  resource: {
+    id: string;
+    fromVersion: number;
+    toVersion: number;
+    fromHash: string;
+    toHash: string;
+  };
+  changes?: string;
+}
+
+/**
+ * Emitted when asset verification is completed
+ */
+export interface VerificationCompletedEvent extends BaseEvent {
+  type: 'verification:completed';
+  asset: {
+    id: string;
+  };
+  result: boolean;
+  checks?: {
+    didDocument: boolean;
+    resources: boolean;
+    credentials: boolean;
+  };
+}
+
+/**
+ * Emitted when a batch operation starts
+ */
+export interface BatchStartedEvent extends BaseEvent {
+  type: 'batch:started';
+  operation: 'create' | 'publish' | 'inscribe' | 'transfer';
+  batchId: string;
+  itemCount: number;
+}
+
+/**
+ * Emitted when a batch operation completes successfully
+ */
+export interface BatchCompletedEvent extends BaseEvent {
+  type: 'batch:completed';
+  batchId: string;
+  operation: string;
+  results: {
+    successful: number;
+    failed: number;
+    totalDuration: number;
+    costSavings?: {
+      amount: number;
+      percentage: number;
+    };
+  };
+}
+
+/**
+ * Emitted when a batch operation fails
+ */
+export interface BatchFailedEvent extends BaseEvent {
+  type: 'batch:failed';
+  batchId: string;
+  operation: string;
+  error: string;
+  partialResults?: {
+    successful: number;
+    failed: number;
+  };
+}
+
+/**
+ * Emitted when a migration starts
+ */
+export interface MigrationStartedEvent extends BaseEvent {
+  type: 'migration:started';
+  migrationId: string;
+  sourceDid: string;
+  targetLayer: string;
+}
+
+/**
+ * Emitted when migration validation completes
+ */
+export interface MigrationValidatedEvent extends BaseEvent {
+  type: 'migration:validated';
+  migrationId: string;
+  valid: boolean;
+}
+
+/**
+ * Emitted when migration checkpoint is created
+ */
+export interface MigrationCheckpointedEvent extends BaseEvent {
+  type: 'migration:checkpointed';
+  migrationId: string;
+  checkpointId: string;
+}
+
+/**
+ * Emitted when migration enters in-progress state
+ */
+export interface MigrationInProgressEvent extends BaseEvent {
+  type: 'migration:in_progress';
+  migrationId: string;
+  currentOperation: string;
+  progress: number;
+}
+
+/**
+ * Emitted when migration enters anchoring state (Bitcoin)
+ */
+export interface MigrationAnchoringEvent extends BaseEvent {
+  type: 'migration:anchoring';
+  migrationId: string;
+  transactionId?: string;
+}
+
+/**
+ * Emitted when migration completes successfully
+ */
+export interface MigrationCompletedEvent extends BaseEvent {
+  type: 'migration:completed';
+  migrationId: string;
+  sourceDid: string;
+  targetDid: string;
+}
+
+/**
+ * Emitted when migration fails
+ */
+export interface MigrationFailedEvent extends BaseEvent {
+  type: 'migration:failed';
+  migrationId: string;
+  error: any;
+}
+
+/**
+ * Emitted when migration is rolled back
+ */
+export interface MigrationRolledbackEvent extends BaseEvent {
+  type: 'migration:rolledback';
+  migrationId: string;
+  checkpointId: string;
+}
+
+/**
+ * Emitted when migration enters quarantine state
+ */
+export interface MigrationQuarantineEvent extends BaseEvent {
+  type: 'migration:quarantine';
+  migrationId: string;
+  checkpointId: string;
+  reason: string;
+}
+
+/**
+ * Emitted during batch operations to report progress
+ */
+export interface BatchProgressEvent extends BaseEvent {
+  type: 'batch:progress';
+  batchId: string;
+  operation: string;
+  progress: number;
+  completed: number;
+  failed: number;
+  total: number;
+}
+
+/**
+ * Union type of all possible events
+ */
+export type OriginalsEvent =
+  | AssetCreatedEvent
+  | AssetMigratedEvent
+  | AssetTransferredEvent
+  | ResourcePublishedEvent
+  | CredentialIssuedEvent
+  | VerificationCompletedEvent
+  | BatchStartedEvent
+  | BatchCompletedEvent
+  | BatchFailedEvent
+  | BatchProgressEvent
+  | ResourceVersionCreatedEvent
+  | MigrationStartedEvent
+  | MigrationValidatedEvent
+  | MigrationCheckpointedEvent
+  | MigrationInProgressEvent
+  | MigrationAnchoringEvent
+  | MigrationCompletedEvent
+  | MigrationFailedEvent
+  | MigrationRolledbackEvent
+  | MigrationQuarantineEvent;
+
+/**
+ * Event handler function type
+ */
+export type EventHandler<T extends OriginalsEvent = OriginalsEvent> = (event: T) => void | Promise<void>;
+
+/**
+ * Map of event types to their specific event interfaces
+ */
+export interface EventTypeMap {
+  'asset:created': AssetCreatedEvent;
+  'asset:migrated': AssetMigratedEvent;
+  'asset:transferred': AssetTransferredEvent;
+  'resource:published': ResourcePublishedEvent;
+  'credential:issued': CredentialIssuedEvent;
+  'verification:completed': VerificationCompletedEvent;
+  'batch:started': BatchStartedEvent;
+  'batch:completed': BatchCompletedEvent;
+  'batch:failed': BatchFailedEvent;
+  'batch:progress': BatchProgressEvent;
+  'resource:version:created': ResourceVersionCreatedEvent;
+  'migration:started': MigrationStartedEvent;
+  'migration:validated': MigrationValidatedEvent;
+  'migration:checkpointed': MigrationCheckpointedEvent;
+  'migration:in_progress': MigrationInProgressEvent;
+  'migration:anchoring': MigrationAnchoringEvent;
+  'migration:completed': MigrationCompletedEvent;
+  'migration:failed': MigrationFailedEvent;
+  'migration:rolledback': MigrationRolledbackEvent;
+  'migration:quarantine': MigrationQuarantineEvent;
+}

package/src/examples/basic-usage.ts

@@ -0,0 +1,78 @@
+import { OriginalsSDK } from '../index';
+
+async function basicExample() {
+  const sdk = OriginalsSDK.create({
+    network: 'regtest',
+    enableLogging: true,
+    // Example uses defaults; provide adapters in your app or tests
+    telemetry: {
+      onEvent: (e) => console.log('[telemetry]', e.name, e.attributes || {}),
+      onError: (err) => console.warn('[error]', err.code, err.message)
+    }
+  });
+
+  // Create new digital asset
+  const resources = [{
+    id: 'image-1',
+    type: 'image',
+    content: 'base64-encoded-image-data',
+    contentType: 'image/png',
+    hash: 'sha256-hash'
+  }];
+
+  try {
+    // Create asset in did:peer layer (private, offline)
+    const asset = await sdk.lifecycle.createAsset(resources);
+    console.log('Created asset:', asset.id);
+    console.log('Current layer:', asset.currentLayer); // 'did:peer'
+    
+    // Publish to web for discovery (did:webvh layer)
+    await sdk.lifecycle.publishToWeb(asset, 'example.com');
+    console.log('Published to web, current layer:', asset.currentLayer); // 'did:webvh'
+    
+    // Inscribe on Bitcoin for permanent ownership (did:btco layer)
+    await sdk.lifecycle.inscribeOnBitcoin(asset);
+    console.log('Inscribed on Bitcoin, current layer:', asset.currentLayer); // 'did:btco'
+    
+    // Get full provenance chain
+    const provenance = asset.getProvenance();
+    console.log('Provenance:', provenance);
+    
+    // Verify asset integrity
+    const isValid = await asset.verify();
+    console.log('Asset is valid:', isValid);
+    
+  } catch (error) {
+    console.error('Error:', error);
+  }
+}
+
+async function digitalArtExample() {
+  const sdk = OriginalsSDK.create();
+  
+  // Artist creates digital artwork
+  const artwork = [{
+    id: 'artwork-001',
+    type: 'image', 
+    url: 'https://artist-site.com/my-artwork.jpg',
+    contentType: 'image/jpeg',
+    hash: 'abcd1234...' // SHA-256 hash of image
+  }];
+  
+  // Create private version for experimentation
+  const asset = await sdk.lifecycle.createAsset(artwork);
+  
+  // Make discoverable when ready
+  await sdk.lifecycle.publishToWeb(asset, 'artist-gallery.com');
+  
+  // Inscribe on Bitcoin when sold
+  await sdk.lifecycle.inscribeOnBitcoin(asset);
+  
+  // Transfer to buyer
+  await sdk.lifecycle.transferOwnership(asset, 'buyer-address');
+}
+
+// Export examples
+export { basicExample, digitalArtExample };
+
+

package/src/examples/run.ts

@@ -0,0 +1,5 @@
+import { basicExample } from './basic-usage';
+import { digitalArtExample } from './basic-usage';
+
+basicExample();
+digitalArtExample();