@originals/sdk 1.4.2 → 1.4.5

package/dist/kinds/validators/base.js

@@ -0,0 +1,218 @@
+/**
+ * Base validator interface and common validation utilities
+ */
+/**
+ * Common validation utilities
+ */
+export class ValidationUtils {
+    /**
+     * Check if a string is a valid semantic version
+     */
+    static isValidSemver(version) {
+        const semverRegex = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+        return semverRegex.test(version);
+    }
+    /**
+     * Check if a string is a valid DID
+     */
+    static isValidDID(did) {
+        // DID format: did:method:identifier (identifier can contain : for path segments)
+        // Examples: did:peer:123, did:webvh:example.com:user, did:btco:12345
+        const didRegex = /^did:[a-z0-9]+:[a-zA-Z0-9._:%-]+$/;
+        return didRegex.test(did);
+    }
+    /**
+     * Check if a string is a valid SPDX license identifier
+     */
+    static isValidSPDXLicense(license) {
+        // Common SPDX identifiers (not exhaustive)
+        const commonLicenses = [
+            'MIT', 'Apache-2.0', 'GPL-3.0', 'GPL-2.0', 'BSD-2-Clause', 'BSD-3-Clause',
+            'ISC', 'MPL-2.0', 'LGPL-3.0', 'AGPL-3.0', 'Unlicense', 'CC0-1.0',
+            'CC-BY-4.0', 'CC-BY-SA-4.0', 'CC-BY-NC-4.0', 'WTFPL', 'Zlib', 'BSL-1.0',
+            'MIT-0', 'Apache-1.0', 'Apache-1.1', 'EPL-2.0', 'EUPL-1.2',
+        ];
+        return commonLicenses.includes(license) || /^[A-Z0-9][A-Z0-9._-]*$/i.test(license);
+    }
+    /**
+     * Check if a string is a valid MIME type
+     */
+    static isValidMimeType(mimeType) {
+        const mimeRegex = /^[a-zA-Z0-9][a-zA-Z0-9!#$&^_.+-]{0,126}\/[a-zA-Z0-9][a-zA-Z0-9!#$&^_.+-]{0,126}$/;
+        return mimeRegex.test(mimeType);
+    }
+    /**
+     * Check if a string is a valid URL
+     */
+    static isValidURL(url) {
+        try {
+            new URL(url);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Check if a string is a valid ISO 639-1 language code
+     */
+    static isValidLanguageCode(code) {
+        // ISO 639-1 is 2 lowercase letters
+        return /^[a-z]{2}$/.test(code);
+    }
+    /**
+     * Check if a resource ID exists in the resources array
+     */
+    static resourceExists(resourceId, resources) {
+        return resources.some(r => r.id === resourceId);
+    }
+    /**
+     * Get a resource by ID
+     */
+    static getResource(resourceId, resources) {
+        return resources.find(r => r.id === resourceId);
+    }
+    /**
+     * Create a validation error
+     */
+    static error(code, message, path, value) {
+        return { code, message, path, value };
+    }
+    /**
+     * Create a validation warning
+     */
+    static warning(code, message, path, suggestion) {
+        return { code, message, path, suggestion };
+    }
+    /**
+     * Create a successful validation result
+     */
+    static success(warnings = []) {
+        return { isValid: true, errors: [], warnings };
+    }
+    /**
+     * Create a failed validation result
+     */
+    static failure(errors, warnings = []) {
+        return { isValid: false, errors, warnings };
+    }
+    /**
+     * Merge multiple validation results
+     */
+    static merge(...results) {
+        const errors = [];
+        const warnings = [];
+        for (const result of results) {
+            errors.push(...result.errors);
+            warnings.push(...result.warnings);
+        }
+        return {
+            isValid: errors.length === 0,
+            errors,
+            warnings,
+        };
+    }
+}
+/**
+ * Base validator class with common validation logic
+ */
+export class BaseKindValidator {
+    /**
+     * Validate a manifest
+     * Combines base validation with kind-specific validation
+     */
+    validate(manifest) {
+        const baseResult = this.validateBase(manifest);
+        const kindResult = this.validateKind(manifest);
+        return ValidationUtils.merge(baseResult, kindResult);
+    }
+    /**
+     * Validate base manifest fields common to all kinds
+     */
+    validateBase(manifest) {
+        const errors = [];
+        const warnings = [];
+        // Validate kind
+        if (!manifest.kind) {
+            errors.push(ValidationUtils.error('MISSING_KIND', 'Manifest must specify a kind', 'kind'));
+        }
+        // Validate name
+        if (!manifest.name || typeof manifest.name !== 'string') {
+            errors.push(ValidationUtils.error('MISSING_NAME', 'Manifest must have a name', 'name'));
+        }
+        else if (manifest.name.length < 1 || manifest.name.length > 200) {
+            errors.push(ValidationUtils.error('INVALID_NAME_LENGTH', 'Name must be between 1 and 200 characters', 'name', manifest.name));
+        }
+        // Validate version
+        if (!manifest.version || typeof manifest.version !== 'string') {
+            errors.push(ValidationUtils.error('MISSING_VERSION', 'Manifest must have a version', 'version'));
+        }
+        else if (!ValidationUtils.isValidSemver(manifest.version)) {
+            errors.push(ValidationUtils.error('INVALID_VERSION', 'Version must be a valid semantic version (e.g., 1.0.0)', 'version', manifest.version));
+        }
+        // Validate resources
+        if (!manifest.resources || !Array.isArray(manifest.resources)) {
+            errors.push(ValidationUtils.error('MISSING_RESOURCES', 'Manifest must have resources array', 'resources'));
+        }
+        else if (manifest.resources.length === 0) {
+            errors.push(ValidationUtils.error('EMPTY_RESOURCES', 'Manifest must have at least one resource', 'resources'));
+        }
+        else {
+            // Validate each resource
+            for (let i = 0; i < manifest.resources.length; i++) {
+                const resource = manifest.resources[i];
+                const resourcePath = `resources[${i}]`;
+                if (!resource.id || typeof resource.id !== 'string') {
+                    errors.push(ValidationUtils.error('INVALID_RESOURCE_ID', `Resource at index ${i} must have an id`, `${resourcePath}.id`));
+                }
+                if (!resource.type || typeof resource.type !== 'string') {
+                    errors.push(ValidationUtils.error('INVALID_RESOURCE_TYPE', `Resource at index ${i} must have a type`, `${resourcePath}.type`));
+                }
+                if (!resource.contentType || !ValidationUtils.isValidMimeType(resource.contentType)) {
+                    errors.push(ValidationUtils.error('INVALID_CONTENT_TYPE', `Resource at index ${i} must have a valid MIME contentType`, `${resourcePath}.contentType`, resource.contentType));
+                }
+                if (!resource.hash || typeof resource.hash !== 'string' || !/^[0-9a-fA-F]+$/.test(resource.hash)) {
+                    errors.push(ValidationUtils.error('INVALID_RESOURCE_HASH', `Resource at index ${i} must have a valid hex hash`, `${resourcePath}.hash`));
+                }
+            }
+            // Check for duplicate resource IDs
+            const resourceIds = manifest.resources.map(r => r.id);
+            const duplicates = resourceIds.filter((id, index) => resourceIds.indexOf(id) !== index);
+            if (duplicates.length > 0) {
+                errors.push(ValidationUtils.error('DUPLICATE_RESOURCE_IDS', `Duplicate resource IDs found: ${[...new Set(duplicates)].join(', ')}`, 'resources'));
+            }
+        }
+        // Validate dependencies if present
+        if (manifest.dependencies) {
+            if (!Array.isArray(manifest.dependencies)) {
+                errors.push(ValidationUtils.error('INVALID_DEPENDENCIES', 'Dependencies must be an array', 'dependencies'));
+            }
+            else {
+                for (let i = 0; i < manifest.dependencies.length; i++) {
+                    const dep = manifest.dependencies[i];
+                    const depPath = `dependencies[${i}]`;
+                    if (!dep.did || !ValidationUtils.isValidDID(dep.did)) {
+                        errors.push(ValidationUtils.error('INVALID_DEPENDENCY_DID', `Dependency at index ${i} must have a valid DID`, `${depPath}.did`, dep.did));
+                    }
+                }
+            }
+        }
+        // Validate optional fields
+        if (manifest.license && !ValidationUtils.isValidSPDXLicense(manifest.license)) {
+            warnings.push(ValidationUtils.warning('UNKNOWN_LICENSE', `License "${manifest.license}" is not a recognized SPDX identifier`, 'license', 'Use a valid SPDX license identifier like MIT, Apache-2.0, etc.'));
+        }
+        if (manifest.homepage && !ValidationUtils.isValidURL(manifest.homepage)) {
+            errors.push(ValidationUtils.error('INVALID_HOMEPAGE', 'Homepage must be a valid URL', 'homepage', manifest.homepage));
+        }
+        if (manifest.repository && !ValidationUtils.isValidURL(manifest.repository)) {
+            errors.push(ValidationUtils.error('INVALID_REPOSITORY', 'Repository must be a valid URL', 'repository', manifest.repository));
+        }
+        // Suggest adding description if missing
+        if (!manifest.description) {
+            warnings.push(ValidationUtils.warning('MISSING_DESCRIPTION', 'Consider adding a description for better discoverability', 'description', 'Add a brief description of this Original'));
+        }
+        return errors.length > 0
+            ? ValidationUtils.failure(errors, warnings)
+            : ValidationUtils.success(warnings);
+    }
+}

package/{src/kinds/validators/index.ts → dist/kinds/validators/index.d.ts}

@@ -1,7 +1,6 @@
 /**
  * Kind validators exports
  */
-
 export { BaseKindValidator, ValidationUtils, type KindValidator } from './base';
 export { AppValidator } from './AppValidator';
 export { AgentValidator } from './AgentValidator';
@@ -9,4 +8,3 @@ export { ModuleValidator } from './ModuleValidator';
 export { DatasetValidator } from './DatasetValidator';
 export { MediaValidator } from './MediaValidator';
 export { DocumentValidator } from './DocumentValidator';
-

package/dist/kinds/validators/index.js

@@ -0,0 +1,10 @@
+/**
+ * Kind validators exports
+ */
+export { BaseKindValidator, ValidationUtils } from './base';
+export { AppValidator } from './AppValidator';
+export { AgentValidator } from './AgentValidator';
+export { ModuleValidator } from './ModuleValidator';
+export { DatasetValidator } from './DatasetValidator';
+export { MediaValidator } from './MediaValidator';
+export { DocumentValidator } from './DocumentValidator';

package/dist/lifecycle/BatchOperations.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Batch Operations for Originals SDK
+ *
+ * Enables efficient processing of multiple assets with:
+ * - Configurable concurrency
+ * - Retry logic with exponential backoff
+ * - Fail-fast vs continue-on-error modes
+ * - Pre-validation of all items
+ * - Detailed timing and error tracking
+ */
+/**
+ * Result of a batch operation containing successful and failed items
+ */
+export interface BatchResult<T> {
+    successful: Array<{
+        index: number;
+        result: T;
+        duration: number;
+    }>;
+    failed: Array<{
+        index: number;
+        error: Error;
+        duration: number;
+        retryAttempts?: number;
+    }>;
+    totalProcessed: number;
+    totalDuration: number;
+    batchId: string;
+    startedAt: string;
+    completedAt: string;
+}
+/**
+ * Options for configuring batch operation execution
+ */
+export interface BatchOperationOptions {
+    continueOnError?: boolean;
+    maxConcurrent?: number;
+    retryCount?: number;
+    retryDelay?: number;
+    timeoutMs?: number;
+    validateFirst?: boolean;
+}
+/**
+ * Options for batch inscription operations with Bitcoin-specific settings
+ */
+export interface BatchInscriptionOptions extends BatchOperationOptions {
+    singleTransaction?: boolean;
+    feeRate?: number;
+}
+/**
+ * Error thrown when a batch operation fails
+ */
+export declare class BatchError extends Error {
+    batchId: string;
+    operation: string;
+    partialResults: {
+        successful: number;
+        failed: number;
+    };
+    constructor(batchId: string, operation: string, partialResults: {
+        successful: number;
+        failed: number;
+    }, message: string);
+}
+/**
+ * Result of a single-transaction batch inscription with cost analysis
+ */
+export interface BatchInscriptionResult<T> {
+    batchTransactionId: string;
+    individualInscriptionIds: string[];
+    assets: T[];
+    totalFee: number;
+    feePerAsset: number[];
+    feeSavings: {
+        batchFee: number;
+        individualFees: number;
+        savings: number;
+        savingsPercentage: number;
+    };
+    batchId: string;
+    processingTime: number;
+}
+/**
+ * Executor for batch operations with configurable options
+ */
+export declare class BatchOperationExecutor {
+    private defaultOptions;
+    constructor(defaultOptions?: BatchOperationOptions);
+    /**
+     * Execute a batch operation on multiple items
+     *
+     * @param items - Array of items to process
+     * @param operation - Function to execute on each item
+     * @param options - Batch operation options
+     * @param predeterminedBatchId - Optional pre-generated batch ID for event correlation
+     * @returns BatchResult with successful and failed operations
+     */
+    execute<T, R>(items: T[], operation: (item: T, index: number) => Promise<R>, options?: BatchOperationOptions, predeterminedBatchId?: string): Promise<BatchResult<R>>;
+    /**
+     * Generate unique batch ID
+     */
+    generateBatchId(): string;
+    /**
+     * Calculate retry delay with exponential backoff
+     */
+    private calculateRetryDelay;
+    /**
+     * Execute operation with timeout
+     */
+    private executeWithTimeout;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+    /**
+     * Chunk array into smaller arrays of specified size
+     */
+    private chunkArray;
+}
+/**
+ * Validation result for batch operations
+ */
+export interface ValidationResult {
+    isValid: boolean;
+    errors: string[];
+    warnings?: string[];
+}
+/**
+ * Validator for batch operations
+ */
+export declare class BatchValidator {
+    /**
+     * Validate batch of resources for asset creation
+     */
+    validateBatchCreate(resourcesList: any[][]): ValidationResult[];
+    /**
+     * Validate batch of assets for inscription
+     */
+    validateBatchInscription(assets: any[]): ValidationResult[];
+    /**
+     * Validate batch of transfer operations
+     */
+    validateBatchTransfer(transfers: Array<{
+        asset: any;
+        to: string;
+    }>): ValidationResult[];
+}

package/dist/lifecycle/BatchOperations.js

@@ -0,0 +1,251 @@
+/**
+ * Batch Operations for Originals SDK
+ *
+ * Enables efficient processing of multiple assets with:
+ * - Configurable concurrency
+ * - Retry logic with exponential backoff
+ * - Fail-fast vs continue-on-error modes
+ * - Pre-validation of all items
+ * - Detailed timing and error tracking
+ */
+import { randomBytes, bytesToHex } from '@noble/hashes/utils.js';
+/**
+ * Error thrown when a batch operation fails
+ */
+export class BatchError extends Error {
+    constructor(batchId, operation, partialResults, message) {
+        super(message);
+        this.batchId = batchId;
+        this.operation = operation;
+        this.partialResults = partialResults;
+        this.name = 'BatchError';
+    }
+}
+/**
+ * Executor for batch operations with configurable options
+ */
+export class BatchOperationExecutor {
+    constructor(defaultOptions = {}) {
+        this.defaultOptions = defaultOptions;
+    }
+    /**
+     * Execute a batch operation on multiple items
+     *
+     * @param items - Array of items to process
+     * @param operation - Function to execute on each item
+     * @param options - Batch operation options
+     * @param predeterminedBatchId - Optional pre-generated batch ID for event correlation
+     * @returns BatchResult with successful and failed operations
+     */
+    async execute(items, operation, options, predeterminedBatchId) {
+        const opts = { ...this.defaultOptions, ...options };
+        const { continueOnError = false, maxConcurrent = 1, retryCount = 0, retryDelay = 1000, timeoutMs = 30000 } = opts;
+        const batchId = predeterminedBatchId || this.generateBatchId();
+        const startedAt = new Date().toISOString();
+        const startTime = Date.now();
+        const successful = [];
+        const failed = [];
+        // Process items with concurrency control
+        const processItem = async (item, index) => {
+            const itemStartTime = Date.now();
+            let lastError = null;
+            let attempts = 0;
+            for (let attempt = 0; attempt <= retryCount; attempt++) {
+                attempts = attempt + 1;
+                try {
+                    // Execute with timeout
+                    const result = await this.executeWithTimeout(() => operation(item, index), timeoutMs);
+                    const duration = Date.now() - itemStartTime;
+                    successful.push({ index, result, duration });
+                    return;
+                }
+                catch (error) {
+                    lastError = error instanceof Error ? error : new Error(String(error));
+                    // If not last attempt, wait with exponential backoff
+                    if (attempt < retryCount) {
+                        const delay = this.calculateRetryDelay(attempt, retryDelay);
+                        await this.sleep(delay);
+                    }
+                }
+            }
+            // All retries failed
+            const duration = Date.now() - itemStartTime;
+            failed.push({
+                index,
+                error: lastError,
+                duration,
+                retryAttempts: attempts - 1
+            });
+            // If fail-fast mode, throw error
+            if (!continueOnError) {
+                throw lastError;
+            }
+        };
+        // Process items in batches based on maxConcurrent
+        try {
+            if (maxConcurrent === 1) {
+                // Sequential processing
+                for (let i = 0; i < items.length; i++) {
+                    await processItem(items[i], i);
+                }
+            }
+            else {
+                // Concurrent processing with limit
+                const chunks = this.chunkArray(items, maxConcurrent);
+                for (const chunk of chunks) {
+                    await Promise.all(chunk.map((item, chunkIndex) => {
+                        const globalIndex = chunks.slice(0, chunks.indexOf(chunk))
+                            .reduce((acc, c) => acc + c.length, 0) + chunkIndex;
+                        return processItem(item, globalIndex);
+                    }));
+                }
+            }
+        }
+        catch (error) {
+            // In fail-fast mode, re-throw the error so callers can handle it
+            if (!continueOnError) {
+                throw error instanceof Error ? error : new Error(String(error));
+            }
+            // In continue-on-error mode, the error was already logged in processItem
+            // and we'll return the partial results below
+        }
+        const totalDuration = Date.now() - startTime;
+        const completedAt = new Date().toISOString();
+        return {
+            successful,
+            failed,
+            totalProcessed: successful.length + failed.length,
+            totalDuration,
+            batchId,
+            startedAt,
+            completedAt
+        };
+    }
+    /**
+     * Generate unique batch ID
+     */
+    generateBatchId() {
+        return `batch_${Date.now()}_${bytesToHex(randomBytes(8))}`;
+    }
+    /**
+     * Calculate retry delay with exponential backoff
+     */
+    calculateRetryDelay(attempt, baseDelay) {
+        // Exponential backoff: baseDelay * 2^attempt
+        return baseDelay * Math.pow(2, attempt);
+    }
+    /**
+     * Execute operation with timeout
+     */
+    async executeWithTimeout(operation, timeoutMs) {
+        return Promise.race([
+            operation(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Operation timeout after ${timeoutMs}ms`)), timeoutMs))
+        ]);
+    }
+    /**
+     * Sleep for specified milliseconds
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Chunk array into smaller arrays of specified size
+     */
+    chunkArray(array, size) {
+        const chunks = [];
+        for (let i = 0; i < array.length; i += size) {
+            chunks.push(array.slice(i, i + size));
+        }
+        return chunks;
+    }
+}
+/**
+ * Validator for batch operations
+ */
+export class BatchValidator {
+    /**
+     * Validate batch of resources for asset creation
+     */
+    validateBatchCreate(resourcesList) {
+        return resourcesList.map((resources, index) => {
+            const errors = [];
+            if (!Array.isArray(resources)) {
+                errors.push(`Item ${index}: Resources must be an array`);
+                return { isValid: false, errors };
+            }
+            if (resources.length === 0) {
+                errors.push(`Item ${index}: At least one resource is required`);
+                return { isValid: false, errors };
+            }
+            // Validate each resource
+            for (let i = 0; i < resources.length; i++) {
+                const resource = resources[i];
+                if (!resource || typeof resource !== 'object') {
+                    errors.push(`Item ${index}, resource ${i}: Invalid resource object`);
+                    continue;
+                }
+                if (!resource.id || typeof resource.id !== 'string') {
+                    errors.push(`Item ${index}, resource ${i}: Missing or invalid id`);
+                }
+                if (!resource.type || typeof resource.type !== 'string') {
+                    errors.push(`Item ${index}, resource ${i}: Missing or invalid type`);
+                }
+                if (!resource.contentType || typeof resource.contentType !== 'string') {
+                    errors.push(`Item ${index}, resource ${i}: Missing or invalid contentType`);
+                }
+                if (!resource.hash || typeof resource.hash !== 'string' || !/^[0-9a-fA-F]+$/.test(resource.hash)) {
+                    errors.push(`Item ${index}, resource ${i}: Missing or invalid hash`);
+                }
+            }
+            return { isValid: errors.length === 0, errors };
+        });
+    }
+    /**
+     * Validate batch of assets for inscription
+     */
+    validateBatchInscription(assets) {
+        return assets.map((asset, index) => {
+            const errors = [];
+            if (!asset || typeof asset !== 'object') {
+                errors.push(`Item ${index}: Invalid asset object`);
+                return { isValid: false, errors };
+            }
+            if (!asset.id || typeof asset.id !== 'string') {
+                errors.push(`Item ${index}: Missing or invalid asset id`);
+            }
+            if (!asset.currentLayer) {
+                errors.push(`Item ${index}: Missing currentLayer`);
+            }
+            else if (asset.currentLayer === 'did:btco') {
+                errors.push(`Item ${index}: Asset already inscribed on Bitcoin`);
+            }
+            if (!asset.resources || !Array.isArray(asset.resources) || asset.resources.length === 0) {
+                errors.push(`Item ${index}: Asset must have at least one resource`);
+            }
+            return { isValid: errors.length === 0, errors };
+        });
+    }
+    /**
+     * Validate batch of transfer operations
+     */
+    validateBatchTransfer(transfers) {
+        return transfers.map((transfer, index) => {
+            const errors = [];
+            if (!transfer || typeof transfer !== 'object') {
+                errors.push(`Item ${index}: Invalid transfer object`);
+                return { isValid: false, errors };
+            }
+            if (!transfer.asset || typeof transfer.asset !== 'object') {
+                errors.push(`Item ${index}: Invalid asset`);
+            }
+            else if (transfer.asset.currentLayer !== 'did:btco') {
+                errors.push(`Item ${index}: Asset must be inscribed on Bitcoin before transfer`);
+            }
+            if (!transfer.to || typeof transfer.to !== 'string') {
+                errors.push(`Item ${index}: Invalid destination address`);
+            }
+            return { isValid: errors.length === 0, errors };
+        });
+    }
+}