@originals/sdk 1.4.3 → 1.4.5

package/dist/resources/ResourceManager.js

@@ -0,0 +1,573 @@
+/**
+ * ResourceManager - CRUD operations for immutable, versioned resources.
+ *
+ * Resources in the Originals SDK are content-addressed and immutable. Each "update"
+ * creates a new version with a new content hash, linked to the previous version
+ * via previousVersionHash. This creates a verifiable provenance chain.
+ *
+ * @example
+ * ```typescript
+ * const manager = new ResourceManager();
+ *
+ * // Create a new resource
+ * const resource = manager.createResource('Hello, World!', {
+ *   type: 'text',
+ *   contentType: 'text/plain'
+ * });
+ *
+ * // Update creates a new version
+ * const updatedResource = manager.updateResource(resource, 'Hello, Updated World!', {
+ *   changes: 'Updated greeting'
+ * });
+ *
+ * // Get version history
+ * const history = manager.getResourceHistory(resource.id);
+ * ```
+ */
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import { v4 as uuidv4 } from 'uuid';
+import { MIME_TYPE_MAP, DEFAULT_RESOURCE_CONFIG } from './types.js';
+/**
+ * Regular expression for validating MIME types according to RFC 6838.
+ * Format: type/subtype where type and subtype are restricted character sets.
+ */
+const MIME_TYPE_REGEX = /^[a-zA-Z0-9][a-zA-Z0-9!#$&^_.+-]{0,126}\/[a-zA-Z0-9][a-zA-Z0-9!#$&^_.+-]{0,126}$/;
+/**
+ * ResourceManager provides CRUD operations for immutable, content-addressed resources
+ * with versioning support and validation.
+ */
+export class ResourceManager {
+    /**
+     * Create a new ResourceManager instance.
+     *
+     * @param config - Optional configuration for the manager
+     */
+    constructor(config) {
+        this.resources = new Map();
+        this.config = { ...DEFAULT_RESOURCE_CONFIG, ...config };
+    }
+    /**
+     * Create a new resource from content.
+     *
+     * @param content - The resource content (string for text, Buffer for binary)
+     * @param options - Creation options including type and contentType
+     * @returns The created Resource
+     * @throws Error if content or options are invalid
+     *
+     * @example
+     * ```typescript
+     * // Create a text resource
+     * const textResource = manager.createResource('# README\nHello', {
+     *   type: 'text',
+     *   contentType: 'text/markdown'
+     * });
+     *
+     * // Create a binary resource (image)
+     * const imageBuffer = fs.readFileSync('image.png');
+     * const imageResource = manager.createResource(imageBuffer, {
+     *   type: 'image',
+     *   contentType: 'image/png'
+     * });
+     * ```
+     */
+    createResource(content, options) {
+        // Validate inputs
+        if (content === null || content === undefined) {
+            throw new Error('Content is required');
+        }
+        if (!options) {
+            throw new Error('Options are required');
+        }
+        if (!options.type) {
+            throw new Error('Resource type is required');
+        }
+        if (!options.contentType) {
+            throw new Error('Content type is required');
+        }
+        // Validate MIME type format
+        if (!this.isValidMimeType(options.contentType)) {
+            throw new Error(`Invalid MIME type format: ${options.contentType}`);
+        }
+        // Check allowed content types
+        if (this.config.allowedContentTypes.length > 0 &&
+            !this.config.allowedContentTypes.includes(options.contentType)) {
+            throw new Error(`Content type not allowed: ${options.contentType}. Allowed types: ${this.config.allowedContentTypes.join(', ')}`);
+        }
+        // Convert content to buffer for consistent handling
+        const contentBuffer = this.toBuffer(content);
+        // Validate size
+        const maxSize = options.maxSize || this.config.defaultMaxSize;
+        if (contentBuffer.length > maxSize) {
+            throw new Error(`Resource size (${contentBuffer.length} bytes) exceeds maximum allowed size (${maxSize} bytes)`);
+        }
+        // Generate hash
+        const hash = this.hashContent(contentBuffer);
+        // Generate or use provided ID
+        const id = options.id || uuidv4();
+        // Create resource object
+        const resource = {
+            id,
+            type: options.type,
+            contentType: options.contentType,
+            hash,
+            size: contentBuffer.length,
+            version: 1,
+            createdAt: new Date().toISOString(),
+            url: options.url,
+            description: options.description,
+        };
+        // Store content if configured to do so
+        if (this.config.storeContent) {
+            if (this.isBinaryContent(content)) {
+                resource.contentBase64 = contentBuffer.toString('base64');
+            }
+            else {
+                resource.content = typeof content === 'string' ? content : contentBuffer.toString('utf-8');
+            }
+        }
+        // Store in version history
+        this.resources.set(id, [resource]);
+        return resource;
+    }
+    /**
+     * Update a resource by creating a new version.
+     * The original resource remains unchanged (immutable versioning).
+     *
+     * @param resource - The resource to update (or its ID)
+     * @param newContent - The new content
+     * @param options - Optional update options including change description
+     * @returns The new version of the resource
+     * @throws Error if resource not found or content unchanged
+     *
+     * @example
+     * ```typescript
+     * const v2 = manager.updateResource(originalResource, 'Updated content', {
+     *   changes: 'Fixed typo in documentation'
+     * });
+     *
+     * console.log(v2.version); // 2
+     * console.log(v2.previousVersionHash); // hash of v1
+     * ```
+     */
+    updateResource(resource, newContent, options) {
+        const resourceId = typeof resource === 'string' ? resource : resource.id;
+        // Get version history
+        const versions = this.resources.get(resourceId);
+        if (!versions || versions.length === 0) {
+            throw new Error(`Resource not found: ${resourceId}`);
+        }
+        // Get current (latest) version
+        const currentVersion = versions[versions.length - 1];
+        // Convert content to buffer
+        const contentBuffer = this.toBuffer(newContent);
+        // Generate hash for new content
+        const newHash = this.hashContent(contentBuffer);
+        // Check if content has actually changed
+        if (newHash === currentVersion.hash) {
+            throw new Error('Content unchanged - new version would be identical to current version');
+        }
+        // Validate size
+        if (contentBuffer.length > this.config.defaultMaxSize) {
+            throw new Error(`Resource size (${contentBuffer.length} bytes) exceeds maximum allowed size (${this.config.defaultMaxSize} bytes)`);
+        }
+        // Determine content type (use provided or inherit from previous)
+        const contentType = options?.contentType || currentVersion.contentType;
+        // Validate new content type if changed
+        if (options?.contentType && !this.isValidMimeType(options.contentType)) {
+            throw new Error(`Invalid MIME type format: ${options.contentType}`);
+        }
+        // Create new version
+        const newVersion = {
+            id: resourceId,
+            type: currentVersion.type,
+            contentType,
+            hash: newHash,
+            size: contentBuffer.length,
+            version: (currentVersion.version || 1) + 1,
+            previousVersionHash: currentVersion.hash,
+            createdAt: new Date().toISOString(),
+            url: currentVersion.url,
+            description: currentVersion.description,
+        };
+        // Store content if configured
+        if (this.config.storeContent) {
+            if (this.isBinaryContent(newContent)) {
+                newVersion.contentBase64 = contentBuffer.toString('base64');
+            }
+            else {
+                newVersion.content = typeof newContent === 'string' ? newContent : contentBuffer.toString('utf-8');
+            }
+        }
+        // Add to version history
+        versions.push(newVersion);
+        return newVersion;
+    }
+    /**
+     * Get the complete version history for a resource.
+     *
+     * @param resourceId - The logical resource ID
+     * @returns Array of all versions (oldest to newest), or empty array if not found
+     *
+     * @example
+     * ```typescript
+     * const history = manager.getResourceHistory('my-resource-id');
+     * console.log(`Found ${history.length} versions`);
+     * history.forEach((v, i) => console.log(`v${i + 1}: ${v.hash}`));
+     * ```
+     */
+    getResourceHistory(resourceId) {
+        const versions = this.resources.get(resourceId);
+        if (!versions) {
+            return [];
+        }
+        return [...versions]; // Return copy to prevent external mutation
+    }
+    /**
+     * Get detailed version history with metadata.
+     *
+     * @param resourceId - The logical resource ID
+     * @returns ResourceVersionHistory object or null if not found
+     */
+    getResourceVersionHistory(resourceId) {
+        const versions = this.resources.get(resourceId);
+        if (!versions || versions.length === 0) {
+            return null;
+        }
+        return {
+            resourceId,
+            versions: [...versions],
+            currentVersion: versions[versions.length - 1],
+            versionCount: versions.length,
+        };
+    }
+    /**
+     * Get a specific version of a resource.
+     *
+     * @param resourceId - The logical resource ID
+     * @param version - Version number (1-indexed)
+     * @returns The resource at that version, or null if not found
+     */
+    getResourceVersion(resourceId, version) {
+        const versions = this.resources.get(resourceId);
+        if (!versions || version < 1 || version > versions.length) {
+            return null;
+        }
+        return versions[version - 1];
+    }
+    /**
+     * Get the current (latest) version of a resource.
+     *
+     * @param resourceId - The logical resource ID
+     * @returns The current version, or null if not found
+     */
+    getCurrentVersion(resourceId) {
+        const versions = this.resources.get(resourceId);
+        if (!versions || versions.length === 0) {
+            return null;
+        }
+        return versions[versions.length - 1];
+    }
+    /**
+     * Get a resource by its content hash.
+     *
+     * @param hash - The content hash to search for
+     * @returns The resource with that hash, or null if not found
+     */
+    getResourceByHash(hash) {
+        for (const versions of this.resources.values()) {
+            const found = versions.find(r => r.hash === hash);
+            if (found) {
+                return found;
+            }
+        }
+        return null;
+    }
+    /**
+     * Validate a resource object.
+     *
+     * @param resource - The resource to validate
+     * @returns ValidationResult with valid flag and any errors/warnings
+     *
+     * @example
+     * ```typescript
+     * const result = manager.validateResource(resource);
+     * if (!result.valid) {
+     *   console.error('Validation errors:', result.errors);
+     * }
+     * if (result.warnings.length > 0) {
+     *   console.warn('Warnings:', result.warnings);
+     * }
+     * ```
+     */
+    validateResource(resource) {
+        const errors = [];
+        const warnings = [];
+        // Required field validation
+        if (!resource) {
+            return { valid: false, errors: ['Resource is null or undefined'], warnings: [] };
+        }
+        if (!resource.id || typeof resource.id !== 'string') {
+            errors.push('Missing or invalid resource ID');
+        }
+        if (!resource.type || typeof resource.type !== 'string') {
+            errors.push('Missing or invalid resource type');
+        }
+        if (!resource.contentType || typeof resource.contentType !== 'string') {
+            errors.push('Missing or invalid content type');
+        }
+        else if (this.config.strictMimeValidation && !this.isValidMimeType(resource.contentType)) {
+            errors.push(`Invalid MIME type format: ${resource.contentType}`);
+        }
+        if (!resource.hash || typeof resource.hash !== 'string') {
+            errors.push('Missing or invalid hash');
+        }
+        else if (!/^[0-9a-fA-F]{64}$/.test(resource.hash)) {
+            errors.push('Invalid hash format (must be 64 character hex string)');
+        }
+        // Version chain validation
+        if (resource.version !== undefined) {
+            if (typeof resource.version !== 'number' || resource.version < 1) {
+                errors.push('Invalid version number (must be positive integer)');
+            }
+            // v1 should not have previousVersionHash
+            if (resource.version === 1 && resource.previousVersionHash) {
+                warnings.push('First version should not have previousVersionHash');
+            }
+            // v2+ should have previousVersionHash
+            if (resource.version > 1 && !resource.previousVersionHash) {
+                errors.push('Versions greater than 1 must have previousVersionHash');
+            }
+        }
+        // Size validation
+        if (resource.size !== undefined) {
+            if (typeof resource.size !== 'number' || resource.size < 0) {
+                errors.push('Invalid size (must be non-negative number)');
+            }
+            if (resource.size > this.config.defaultMaxSize) {
+                warnings.push(`Resource size (${resource.size} bytes) exceeds default maximum (${this.config.defaultMaxSize} bytes)`);
+            }
+        }
+        // Timestamp validation
+        if (resource.createdAt) {
+            const date = new Date(resource.createdAt);
+            if (isNaN(date.getTime())) {
+                errors.push('Invalid createdAt timestamp');
+            }
+        }
+        // Content hash verification (if content is present)
+        if (resource.content || resource.contentBase64) {
+            const content = resource.content
+                ? Buffer.from(resource.content, 'utf-8')
+                : Buffer.from(resource.contentBase64 || '', 'base64');
+            const computedHash = this.hashContent(content);
+            if (computedHash !== resource.hash) {
+                errors.push(`Content hash mismatch: expected ${resource.hash}, computed ${computedHash}`);
+            }
+        }
+        // Check allowed content types if configured
+        if (this.config.allowedContentTypes.length > 0 &&
+            resource.contentType &&
+            !this.config.allowedContentTypes.includes(resource.contentType)) {
+            errors.push(`Content type not allowed: ${resource.contentType}`);
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+        };
+    }
+    /**
+     * Verify the integrity of a resource's version chain.
+     * Ensures that previousVersionHash references form a valid chain.
+     *
+     * @param resourceId - The logical resource ID to verify
+     * @returns ResourceValidationResult indicating chain integrity
+     */
+    verifyVersionChain(resourceId) {
+        const errors = [];
+        const warnings = [];
+        const versions = this.resources.get(resourceId);
+        if (!versions || versions.length === 0) {
+            return { valid: false, errors: ['Resource not found'], warnings: [] };
+        }
+        for (let i = 0; i < versions.length; i++) {
+            const version = versions[i];
+            // Check version numbers are sequential
+            if ((version.version || i + 1) !== i + 1) {
+                errors.push(`Version number mismatch at index ${i}: expected ${i + 1}, got ${version.version}`);
+            }
+            // First version should not have previousVersionHash
+            if (i === 0) {
+                if (version.previousVersionHash) {
+                    warnings.push('First version has previousVersionHash (should not exist for v1)');
+                }
+            }
+            else {
+                // Subsequent versions must link to previous
+                const prevVersion = versions[i - 1];
+                if (!version.previousVersionHash) {
+                    errors.push(`Version ${i + 1} missing previousVersionHash`);
+                }
+                else if (version.previousVersionHash !== prevVersion.hash) {
+                    errors.push(`Version ${i + 1} previousVersionHash mismatch: expected ${prevVersion.hash}, got ${version.previousVersionHash}`);
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+        };
+    }
+    /**
+     * Hash content using SHA-256.
+     *
+     * @param content - Content to hash (string or Buffer)
+     * @returns Hex-encoded SHA-256 hash
+     *
+     * @example
+     * ```typescript
+     * const hash = manager.hashContent('Hello, World!');
+     * console.log(hash); // 64-character hex string
+     * ```
+     */
+    hashContent(content) {
+        const buffer = this.toBuffer(content);
+        const hash = sha256(buffer);
+        return bytesToHex(hash);
+    }
+    /**
+     * Delete a resource and all its versions.
+     *
+     * @param resourceId - The resource ID to delete
+     * @returns true if deleted, false if not found
+     */
+    deleteResource(resourceId) {
+        return this.resources.delete(resourceId);
+    }
+    /**
+     * List all resource IDs managed by this instance.
+     *
+     * @returns Array of resource IDs
+     */
+    listResourceIds() {
+        return Array.from(this.resources.keys());
+    }
+    /**
+     * Get the total number of resources (unique IDs) managed.
+     *
+     * @returns Number of resources
+     */
+    getResourceCount() {
+        return this.resources.size;
+    }
+    /**
+     * Get the total number of versions across all resources.
+     *
+     * @returns Total version count
+     */
+    getTotalVersionCount() {
+        let count = 0;
+        for (const versions of this.resources.values()) {
+            count += versions.length;
+        }
+        return count;
+    }
+    /**
+     * Import a resource from an existing AssetResource.
+     * Useful for loading resources from storage or external sources.
+     *
+     * @param assetResource - The AssetResource to import
+     * @returns The imported Resource
+     */
+    importResource(assetResource) {
+        const resourceId = assetResource.id;
+        // Get or create version array
+        let versions = this.resources.get(resourceId);
+        if (!versions) {
+            versions = [];
+            this.resources.set(resourceId, versions);
+        }
+        // Check if this version already exists (by hash)
+        const existingVersion = versions.find(v => v.hash === assetResource.hash);
+        if (existingVersion) {
+            return existingVersion;
+        }
+        // Add to version array (maintain order by version number)
+        const version = assetResource.version || 1;
+        const insertIndex = versions.findIndex(v => (v.version || 1) > version);
+        if (insertIndex === -1) {
+            versions.push(assetResource);
+        }
+        else {
+            versions.splice(insertIndex, 0, assetResource);
+        }
+        return assetResource;
+    }
+    /**
+     * Export all resources as an array (for serialization).
+     *
+     * @returns Array of all resources (all versions)
+     */
+    exportResources() {
+        const allResources = [];
+        for (const versions of this.resources.values()) {
+            allResources.push(...versions);
+        }
+        return allResources;
+    }
+    /**
+     * Clear all resources from this manager.
+     */
+    clear() {
+        this.resources.clear();
+    }
+    /**
+     * Infer resource type from MIME type.
+     *
+     * @param contentType - The MIME content type
+     * @returns Inferred ResourceType
+     */
+    static inferResourceType(contentType) {
+        // Check exact match first
+        if (contentType in MIME_TYPE_MAP) {
+            return MIME_TYPE_MAP[contentType];
+        }
+        // Check by prefix
+        const prefix = contentType.split('/')[0];
+        switch (prefix) {
+            case 'image':
+                return 'image';
+            case 'audio':
+                return 'audio';
+            case 'video':
+                return 'video';
+            case 'text':
+                return 'text';
+            default:
+                return 'other';
+        }
+    }
+    /**
+     * Check if a string is a valid MIME type format.
+     */
+    isValidMimeType(mimeType) {
+        return MIME_TYPE_REGEX.test(mimeType);
+    }
+    /**
+     * Convert content to Buffer.
+     */
+    toBuffer(content) {
+        if (Buffer.isBuffer(content)) {
+            return content;
+        }
+        return Buffer.from(content, 'utf-8');
+    }
+    /**
+     * Check if content is binary (Buffer) rather than text.
+     */
+    isBinaryContent(content) {
+        return Buffer.isBuffer(content);
+    }
+}

package/dist/resources/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resources module for the Originals SDK.
+ *
+ * This module provides resource management with immutable versioning,
+ * content hashing, and validation.
+ *
+ * @module resources
+ */
+export { ResourceManager } from './ResourceManager.js';
+export type { Resource, ResourceOptions, ResourceUpdateOptions, ResourceVersionHistory, ResourceManagerConfig, ResourceValidationResult, ResourceType, } from './types.js';
+export { MIME_TYPE_MAP, DEFAULT_RESOURCE_CONFIG } from './types.js';

package/dist/resources/index.js

@@ -0,0 +1,10 @@
+/**
+ * Resources module for the Originals SDK.
+ *
+ * This module provides resource management with immutable versioning,
+ * content hashing, and validation.
+ *
+ * @module resources
+ */
+export { ResourceManager } from './ResourceManager.js';
+export { MIME_TYPE_MAP, DEFAULT_RESOURCE_CONFIG } from './types.js';

package/dist/resources/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Resource types for the Originals SDK ResourceManager.
+ *
+ * Resources in the Originals protocol are immutable, content-addressed entities
+ * that can be versioned through a linked hash chain.
+ */
+import { AssetResource } from '../types/common';
+/**
+ * Supported resource types for categorization
+ */
+export type ResourceType = 'image' | 'text' | 'code' | 'data' | 'audio' | 'video' | 'document' | 'binary' | 'other';
+/**
+ * Options for creating a new resource
+ */
+export interface ResourceOptions {
+    /** Logical resource ID (optional - will be generated if not provided) */
+    id?: string;
+    /** Resource type category */
+    type: ResourceType;
+    /** MIME content type (e.g., 'text/plain', 'image/png') */
+    contentType: string;
+    /** Optional URL if resource is externally hosted */
+    url?: string;
+    /** Optional description of the resource */
+    description?: string;
+    /** Maximum allowed size in bytes (optional, uses default if not specified) */
+    maxSize?: number;
+}
+/**
+ * Options for updating an existing resource
+ */
+export interface ResourceUpdateOptions {
+    /** New content type (optional - inherits from previous version if not specified) */
+    contentType?: string;
+    /** Description of changes made in this version */
+    changes?: string;
+}
+/**
+ * Result of resource validation
+ */
+export interface ResourceValidationResult {
+    /** Whether the resource is valid */
+    valid: boolean;
+    /** Array of error messages if validation failed */
+    errors: string[];
+    /** Array of warning messages (non-fatal issues) */
+    warnings: string[];
+}
+/**
+ * A resource with its content and metadata
+ */
+export interface Resource extends AssetResource {
+    /** The actual content (for in-memory resources) */
+    content?: string;
+    /** Binary content as base64-encoded string */
+    contentBase64?: string;
+    /** Description of the resource */
+    description?: string;
+}
+/**
+ * Complete history of a resource including all versions
+ */
+export interface ResourceVersionHistory {
+    /** Logical resource ID (stable across all versions) */
+    resourceId: string;
+    /** All versions in chronological order (oldest first) */
+    versions: Resource[];
+    /** The current (latest) version */
+    currentVersion: Resource;
+    /** Total number of versions */
+    versionCount: number;
+}
+/**
+ * Configuration for the ResourceManager
+ */
+export interface ResourceManagerConfig {
+    /** Default maximum resource size in bytes (default: 10MB) */
+    defaultMaxSize?: number;
+    /** Whether to store content in memory (default: true) */
+    storeContent?: boolean;
+    /** Allowed MIME types (if empty, all types allowed) */
+    allowedContentTypes?: string[];
+    /** Whether to enable strict MIME type validation (default: true) */
+    strictMimeValidation?: boolean;
+}
+/**
+ * Common MIME types and their resource type mappings
+ */
+export declare const MIME_TYPE_MAP: Record<string, ResourceType>;
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_RESOURCE_CONFIG: Required<ResourceManagerConfig>;