@originals/sdk 1.8.0 → 1.8.2

package/src/lifecycle/ProvenanceQuery.ts

@@ -0,0 +1,280 @@
+import { ProvenanceChain } from './OriginalsAsset';
+import { LayerType } from '../types';
+
+export type Migration = ProvenanceChain['migrations'][number];
+export type Transfer = ProvenanceChain['transfers'][number];
+
+/**
+ * Base query class for provenance inspection
+ */
+export class ProvenanceQuery {
+  protected provenance: ProvenanceChain;
+  protected afterDate?: Date;
+  protected beforeDate?: Date;
+
+  constructor(provenance: ProvenanceChain) {
+    this.provenance = provenance;
+  }
+
+  /**
+   * Query migrations
+   */
+  migrations(): MigrationQuery {
+    return new MigrationQuery(this.provenance, this.afterDate, this.beforeDate);
+  }
+
+  /**
+   * Query transfers
+   */
+  transfers(): TransferQuery {
+    return new TransferQuery(this.provenance, this.afterDate, this.beforeDate);
+  }
+
+  /**
+   * Filter by date range - after a specific date
+   */
+  after(date: Date | string): this {
+    this.afterDate = typeof date === 'string' ? new Date(date) : date;
+    return this;
+  }
+
+  /**
+   * Filter by date range - before a specific date
+   */
+  before(date: Date | string): this {
+    this.beforeDate = typeof date === 'string' ? new Date(date) : date;
+    return this;
+  }
+
+  /**
+   * Filter by date range - between two dates
+   */
+  between(start: Date | string, end: Date | string): this {
+    this.afterDate = typeof start === 'string' ? new Date(start) : start;
+    this.beforeDate = typeof end === 'string' ? new Date(end) : end;
+    return this;
+  }
+
+  /**
+   * Get count of results
+   */
+  count(): number {
+    return this.all().length;
+  }
+
+  /**
+   * Get first result
+   */
+  first(): Migration | Transfer | null {
+    const results = this.all();
+    return results.length > 0 ? results[0] : null;
+  }
+
+  /**
+   * Get last result
+   */
+  last(): Migration | Transfer | null {
+    const results = this.all();
+    return results.length > 0 ? results[results.length - 1] : null;
+  }
+
+  /**
+   * Get all results
+   */
+  all(): Array<Migration | Transfer> {
+    const merged = [...this.provenance.migrations, ...this.provenance.transfers];
+    const filtered = this.applyDateFilters(merged);
+    return filtered.sort(
+      (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
+    );
+  }
+
+  /**
+   * Apply date filters to items
+   */
+  protected applyDateFilters<T extends { timestamp: string }>(items: T[]): T[] {
+    let filtered = items;
+
+    if (this.afterDate) {
+      filtered = filtered.filter(item => new Date(item.timestamp) > this.afterDate!);
+    }
+
+    if (this.beforeDate) {
+      filtered = filtered.filter(item => new Date(item.timestamp) < this.beforeDate!);
+    }
+
+    return filtered;
+  }
+}
+
+/**
+ * Query class for migrations
+ */
+export class MigrationQuery extends ProvenanceQuery {
+  private fromLayerFilter?: LayerType;
+  private toLayerFilter?: LayerType;
+  private transactionIdFilter?: string;
+  private inscriptionIdFilter?: string;
+
+  constructor(provenance: ProvenanceChain, afterDate?: Date, beforeDate?: Date) {
+    super(provenance);
+    this.afterDate = afterDate;
+    this.beforeDate = beforeDate;
+  }
+
+  /**
+   * Filter by source layer
+   */
+  fromLayer(layer: LayerType): this {
+    this.fromLayerFilter = layer;
+    return this;
+  }
+
+  /**
+   * Filter by destination layer
+   */
+  toLayer(layer: LayerType): this {
+    this.toLayerFilter = layer;
+    return this;
+  }
+
+  /**
+   * Filter by transaction ID
+   */
+  withTransaction(txId: string): this {
+    this.transactionIdFilter = txId;
+    return this;
+  }
+
+  /**
+   * Filter by inscription ID
+   */
+  withInscription(inscriptionId: string): this {
+    this.inscriptionIdFilter = inscriptionId;
+    return this;
+  }
+
+  /**
+   * Get all filtered migrations
+   */
+  all(): Migration[] {
+    let results = [...this.provenance.migrations];
+
+    // Apply date filters
+    results = this.applyDateFilters(results);
+
+    // Apply layer filters
+    if (this.fromLayerFilter) {
+      results = results.filter(m => m.from === this.fromLayerFilter);
+    }
+
+    if (this.toLayerFilter) {
+      results = results.filter(m => m.to === this.toLayerFilter);
+    }
+
+    // Apply transaction ID filter
+    if (this.transactionIdFilter) {
+      results = results.filter(m => m.transactionId === this.transactionIdFilter);
+    }
+
+    // Apply inscription ID filter
+    if (this.inscriptionIdFilter) {
+      results = results.filter(m => m.inscriptionId === this.inscriptionIdFilter);
+    }
+
+    return results;
+  }
+
+  /**
+   * Override migrations to return this (method chaining)
+   */
+  migrations(): MigrationQuery {
+    return this;
+  }
+
+  /**
+   * Override transfers to create new TransferQuery with date filters
+   */
+  transfers(): TransferQuery {
+    return new TransferQuery(this.provenance, this.afterDate, this.beforeDate);
+  }
+}
+
+/**
+ * Query class for transfers
+ */
+export class TransferQuery extends ProvenanceQuery {
+  private fromAddressFilter?: string;
+  private toAddressFilter?: string;
+  private transactionIdFilter?: string;
+
+  constructor(provenance: ProvenanceChain, afterDate?: Date, beforeDate?: Date) {
+    super(provenance);
+    this.afterDate = afterDate;
+    this.beforeDate = beforeDate;
+  }
+
+  /**
+   * Filter by source address
+   */
+  from(address: string): this {
+    this.fromAddressFilter = address;
+    return this;
+  }
+
+  /**
+   * Filter by destination address
+   */
+  to(address: string): this {
+    this.toAddressFilter = address;
+    return this;
+  }
+
+  /**
+   * Filter by transaction ID
+   */
+  withTransaction(txId: string): this {
+    this.transactionIdFilter = txId;
+    return this;
+  }
+
+  /**
+   * Get all filtered transfers
+   */
+  all(): Transfer[] {
+    let results = [...this.provenance.transfers];
+
+    // Apply date filters
+    results = this.applyDateFilters(results);
+
+    // Apply address filters
+    if (this.fromAddressFilter) {
+      results = results.filter(t => t.from === this.fromAddressFilter);
+    }
+
+    if (this.toAddressFilter) {
+      results = results.filter(t => t.to === this.toAddressFilter);
+    }
+
+    // Apply transaction ID filter
+    if (this.transactionIdFilter) {
+      results = results.filter(t => t.transactionId === this.transactionIdFilter);
+    }
+
+    return results;
+  }
+
+  /**
+   * Override transfers to return this (method chaining)
+   */
+  transfers(): TransferQuery {
+    return this;
+  }
+
+  /**
+   * Override migrations to create new MigrationQuery with date filters
+   */
+  migrations(): MigrationQuery {
+    return new MigrationQuery(this.provenance, this.afterDate, this.beforeDate);
+  }
+}

package/src/lifecycle/ResourceVersioning.ts

@@ -0,0 +1,163 @@
+/**
+ * ResourceVersioning module for immutable resource versioning with verifiable provenance.
+ * 
+ * Resources in the Originals SDK are immutable and content-addressed. "Versioning" means
+ * creating a new immutable resource instance with a new hash and linking it to the prior
+ * version via previousVersionHash. Old versions remain accessible.
+ */
+
+export interface ResourceVersion {
+  version: number;
+  hash: string;               // Unique content hash
+  timestamp: string;          // ISO timestamp
+  contentType: string;
+  changes?: string;           // Optional change description
+  previousVersionHash?: string;
+}
+
+export interface ResourceHistory {
+  resourceId: string;         // Logical ID (same across versions)
+  versions: ResourceVersion[];
+  currentVersion: ResourceVersion;
+}
+
+/**
+ * ResourceVersionManager manages the versioning of immutable resources.
+ * Each version is a separate resource with a unique content hash, linked to
+ * its predecessor via previousVersionHash.
+ */
+export class ResourceVersionManager {
+  private versionMap: Map<string, ResourceVersion[]>;
+
+  constructor() {
+    this.versionMap = new Map();
+  }
+
+  /**
+   * Add a new version for a resource
+   * @param resourceId - Logical resource ID (stable across versions)
+   * @param hash - Content hash of the new version
+   * @param contentType - Content type of the resource
+   * @param previousVersionHash - Hash of the previous version (optional for v1)
+   * @param changes - Optional description of changes
+   */
+  addVersion(
+    resourceId: string,
+    hash: string,
+    contentType: string,
+    previousVersionHash?: string,
+    changes?: string
+  ): void {
+    const versions = this.versionMap.get(resourceId) || [];
+    
+    const version: ResourceVersion = {
+      version: versions.length + 1,
+      hash,
+      timestamp: new Date().toISOString(),
+      contentType,
+      changes,
+      previousVersionHash
+    };
+    
+    versions.push(version);
+    this.versionMap.set(resourceId, versions);
+  }
+
+  /**
+   * Get the complete version history for a resource
+   * @param resourceId - Logical resource ID
+   * @returns ResourceHistory or null if resource doesn't exist
+   */
+  getHistory(resourceId: string): ResourceHistory | null {
+    const versions = this.versionMap.get(resourceId);
+    if (!versions || versions.length === 0) {
+      return null;
+    }
+
+    return {
+      resourceId,
+      versions: [...versions],
+      currentVersion: versions[versions.length - 1]
+    };
+  }
+
+  /**
+   * Get a specific version of a resource
+   * @param resourceId - Logical resource ID
+   * @param version - Version number (1-indexed)
+   * @returns ResourceVersion or null if not found
+   */
+  getVersion(resourceId: string, version: number): ResourceVersion | null {
+    const versions = this.versionMap.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 - Logical resource ID
+   * @returns ResourceVersion or null if not found
+   */
+  getCurrentVersion(resourceId: string): ResourceVersion | null {
+    const versions = this.versionMap.get(resourceId);
+    if (!versions || versions.length === 0) {
+      return null;
+    }
+    return versions[versions.length - 1];
+  }
+
+  /**
+   * Verify the integrity of the version chain for a resource.
+   * Ensures that:
+   * - Version numbers are sequential starting at 1
+   * - Each version (except v1) has a previousVersionHash
+   * - Each previousVersionHash matches the actual previous version's hash
+   * 
+   * @param resourceId - Logical resource ID
+   * @returns true if the chain is valid, false otherwise
+   */
+  verifyChain(resourceId: string): boolean {
+    const versions = this.versionMap.get(resourceId);
+    if (!versions || versions.length === 0) {
+      return false;
+    }
+
+    for (let i = 0; i < versions.length; i++) {
+      const version = versions[i];
+      
+      // Check version number is sequential
+      if (version.version !== i + 1) {
+        return false;
+      }
+
+      // First version should not have previousVersionHash
+      if (i === 0) {
+        if (version.previousVersionHash !== undefined) {
+          return false;
+        }
+      } else {
+        // Subsequent versions must have previousVersionHash matching the prior version
+        const prevVersion = versions[i - 1];
+        if (version.previousVersionHash !== prevVersion.hash) {
+          return false;
+        }
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Serialize the version manager state to JSON
+   * @returns Object representation of all version data
+   */
+  toJSON(): object {
+    const result: Record<string, ResourceVersion[]> = {};
+    for (const [resourceId, versions] of this.versionMap.entries()) {
+      result[resourceId] = versions;
+    }
+    return result;
+  }
+}