@cmdoss/memwal-sdk 0.6.0

package/src/client/namespaces/StorageNamespace.ts

@@ -0,0 +1,458 @@
+/**
+ * Storage Namespace - Direct Walrus Storage Operations
+ *
+ * Simple wrapper around StorageService for direct Walrus access.
+ * Delegates to existing storage managers:
+ * - WalrusStorageManager (upload/download)
+ * - QuiltBatchManager (batch operations)
+ * - WalrusMetadataManager (metadata)
+ * - BlobAttributesManager (dynamic fields)
+ *
+ * @module client/namespaces
+ */
+
+import type { ServiceContainer } from '../SimplePDWClient';
+
+/**
+ * Upload result
+ */
+export interface UploadResult {
+  blobId: string;
+  size: number;
+  contentType?: string;
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Quilt result (batch upload)
+ */
+export interface QuiltResult {
+  quiltId: string;
+  files: Array<{
+    name: string;
+    blobId: string;
+    size: number;
+  }>;
+  totalSize: number;
+}
+
+/**
+ * Blob metadata
+ */
+export interface BlobMetadata {
+  [key: string]: string | number | boolean;
+}
+
+/**
+ * File for batch upload
+ */
+export interface FileUpload {
+  name: string;
+  data: Uint8Array;
+  contentType?: string;
+}
+
+/**
+ * Storage statistics
+ */
+export interface StorageStats {
+  totalBlobs: number;
+  totalSize: number;
+  blobsByCategory: Record<string, number>;
+}
+
+/**
+ * Storage Namespace
+ *
+ * Handles direct Walrus storage operations
+ */
+export class StorageNamespace {
+  constructor(private services: ServiceContainer) {}
+
+  /**
+   * Upload data to Walrus
+   *
+   * Delegates to StorageService.uploadBlob() (WalrusStorageManager)
+   *
+   * @param data - Data bytes to upload
+   * @param metadata - Optional metadata
+   * @returns Upload result with blob ID
+   *
+   * @example
+   * ```typescript
+   * const data = new TextEncoder().encode('Hello world');
+   * const result = await pdw.storage.upload(data, {
+   *   contentType: 'text/plain',
+   *   category: 'document'
+   * });
+   * ```
+   */
+  async upload(data: Uint8Array, metadata?: BlobMetadata): Promise<UploadResult> {
+    try {
+      // Delegate to StorageService (uses WalrusStorageManager internally)
+      const result = await this.services.storage.uploadBlob(
+        data,
+        {
+          signer: this.services.config.signer.getSigner(),
+          epochs: 3,
+          deletable: true,
+          metadata: metadata as any
+        }
+      );
+
+      return {
+        blobId: result.blobId,
+        size: data.length,
+        metadata
+      };
+    } catch (error) {
+      throw new Error(`Upload failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Download data from Walrus
+   *
+   * @param blobId - Blob ID to download
+   * @returns Data bytes
+   */
+  async download(blobId: string): Promise<Uint8Array> {
+    try {
+      const result = await this.services.storage.retrieve(blobId);
+
+      if (result instanceof Uint8Array) {
+        return result;
+      }
+
+      // Convert string to Uint8Array if needed
+      if (typeof result === 'string') {
+        return new TextEncoder().encode(result);
+      }
+
+      throw new Error('Unexpected blob format');
+    } catch (error) {
+      throw new Error(`Download failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Delete a blob (soft delete)
+   *
+   * Walrus blobs are immutable and cannot be truly deleted.
+   * This marks the blob as deleted by setting a `deleted_at` attribute on-chain.
+   * The blob data remains on Walrus but will be filtered out in queries.
+   *
+   * @param blobId - Blob ID to mark as deleted
+   */
+  async delete(blobId: string): Promise<void> {
+    try {
+      if (!blobId) {
+        throw new Error('Blob ID is required');
+      }
+
+      // Mark as deleted by setting deleted_at attribute
+      // This is a soft delete - the blob remains on Walrus but is marked as deleted
+      await this.services.storage.updateBlobAttributes(
+        blobId,
+        {
+          deleted_at: new Date().toISOString(),
+          deleted_by: this.services.config.userAddress
+        },
+        this.services.config.signer.getSigner()
+      );
+
+      console.log(`Blob ${blobId} marked as deleted`);
+    } catch (error) {
+      throw new Error(`Delete failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Upload multiple files as a Quilt (batch)
+   *
+   * @param files - Array of files to upload
+   * @returns Quilt result with file mappings
+   */
+  async uploadBatch(files: FileUpload[]): Promise<QuiltResult> {
+    try {
+      // Use uploadMemoryBatch (StorageService has this, not uploadQuilt)
+      const memories = files.map(f => ({
+        content: new TextDecoder().decode(f.data),
+        category: 'general',
+        importance: 5,
+        topic: f.name,
+        embedding: [] as number[],
+        encryptedContent: f.data,  // Use file data as encrypted content
+        summary: ''
+      }));
+
+      const result = await this.services.storage.uploadMemoryBatch(
+        memories,
+        {
+          signer: this.services.config.signer.getSigner(),
+          epochs: 3,
+          userAddress: this.services.config.userAddress
+        }
+      );
+
+      return {
+        quiltId: result.quiltId,
+        files: result.files.map((f: any) => ({
+          name: f.identifier,
+          blobId: f.blobId,
+          size: 0  // Size not available in result
+        })),
+        totalSize: files.reduce((sum, f) => sum + f.data.length, 0)
+      };
+    } catch (error) {
+      throw new Error(`Batch upload failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Download multiple files from a Quilt
+   *
+   * Retrieves all WalrusFiles from a quilt and downloads their content.
+   * File names are extracted from identifiers or tags.
+   *
+   * @param quiltId - Quilt ID
+   * @returns Array of files with name and data
+   */
+  async downloadBatch(quiltId: string): Promise<Array<{ name: string; data: Uint8Array }>> {
+    try {
+      if (!quiltId) {
+        throw new Error('Quilt ID is required');
+      }
+
+      // Get all WalrusFile objects from quilt
+      const files = await this.services.storage.getQuiltFiles(quiltId);
+
+      if (!files || files.length === 0) {
+        console.warn(`No files found in quilt ${quiltId}`);
+        return [];
+      }
+
+      // Download each file in parallel
+      const results = await Promise.all(
+        files.map(async (file: any, index: number) => {
+          try {
+            // Extract name from identifier or tags
+            let name = `file-${index}`;
+
+            // Try to get identifier (filename)
+            if (typeof file.getIdentifier === 'function') {
+              const identifier = file.getIdentifier();
+              if (identifier) {
+                name = identifier;
+              }
+            }
+
+            // Try to get name from tags as fallback
+            if (name === `file-${index}` && typeof file.getTags === 'function') {
+              const tags = await file.getTags();
+              if (tags?.topic) {
+                name = tags.topic;
+              }
+            }
+
+            // Get blob content - WalrusFile should have blob reference
+            let data: Uint8Array;
+
+            // Try to read content directly from file if available
+            if (typeof file.read === 'function') {
+              data = await file.read();
+            } else if (file.blobId) {
+              // Fallback: retrieve via blobId
+              const result = await this.services.storage.retrieve(file.blobId);
+              data = result instanceof Uint8Array ? result : new TextEncoder().encode(String(result));
+            } else if (file.contents) {
+              // Direct contents access
+              data = file.contents instanceof Uint8Array
+                ? file.contents
+                : new TextEncoder().encode(String(file.contents));
+            } else {
+              throw new Error(`Cannot extract content from file at index ${index}`);
+            }
+
+            return { name, data };
+          } catch (fileError) {
+            console.warn(`Failed to download file at index ${index}:`, fileError);
+            // Return empty data for failed files instead of throwing
+            return { name: `file-${index}-error`, data: new Uint8Array(0) };
+          }
+        })
+      );
+
+      // Filter out failed downloads (empty data)
+      return results.filter(r => r.data.length > 0);
+    } catch (error) {
+      throw new Error(`Batch download failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Set metadata for a blob
+   *
+   * @param blobId - Blob ID
+   * @param metadata - Metadata to attach
+   */
+  async setMetadata(blobId: string, metadata: BlobMetadata): Promise<void> {
+    try {
+      // Use attachMetadataToBlob (correct method name)
+      await this.services.storage.attachMetadataToBlob(
+        blobId,
+        metadata as any,
+        this.services.config.signer.getSigner()
+      );
+    } catch (error) {
+      throw new Error(`Set metadata failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Get metadata for a blob
+   *
+   * @param blobId - Blob ID
+   * @returns Blob metadata
+   */
+  async getMetadata(blobId: string): Promise<BlobMetadata> {
+    try {
+      // Use retrieveBlobMetadata (correct method name)
+      const metadata = await this.services.storage.retrieveBlobMetadata(blobId);
+      return metadata as BlobMetadata;
+    } catch (error) {
+      throw new Error(`Get metadata failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * List blobs for user
+   *
+   * @param filter - Optional filter
+   * @returns Array of blob info
+   */
+  async listBlobs(filter?: { category?: string; limit?: number }): Promise<Array<{ blobId: string; metadata: BlobMetadata }>> {
+    try {
+      // Use searchByMetadata
+      const results = await this.services.storage.searchByMetadata(
+        this.services.config.userAddress,
+        {} // MetadataSearchQuery - minimal params
+      );
+
+      return results.map((r: any) => ({
+        blobId: r.blobId,
+        metadata: r.metadata || {}
+      }));
+    } catch (error) {
+      throw new Error(`List blobs failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Get storage statistics
+   *
+   * Calculates total size from blob metadata (content_size field).
+   *
+   * @returns Storage stats
+   */
+  async getStats(): Promise<StorageStats> {
+    try {
+      // Get all blobs
+      const blobs = await this.listBlobs({ limit: 1000 });
+
+      const stats: StorageStats = {
+        totalBlobs: blobs.length,
+        totalSize: 0,
+        blobsByCategory: {}
+      };
+
+      // Count by category and accumulate size
+      blobs.forEach(b => {
+        const category = b.metadata.category as string || 'general';
+        stats.blobsByCategory[category] = (stats.blobsByCategory[category] || 0) + 1;
+
+        // Sum up content sizes from metadata
+        const size = Number(b.metadata.content_size || b.metadata.contentSize || b.metadata.size || 0);
+        if (!isNaN(size)) {
+          stats.totalSize += size;
+        }
+      });
+
+      return stats;
+    } catch (error) {
+      throw new Error(`Get storage stats failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Cleanup old or unused blobs
+   *
+   * Marks blobs as deleted if they meet cleanup criteria:
+   * - Already marked as deleted (removes from active queries)
+   * - Low importance and old (optional aggressive cleanup)
+   *
+   * Note: Walrus blobs cannot be truly deleted. This marks them
+   * as deleted via attributes for filtering in queries.
+   *
+   * @param options - Cleanup options
+   * @returns Number of blobs marked for cleanup
+   */
+  async cleanup(options?: {
+    /** Remove blobs already marked as deleted from listings */
+    removeDeleted?: boolean;
+    /** Mark old, low-importance blobs as deleted */
+    aggressiveCleanup?: boolean;
+    /** Max age in days for aggressive cleanup (default: 90) */
+    maxAgeDays?: number;
+    /** Max importance for aggressive cleanup (default: 3) */
+    maxImportance?: number;
+  }): Promise<number> {
+    try {
+      const {
+        removeDeleted = true,
+        aggressiveCleanup = false,
+        maxAgeDays = 90,
+        maxImportance = 3
+      } = options || {};
+
+      let cleanedCount = 0;
+      const blobs = await this.listBlobs({ limit: 1000 });
+
+      for (const blob of blobs) {
+        try {
+          const metadata = blob.metadata;
+
+          // Skip if already processed
+          if (metadata.deleted_at) {
+            continue;
+          }
+
+          // Aggressive cleanup: mark old, low-importance blobs
+          if (aggressiveCleanup) {
+            const importance = Number(metadata.importance) || 5;
+            const createdAt = metadata.created_at
+              ? new Date(metadata.created_at as string).getTime()
+              : Date.now();
+            const ageInDays = (Date.now() - createdAt) / (1000 * 60 * 60 * 24);
+
+            if (importance <= maxImportance && ageInDays >= maxAgeDays) {
+              await this.delete(blob.blobId);
+              cleanedCount++;
+              console.log(`Cleaned up old blob ${blob.blobId} (age: ${ageInDays.toFixed(0)} days, importance: ${importance})`);
+            }
+          }
+        } catch (blobError) {
+          console.warn(`Failed to process blob ${blob.blobId} during cleanup:`, blobError);
+        }
+      }
+
+      if (cleanedCount > 0) {
+        console.log(`Storage cleanup completed: ${cleanedCount} blobs marked for cleanup`);
+      }
+
+      return cleanedCount;
+    } catch (error) {
+      throw new Error(`Cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}

package/src/client/namespaces/TxNamespace.ts

@@ -0,0 +1,260 @@
+/**
+ * Tx Namespace - Transaction Utilities
+ *
+ * Pure delegation to TransactionService for PTB building and execution.
+ * Provides convenient methods for common blockchain operations.
+ *
+ * @module client/namespaces
+ */
+
+import type { ServiceContainer } from '../SimplePDWClient';
+import { Transaction } from '@mysten/sui/transactions';
+import type { TransactionResult } from '../../types';
+
+/**
+ * Memory transaction options
+ */
+export interface MemoryTxOptions {
+  category: string;
+  vectorId: number;
+  blobId: string;
+  importance: number;
+  gasBudget?: number;
+}
+
+/**
+ * Batch operation types supported by PTB
+ */
+export type BatchOperationType = 'createMemory' | 'updateMemory' | 'deleteMemory' | 'createCap' | 'transferCap' | 'burnCap';
+
+/**
+ * Batch operation definition
+ */
+export interface BatchOperation {
+  type: BatchOperationType;
+  options: any;
+}
+
+/**
+ * Tx Namespace
+ *
+ * Handles transaction building and execution utilities
+ */
+export class TxNamespace {
+  constructor(private services: ServiceContainer) {}
+
+  /**
+   * Build transaction for creating memory record
+   *
+   * Delegates to: TransactionService.buildCreateMemoryRecordLightweight()
+   *
+   * @param options - Memory creation options
+   * @returns Transaction object
+   */
+  buildCreate(options: MemoryTxOptions): Transaction {
+    if (!this.services.tx) {
+      throw new Error('Transaction service not configured.');
+    }
+
+    return this.services.tx.buildCreateMemoryRecordLightweight({
+      category: options.category,
+      vectorId: options.vectorId,
+      blobId: options.blobId,
+      importance: options.importance,
+      gasBudget: options.gasBudget
+    });
+  }
+
+  /**
+   * Build transaction for updating memory metadata
+   *
+   * Delegates to: TransactionService.buildUpdateMemoryMetadata()
+   *
+   * @param memoryId - Memory ID to update
+   * @param metadataBlobId - New metadata blob ID
+   * @returns Transaction object
+   */
+  buildUpdate(memoryId: string, metadataBlobId: string): Transaction {
+    if (!this.services.tx) {
+      throw new Error('Transaction service not configured.');
+    }
+
+    return this.services.tx.buildUpdateMemoryMetadata({
+      memoryId,
+      metadataBlobId,
+      embeddingDimension: 3072 // Default for Gemini
+    });
+  }
+
+  /**
+   * Build transaction for deleting memory record
+   *
+   * Delegates to: TransactionService.buildDeleteMemoryRecord()
+   *
+   * @param memoryId - Memory ID to delete
+   * @returns Transaction object
+   */
+  buildDelete(memoryId: string): Transaction {
+    if (!this.services.tx) {
+      throw new Error('Transaction service not configured.');
+    }
+
+    return this.services.tx.buildDeleteMemoryRecord({
+      memoryId
+    });
+  }
+
+  /**
+   * Execute a transaction
+   *
+   * Delegates to: TransactionService.executeTransaction()
+   *
+   * @param tx - Transaction to execute
+   * @returns Transaction result with digest and status
+   */
+  async execute(tx: Transaction): Promise<TransactionResult> {
+    if (!this.services.tx) {
+      throw new Error('Transaction service not configured.');
+    }
+
+    return await this.services.tx.executeTransaction(
+      tx,
+      this.services.config.signer.getSigner()
+    );
+  }
+
+  /**
+   * Build and execute in one call
+   *
+   * Convenience method combining build + execute
+   *
+   * @param options - Memory creation options
+   * @returns Transaction result
+   */
+  async createMemory(options: MemoryTxOptions): Promise<TransactionResult> {
+    const tx = this.buildCreate(options);
+    return await this.execute(tx);
+  }
+
+  /**
+   * Build batch transaction (combine multiple operations into single PTB)
+   *
+   * Delegates to TransactionService.buildBatchTransaction() for proper PTB composition.
+   * All operations are executed atomically in a single transaction.
+   *
+   * @param operations - Array of typed operations to batch
+   * @returns Combined transaction with all move calls
+   *
+   * @example
+   * ```typescript
+   * const tx = pdw.tx.buildBatch([
+   *   { type: 'createMemory', options: { category: 'note', vectorId: 1, blobId: 'abc', importance: 5 } },
+   *   { type: 'createMemory', options: { category: 'task', vectorId: 2, blobId: 'def', importance: 7 } },
+   * ]);
+   * const result = await pdw.tx.execute(tx);
+   * ```
+   */
+  buildBatch(operations: BatchOperation[]): Transaction {
+    if (!this.services.tx) {
+      throw new Error('Transaction service not configured.');
+    }
+
+    return this.services.tx.buildBatchTransaction(operations);
+  }
+
+  /**
+   * Build and execute batch transaction in one call
+   *
+   * Convenience method combining buildBatch + execute
+   *
+   * @param operations - Array of typed operations to batch
+   * @param gasBudget - Optional gas budget override
+   * @returns Transaction result with digest and status
+   *
+   * @example
+   * ```typescript
+   * const result = await pdw.tx.executeBatch([
+   *   { type: 'createMemory', options: { ... } },
+   *   { type: 'deleteMemory', options: { memoryId: '0x123' } },
+   * ]);
+   * ```
+   */
+  async executeBatch(operations: BatchOperation[], gasBudget?: number): Promise<TransactionResult> {
+    if (!this.services.tx) {
+      throw new Error('Transaction service not configured.');
+    }
+
+    return await this.services.tx.executeBatch(
+      operations,
+      this.services.config.signer.getSigner(),
+      { gasBudget }
+    );
+  }
+
+  /**
+   * Estimate gas cost for transaction
+   *
+   * Dry-runs transaction to estimate gas
+   *
+   * @param tx - Transaction to estimate
+   * @returns Estimated gas cost
+   */
+  async estimateGas(tx: Transaction): Promise<number> {
+    if (!this.services.tx) {
+      throw new Error('Transaction service not configured.');
+    }
+
+    try {
+      // Use Sui client to dry-run
+      const dryRun = await this.services.config.sui.client.dryRunTransactionBlock({
+        transactionBlock: await tx.build({ client: this.services.config.sui.client })
+      });
+
+      const gasUsed = dryRun.effects.gasUsed;
+      const totalGas =
+        Number(gasUsed.computationCost) +
+        Number(gasUsed.storageCost) -
+        Number(gasUsed.storageRebate);
+
+      return totalGas;
+    } catch (error) {
+      throw new Error(`Gas estimation failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Wait for transaction confirmation
+   *
+   * Waits for transaction to be confirmed on-chain
+   *
+   * @param digest - Transaction digest
+   * @returns Transaction effects
+   */
+  async waitForConfirmation(digest: string): Promise<TransactionResult> {
+    if (!this.services.tx) {
+      throw new Error('Transaction service not configured.');
+    }
+
+    try {
+      const result = await this.services.config.sui.client.waitForTransaction({
+        digest,
+        options: {
+          showEffects: true,
+          showObjectChanges: true,
+          showEvents: true
+        }
+      });
+
+      return {
+        digest: result.digest,
+        status: result.effects?.status?.status === 'success' ? 'success' : 'failure',
+        effects: result.effects,
+        gasUsed: result.effects?.gasUsed?.computationCost
+          ? Number(result.effects.gasUsed.computationCost)
+          : undefined
+      };
+    } catch (error) {
+      throw new Error(`Wait for confirmation failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}