@originals/sdk 1.4.2 → 1.4.5

package/src/events/EventEmitter.ts

@@ -1,222 +0,0 @@
-/**
- * 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

@@ -1,19 +0,0 @@
-/**
- * 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

@@ -1,331 +0,0 @@
-/**
- * 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

@@ -1,78 +0,0 @@
-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 };
-
-