@originals/sdk 1.4.2 → 1.4.5

package/dist/lifecycle/LifecycleManager.d.ts

@@ -0,0 +1,362 @@
+import { OriginalsConfig, AssetResource, BitcoinTransaction, KeyStore, ExternalSigner, LayerType } from '../types';
+import { BitcoinManager } from '../bitcoin/BitcoinManager';
+import { DIDManager } from '../did/DIDManager';
+import { CredentialManager } from '../vc/CredentialManager';
+import { OriginalsAsset } from './OriginalsAsset';
+import type { EventHandler, EventTypeMap } from '../events/types';
+import { type BatchResult, type BatchOperationOptions, type BatchInscriptionOptions } from './BatchOperations';
+import { type OriginalKind, type OriginalManifest, type CreateTypedOriginalOptions } from '../kinds';
+/**
+ * Cost estimation result for migration operations
+ */
+export interface CostEstimate {
+    /** Total estimated cost in satoshis */
+    totalSats: number;
+    /** Breakdown of costs */
+    breakdown: {
+        /** Network fee in satoshis */
+        networkFee: number;
+        /** Data cost for inscription (sat/vB * size) */
+        dataCost: number;
+        /** Dust output value */
+        dustValue: number;
+    };
+    /** Fee rate used for estimation (sat/vB) */
+    feeRate: number;
+    /** Data size in bytes */
+    dataSize: number;
+    /** Target layer for the migration */
+    targetLayer: LayerType;
+    /** Confidence level of estimate */
+    confidence: 'low' | 'medium' | 'high';
+}
+/**
+ * Migration validation result
+ */
+export interface MigrationValidation {
+    /** Whether the migration is valid */
+    valid: boolean;
+    /** List of validation errors */
+    errors: string[];
+    /** List of warnings (non-blocking) */
+    warnings: string[];
+    /** Current layer of the asset */
+    currentLayer: LayerType;
+    /** Target layer for migration */
+    targetLayer: LayerType;
+    /** Checks performed */
+    checks: {
+        layerTransition: boolean;
+        resourcesValid: boolean;
+        credentialsValid: boolean;
+        didDocumentValid: boolean;
+        bitcoinReadiness?: boolean;
+    };
+}
+/**
+ * Progress callback for long-running operations
+ */
+export type ProgressCallback = (progress: LifecycleProgress) => void;
+/**
+ * Progress information for lifecycle operations
+ */
+export interface LifecycleProgress {
+    /** Current operation phase */
+    phase: 'preparing' | 'validating' | 'processing' | 'committing' | 'confirming' | 'complete' | 'failed';
+    /** Progress percentage (0-100) */
+    percentage: number;
+    /** Human-readable message */
+    message: string;
+    /** Current operation details */
+    details?: {
+        currentStep?: number;
+        totalSteps?: number;
+        transactionId?: string;
+        confirmations?: number;
+    };
+}
+/**
+ * Options for lifecycle operations with progress tracking
+ */
+export interface LifecycleOperationOptions {
+    /** Fee rate for Bitcoin operations (sat/vB) */
+    feeRate?: number;
+    /** Progress callback for operation updates */
+    onProgress?: ProgressCallback;
+    /** Enable atomic rollback on failure (default: true) */
+    atomicRollback?: boolean;
+}
+export declare class LifecycleManager {
+    private config;
+    private didManager;
+    private credentialManager;
+    private deps?;
+    private keyStore?;
+    private eventEmitter;
+    private batchExecutor;
+    private batchValidator;
+    private logger;
+    private metrics;
+    constructor(config: OriginalsConfig, didManager: DIDManager, credentialManager: CredentialManager, deps?: {
+        bitcoinManager?: BitcoinManager;
+    } | undefined, keyStore?: KeyStore | undefined);
+    /**
+     * Subscribe to a lifecycle event
+     * @param eventType - The type of event to subscribe to
+     * @param handler - The handler function to call when the event is emitted
+     * @returns A function to unsubscribe from the event
+     */
+    on<K extends keyof EventTypeMap>(eventType: K, handler: EventHandler<EventTypeMap[K]>): () => void;
+    /**
+     * Subscribe to a lifecycle event once
+     * @param eventType - The type of event to subscribe to
+     * @param handler - The handler function to call when the event is emitted (will only fire once)
+     * @returns A function to unsubscribe from the event
+     */
+    once<K extends keyof EventTypeMap>(eventType: K, handler: EventHandler<EventTypeMap[K]>): () => void;
+    /**
+     * Unsubscribe from a lifecycle event
+     * @param eventType - The type of event to unsubscribe from
+     * @param handler - The handler function to remove
+     */
+    off<K extends keyof EventTypeMap>(eventType: K, handler: EventHandler<EventTypeMap[K]>): void;
+    registerKey(verificationMethodId: string, privateKey: string): Promise<void>;
+    createAsset(resources: AssetResource[]): Promise<OriginalsAsset>;
+    /**
+     * Create a typed Original with kind-specific validation
+     *
+     * This is the recommended way to create Originals with proper typing and validation.
+     * Each kind (App, Agent, Module, Dataset, Media, Document) has specific metadata
+     * requirements that are validated before creation.
+     *
+     * @param kind - The kind of Original to create
+     * @param manifest - The manifest containing name, version, resources, and kind-specific metadata
+     * @param options - Optional creation options (skipValidation, strictMode)
+     * @returns The created OriginalsAsset
+     * @throws Error if validation fails (unless skipValidation is true)
+     *
+     * @example
+     * ```typescript
+     * // Create a Module Original
+     * const moduleAsset = await sdk.lifecycle.createTypedOriginal(
+     *   OriginalKind.Module,
+     *   {
+     *     kind: OriginalKind.Module,
+     *     name: 'my-utility',
+     *     version: '1.0.0',
+     *     resources: [{ id: 'index.js', type: 'code', hash: '...', contentType: 'application/javascript' }],
+     *     metadata: {
+     *       format: 'esm',
+     *       main: 'index.js',
+     *     }
+     *   }
+     * );
+     * ```
+     */
+    createTypedOriginal<K extends OriginalKind>(kind: K, manifest: OriginalManifest<K>, options?: CreateTypedOriginalOptions): Promise<OriginalsAsset>;
+    /**
+     * Get the manifest from a typed Original asset
+     * Returns undefined if the asset was not created with createTypedOriginal
+     *
+     * @param asset - The OriginalsAsset to get manifest from
+     * @returns The manifest or undefined
+     */
+    getManifest<K extends OriginalKind>(asset: OriginalsAsset): OriginalManifest<K> | undefined;
+    /**
+     * Estimate the cost of creating a typed Original
+     * Useful for showing users estimated fees before creation
+     *
+     * @param manifest - The manifest to estimate
+     * @param targetLayer - The target layer (did:webvh or did:btco)
+     * @param feeRate - Optional fee rate override (sat/vB)
+     * @returns Cost estimate including fees
+     */
+    estimateTypedOriginalCost<K extends OriginalKind>(manifest: OriginalManifest<K>, targetLayer: LayerType, feeRate?: number): Promise<CostEstimate>;
+    publishToWeb(asset: OriginalsAsset, publisherDidOrSigner: string | ExternalSigner): Promise<OriginalsAsset>;
+    private extractPublisherInfo;
+    private parseWebVHDid;
+    private publishResources;
+    private emitResourcePublishedEvent;
+    private issuePublicationCredential;
+    private signWithKeyStore;
+    inscribeOnBitcoin(asset: OriginalsAsset, feeRate?: number): Promise<OriginalsAsset>;
+    transferOwnership(asset: OriginalsAsset, newOwner: string): Promise<BitcoinTransaction>;
+    /**
+     * Create multiple assets in batch
+     *
+     * @param resourcesList - Array of resource arrays, one per asset to create
+     * @param options - Batch operation options
+     * @returns BatchResult with created assets
+     */
+    batchCreateAssets(resourcesList: AssetResource[][], options?: BatchOperationOptions): Promise<BatchResult<OriginalsAsset>>;
+    /**
+     * Publish multiple assets to web storage in batch
+     *
+     * @param assets - Array of assets to publish
+     * @param domain - Domain to publish to
+     * @param options - Batch operation options
+     * @returns BatchResult with published assets
+     */
+    batchPublishToWeb(assets: OriginalsAsset[], domain: string, options?: BatchOperationOptions): Promise<BatchResult<OriginalsAsset>>;
+    /**
+     * Inscribe multiple assets on Bitcoin with cost optimization
+     * KEY FEATURE: singleTransaction option for 30%+ cost savings
+     *
+     * @param assets - Array of assets to inscribe
+     * @param options - Batch inscription options
+     * @returns BatchResult with inscribed assets
+     */
+    batchInscribeOnBitcoin(assets: OriginalsAsset[], options?: BatchInscriptionOptions): Promise<BatchResult<OriginalsAsset>>;
+    /**
+     * CORE INNOVATION: Single-transaction batch inscription
+     * Combines multiple assets into one Bitcoin transaction for 30%+ cost savings
+     *
+     * @param assets - Array of assets to inscribe
+     * @param options - Batch inscription options
+     * @returns BatchResult with inscribed assets and cost savings data
+     */
+    private batchInscribeSingleTransaction;
+    /**
+     * Individual transaction batch inscription (fallback mode)
+     * Each asset is inscribed in its own transaction
+     *
+     * @param assets - Array of assets to inscribe
+     * @param options - Batch inscription options
+     * @returns BatchResult with inscribed assets
+     */
+    private batchInscribeIndividualTransactions;
+    /**
+     * Transfer ownership of multiple assets in batch
+     *
+     * @param transfers - Array of transfer operations
+     * @param options - Batch operation options
+     * @returns BatchResult with transaction results
+     */
+    batchTransferOwnership(transfers: Array<{
+        asset: OriginalsAsset;
+        to: string;
+    }>, options?: BatchOperationOptions): Promise<BatchResult<BitcoinTransaction>>;
+    /**
+     * Calculate total data size for all assets in a batch
+     */
+    private calculateTotalDataSize;
+    /**
+     * Estimate cost savings from batch inscription vs individual inscriptions
+     */
+    private estimateBatchSavings;
+    /**
+     * Create a draft asset (did:peer layer)
+     *
+     * This is the entry point for creating new Originals. Draft assets are
+     * stored locally and can be published or inscribed later.
+     *
+     * @param resources - Array of resources to include in the asset
+     * @param options - Optional configuration including progress callback
+     * @returns The newly created OriginalsAsset in did:peer layer
+     *
+     * @example
+     * ```typescript
+     * const draft = await sdk.lifecycle.createDraft([
+     *   { id: 'main', type: 'code', contentType: 'text/javascript', hash: '...' }
+     * ], {
+     *   onProgress: (p) => console.log(p.message)
+     * });
+     * ```
+     */
+    createDraft(resources: AssetResource[], options?: LifecycleOperationOptions): Promise<OriginalsAsset>;
+    /**
+     * Publish an asset to the web (did:webvh layer)
+     *
+     * Migrates a draft asset from did:peer to did:webvh, making it publicly
+     * discoverable via HTTPS.
+     *
+     * @param asset - The asset to publish (must be in did:peer layer)
+     * @param publisherDidOrSigner - Publisher's DID or external signer
+     * @param options - Optional configuration including progress callback
+     * @returns The published OriginalsAsset in did:webvh layer
+     *
+     * @example
+     * ```typescript
+     * const published = await sdk.lifecycle.publish(draft, 'did:webvh:example.com:user');
+     * ```
+     */
+    publish(asset: OriginalsAsset, publisherDidOrSigner: string | ExternalSigner, options?: LifecycleOperationOptions): Promise<OriginalsAsset>;
+    /**
+     * Inscribe an asset on Bitcoin (did:btco layer)
+     *
+     * Permanently anchors an asset on the Bitcoin blockchain via Ordinals inscription.
+     * This is an irreversible operation.
+     *
+     * @param asset - The asset to inscribe (must be in did:peer or did:webvh layer)
+     * @param options - Optional configuration including fee rate and progress callback
+     * @returns The inscribed OriginalsAsset in did:btco layer
+     *
+     * @example
+     * ```typescript
+     * const inscribed = await sdk.lifecycle.inscribe(published, {
+     *   feeRate: 15,
+     *   onProgress: (p) => console.log(`${p.percentage}%: ${p.message}`)
+     * });
+     * ```
+     */
+    inscribe(asset: OriginalsAsset, options?: LifecycleOperationOptions): Promise<OriginalsAsset>;
+    /**
+     * Transfer ownership of a Bitcoin-inscribed asset
+     *
+     * Transfers an inscribed asset to a new owner. Only works for assets
+     * in the did:btco layer.
+     *
+     * @param asset - The asset to transfer (must be in did:btco layer)
+     * @param newOwnerAddress - Bitcoin address of the new owner
+     * @param options - Optional configuration including progress callback
+     * @returns The Bitcoin transaction for the transfer
+     *
+     * @example
+     * ```typescript
+     * const tx = await sdk.lifecycle.transfer(inscribed, 'bc1q...newowner');
+     * console.log('Transfer txid:', tx.txid);
+     * ```
+     */
+    transfer(asset: OriginalsAsset, newOwnerAddress: string, options?: LifecycleOperationOptions): Promise<BitcoinTransaction>;
+    /**
+     * Estimate the cost of migrating an asset to a target layer
+     *
+     * Returns a detailed breakdown of expected costs for Bitcoin operations.
+     * For did:webvh migrations, costs are minimal (only hosting).
+     *
+     * @param asset - The asset to estimate costs for
+     * @param targetLayer - The target layer for migration
+     * @param feeRate - Optional fee rate override (sat/vB)
+     * @returns Detailed cost estimate
+     *
+     * @example
+     * ```typescript
+     * const cost = await sdk.lifecycle.estimateCost(draft, 'did:btco', 10);
+     * console.log(`Estimated cost: ${cost.totalSats} sats`);
+     * ```
+     */
+    estimateCost(asset: OriginalsAsset, targetLayer: LayerType, feeRate?: number): Promise<CostEstimate>;
+    /**
+     * Validate whether an asset can be migrated to a target layer
+     *
+     * Performs comprehensive pre-flight checks including:
+     * - Valid layer transition
+     * - Resource integrity
+     * - Credential validity
+     * - DID document structure
+     * - Bitcoin readiness (for did:btco)
+     *
+     * @param asset - The asset to validate
+     * @param targetLayer - The target layer for migration
+     * @returns Detailed validation result
+     *
+     * @example
+     * ```typescript
+     * const validation = await sdk.lifecycle.validateMigration(draft, 'did:webvh');
+     * if (!validation.valid) {
+     *   console.error('Cannot migrate:', validation.errors);
+     * }
+     * ```
+     */
+    validateMigration(asset: OriginalsAsset, targetLayer: LayerType): Promise<MigrationValidation>;
+}