@cmdoss/memwal-sdk 0.6.0

package/src/client/namespaces/BatchNamespace.ts

@@ -0,0 +1,356 @@
+/**
+ * Batch Namespace - Batch Processing Operations
+ *
+ * Pure delegation to BatchService for coordinated batch operations.
+ * Handles intelligent batching with configurable delays and sizes.
+ *
+ * @module client/namespaces
+ */
+
+import type { ServiceContainer } from '../SimplePDWClient';
+import type { BatchItem, BatchProcessor } from '../../services/BatchService';
+
+/**
+ * Batch progress info
+ */
+export interface BatchProgress {
+  total: number;
+  completed: number;
+  failed: number;
+  inProgress: number;
+  percentage: number;
+}
+
+/**
+ * Batch statistics
+ */
+export interface BatchStatistics {
+  totalBatches: number;
+  totalItems: number;
+  averageBatchSize: number;
+  totalProcessingTime: number;
+  averageProcessingTime: number;
+  successCount: number;
+  errorCount: number;
+  lastProcessed: Date;
+}
+
+/**
+ * Batch Namespace
+ *
+ * Handles batch processing operations with intelligent queuing
+ */
+export class BatchNamespace {
+  constructor(private services: ServiceContainer) {}
+
+  /**
+   * Create many memories in batch
+   *
+   * Delegates to: MemoryNamespace.createBatch()
+   *
+   * @param contents - Array of content strings
+   * @param options - Optional creation options
+   * @returns Array of created memory objects
+   */
+  async createMany(
+    contents: string[],
+    options?: {
+      category?: 'general' | 'preference' | 'fact' | 'todo' | 'note';
+      importance?: number;
+    }
+  ): Promise<Array<{ id: string; blobId: string }>> {
+    if (!this.services.batchService) {
+      throw new Error('Batch service not configured.');
+    }
+
+    // Import MemoryNamespace to reuse existing batch create logic
+    const { MemoryNamespace } = await import('./MemoryNamespace');
+    const memoryNamespace = new MemoryNamespace(this.services);
+
+    // Delegate to existing createBatch method which handles everything
+    const memories = await memoryNamespace.createBatch(
+      contents,
+      {
+        category: options?.category,
+        importance: options?.importance
+      }
+    );
+
+    return memories.map(m => ({
+      id: m.id,
+      blobId: m.blobId
+    }));
+  }
+
+  /**
+   * Update many memories in batch
+   *
+   * Updates memories in parallel:
+   * 1. For updates with new content: uploads new blobs to Walrus
+   * 2. Executes on-chain update transactions
+   * 3. Updates local vector index if enabled
+   *
+   * @param updates - Array of {id, content, category, importance, topic}
+   * @returns Array of successfully updated memory IDs
+   */
+  async updateMany(
+    updates: Array<{
+      id: string;
+      content?: string;
+      category?: string;
+      importance?: number;
+      topic?: string;
+    }>
+  ): Promise<string[]> {
+    if (!this.services.batchService) {
+      throw new Error('Batch service not configured.');
+    }
+
+    if (!this.services.tx) {
+      throw new Error('Transaction service not configured.');
+    }
+
+    const successfulIds: string[] = [];
+    const errors: Array<{ id: string; error: string }> = [];
+
+    // Process updates in parallel batches
+    const BATCH_SIZE = 5; // Process 5 at a time to avoid overwhelming network
+
+    for (let i = 0; i < updates.length; i += BATCH_SIZE) {
+      const batch = updates.slice(i, i + BATCH_SIZE);
+
+      const batchPromises = batch.map(async (update) => {
+        try {
+          let newBlobId = '';
+          let newContentHash = '';
+          let newContentSize = 0;
+
+          // Step 1: If content changed, upload new blob to Walrus
+          if (update.content) {
+            // Generate embedding if service available
+            let embedding: number[] = [];
+            if (this.services.embedding) {
+              const embResult = await this.services.embedding.embedText({
+                text: update.content
+              });
+              embedding = embResult.vector;
+            }
+
+            // Upload new content
+            const uploadResult = await this.services.storage.uploadMemoryPackage(
+              {
+                content: update.content,
+                embedding,
+                metadata: {
+                  category: update.category || 'general',
+                  importance: update.importance || 5,
+                  topic: update.topic || ''
+                },
+                identity: this.services.config.userAddress
+              },
+              {
+                signer: this.services.config.signer.getSigner(),
+                epochs: 3,
+                deletable: true
+              }
+            );
+
+            newBlobId = uploadResult.blobId;
+            newContentHash = uploadResult.blobId; // blob_id is content-addressed
+            newContentSize = update.content.length;
+          }
+
+          // Step 2: Build and execute update transaction
+          const tx = this.services.tx!.buildUpdateMemoryRecord({
+            memoryId: update.id,
+            newBlobId,
+            newCategory: update.category || '',
+            newTopic: update.topic || '',
+            newImportance: update.importance || 0,
+            newEmbeddingBlobId: '',
+            newContentHash,
+            newContentSize
+          });
+
+          const result = await this.services.tx!.executeTransaction(
+            tx,
+            this.services.config.signer.getSigner()
+          );
+
+          if (result.status !== 'success') {
+            throw new Error(result.error || 'Transaction failed');
+          }
+
+          // Step 3: Update local vector index if content changed
+          if (update.content && this.services.vector && this.services.embedding) {
+            const embResult = await this.services.embedding.embedText({
+              text: update.content
+            });
+            await this.services.vector.addVector(
+              this.services.config.userAddress,
+              Date.now(), // vectorId
+              embResult.vector,
+              {
+                category: update.category,
+                importance: update.importance,
+                topic: update.topic
+              }
+            );
+          }
+
+          return { success: true, id: update.id };
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          console.warn(`Failed to update memory ${update.id}:`, errorMsg);
+          return { success: false, id: update.id, error: errorMsg };
+        }
+      });
+
+      const batchResults = await Promise.all(batchPromises);
+
+      for (const result of batchResults) {
+        if (result.success) {
+          successfulIds.push(result.id);
+        } else {
+          errors.push({ id: result.id, error: result.error || 'Unknown error' });
+        }
+      }
+    }
+
+    if (errors.length > 0) {
+      console.warn(`Batch update completed with ${errors.length} errors:`, errors);
+    }
+
+    return successfulIds;
+  }
+
+  /**
+   * Delete many memories in batch
+   *
+   * Delegates to: MemoryService.deleteMemoryRecord() for each
+   *
+   * @param ids - Array of memory IDs
+   * @returns Number of successfully deleted
+   */
+  async deleteMany(ids: string[]): Promise<number> {
+    if (!this.services.batchService) {
+      throw new Error('Batch service not configured.');
+    }
+
+    let successCount = 0;
+
+    for (const id of ids) {
+      try {
+        // Build and execute delete transaction
+        const tx = await this.services.memory.tx.deleteMemory(id);
+        await this.services.config.signer.signAndExecuteTransaction(tx);
+        successCount++;
+      } catch (error) {
+        console.warn(`Failed to delete memory ${id}:`, error);
+      }
+    }
+
+    return successCount;
+  }
+
+  /**
+   * Upload many files in batch
+   *
+   * Delegates to: StorageService.uploadMemoryBatch()
+   *
+   * @param files - Array of {name, data}
+   * @returns Quilt result with blob IDs
+   */
+  async uploadMany(
+    files: Array<{ name: string; data: Uint8Array }>
+  ): Promise<{ quiltId: string; files: Array<{ name: string; blobId: string }> }> {
+    if (!this.services.batchService) {
+      throw new Error('Batch service not configured.');
+    }
+
+    // Convert to memory format for batch upload
+    const memories = files.map(f => ({
+      content: new TextDecoder().decode(f.data),
+      category: 'file' as const,
+      importance: 5,
+      topic: f.name,
+      embedding: [] as number[],
+      encryptedContent: f.data,
+      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
+      }))
+    };
+  }
+
+  /**
+   * Get batch processing progress
+   *
+   * Delegates to: BatchService.getStats()
+   *
+   * @returns Current batch progress
+   */
+  getProgress(): BatchProgress {
+    if (!this.services.batchService) {
+      throw new Error('Batch service not configured.');
+    }
+
+    const stats = this.services.batchService.getStats() as Map<string, any>;
+
+    let total = 0;
+    let completed = 0;
+    let failed = 0;
+
+    for (const [, stat] of stats) {
+      total += stat.totalItems;
+      completed += stat.successCount;
+      failed += stat.errorCount;
+    }
+
+    const percentage = total > 0 ? (completed / total) * 100 : 0;
+
+    return {
+      total,
+      completed,
+      failed,
+      inProgress: total - completed - failed,
+      percentage
+    };
+  }
+
+  /**
+   * Get batch statistics
+   *
+   * Delegates to: BatchService.getStats()
+   *
+   * @param type - Optional batch type ('memory-create', 'storage', etc.)
+   * @returns Batch statistics
+   */
+  getStats(type?: string): BatchStatistics | Map<string, BatchStatistics> {
+    if (!this.services.batchService) {
+      throw new Error('Batch service not configured.');
+    }
+
+    const stats = this.services.batchService.getStats(type);
+
+    if (stats instanceof Map) {
+      return stats as Map<string, BatchStatistics>;
+    }
+
+    return stats as BatchStatistics;
+  }
+}

package/src/client/namespaces/CacheNamespace.ts

@@ -0,0 +1,123 @@
+/**
+ * Cache Namespace - LRU Cache Operations
+ *
+ * Pure delegation to BatchService cache methods.
+ * Provides fast in-memory caching with TTL support.
+ *
+ * @module client/namespaces
+ */
+
+import type { ServiceContainer } from '../SimplePDWClient';
+
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+  size: number;
+  totalAccess: number;
+  hitRate: number;
+  oldestItem?: Date;
+  newestItem?: Date;
+}
+
+/**
+ * Cache Namespace
+ *
+ * Handles in-memory caching operations with TTL and LRU eviction
+ */
+export class CacheNamespace {
+  constructor(private services: ServiceContainer) {}
+
+  /**
+   * Get cached value
+   *
+   * Delegates to: BatchService.getCache()
+   *
+   * @param key - Cache key
+   * @returns Cached value or null if not found/expired
+   */
+  get<T = any>(key: string): T | null {
+    if (!this.services.batchService) {
+      throw new Error('Batch service (cache) not configured.');
+    }
+
+    return this.services.batchService.getCache<T>(key);
+  }
+
+  /**
+   * Set cache value
+   *
+   * Delegates to: BatchService.setCache()
+   *
+   * @param key - Cache key
+   * @param value - Value to cache
+   * @param ttl - Time-to-live in milliseconds (optional)
+   */
+  set<T = any>(key: string, value: T, ttl?: number): void {
+    if (!this.services.batchService) {
+      throw new Error('Batch service (cache) not configured.');
+    }
+
+    this.services.batchService.setCache(key, value, ttl);
+  }
+
+  /**
+   * Check if key exists in cache
+   *
+   * Delegates to: BatchService.hasCache()
+   *
+   * @param key - Cache key
+   * @returns True if key exists and not expired
+   */
+  has(key: string): boolean {
+    if (!this.services.batchService) {
+      throw new Error('Batch service (cache) not configured.');
+    }
+
+    return this.services.batchService.hasCache(key);
+  }
+
+  /**
+   * Delete cache entry
+   *
+   * Delegates to: BatchService.deleteCache()
+   *
+   * @param key - Cache key
+   * @returns True if deleted, false if not found
+   */
+  delete(key: string): boolean {
+    if (!this.services.batchService) {
+      throw new Error('Batch service (cache) not configured.');
+    }
+
+    return this.services.batchService.deleteCache(key);
+  }
+
+  /**
+   * Clear all cache entries
+   *
+   * Delegates to: BatchService.clearCache()
+   */
+  clear(): void {
+    if (!this.services.batchService) {
+      throw new Error('Batch service (cache) not configured.');
+    }
+
+    this.services.batchService.clearCache();
+  }
+
+  /**
+   * Get cache statistics
+   *
+   * Delegates to: BatchService.getCacheStats()
+   *
+   * @returns Cache statistics
+   */
+  stats(): CacheStats {
+    if (!this.services.batchService) {
+      throw new Error('Batch service (cache) not configured.');
+    }
+
+    return this.services.batchService.getCacheStats();
+  }
+}

package/src/client/namespaces/CapabilityNamespace.ts

@@ -0,0 +1,217 @@
+/**
+ * Capability Namespace - MemoryCap Object Operations
+ *
+ * Provides API for managing MemoryCap capability objects using
+ * the SEAL PrivateData pattern.
+ *
+ * Key concepts:
+ * - MemoryCap: Capability object for app context access
+ * - Object ownership = access permission (SEAL idiomatic)
+ * - Transfer capability = share access
+ * - Burn capability = revoke access
+ *
+ * @module client/namespaces
+ */
+
+import type { ServiceContainer } from '../SimplePDWClient';
+import type { MemoryCap } from '../../core/types/capability';
+import { CapabilityService } from '../../services/CapabilityService';
+
+/**
+ * Options for creating a capability
+ */
+export interface CreateCapabilityOptions {
+  appId: string;
+}
+
+/**
+ * Options for listing capabilities
+ */
+export interface ListCapabilityOptions {
+  appId?: string;
+}
+
+/**
+ * Capability Namespace
+ *
+ * Handles MemoryCap CRUD operations
+ */
+export class CapabilityNamespace {
+  private capService: CapabilityService | null = null;
+
+  constructor(private services: ServiceContainer) {
+    // Initialize CapabilityService if SuiClient and packageId available
+    const suiClient = this.services.config.sui?.client;
+    const packageId = this.services.config.sui?.packageId;
+
+    if (suiClient && packageId) {
+      this.capService = new CapabilityService({
+        suiClient,
+        packageId,
+      });
+    }
+  }
+
+  /**
+   * Ensure CapabilityService is initialized
+   */
+  private ensureService(): CapabilityService {
+    if (!this.capService) {
+      throw new Error('CapabilityService not initialized. Check Sui configuration.');
+    }
+    return this.capService;
+  }
+
+  /**
+   * Create a new MemoryCap for an app context
+   *
+   * @param appId - Application identifier (e.g., "MEMO", "HEALTH")
+   * @returns Created MemoryCap
+   *
+   * @example
+   * ```typescript
+   * const cap = await pdw.capability.create('MEMO');
+   * console.log(cap.id, cap.appId, cap.nonce);
+   * ```
+   */
+  async create(appId: string): Promise<MemoryCap> {
+    const service = this.ensureService();
+    const signer = this.services.config.signer.getSigner();
+
+    return await service.create({ appId }, signer);
+  }
+
+  /**
+   * Get an existing capability by app ID
+   *
+   * @param appId - Application identifier
+   * @returns MemoryCap or null if not found
+   */
+  async get(appId: string): Promise<MemoryCap | null> {
+    const service = this.ensureService();
+    return await service.get(this.services.config.userAddress, appId);
+  }
+
+  /**
+   * Get or create a capability for an app context
+   *
+   * Convenience method that returns existing capability if found,
+   * otherwise creates a new one.
+   *
+   * @param appId - Application identifier
+   * @returns Existing or newly created MemoryCap
+   */
+  async getOrCreate(appId: string): Promise<MemoryCap> {
+    const service = this.ensureService();
+    const signer = this.services.config.signer.getSigner();
+
+    return await service.getOrCreate(
+      { appId, userAddress: this.services.config.userAddress },
+      signer
+    );
+  }
+
+  /**
+   * List all capabilities owned by the current user
+   *
+   * @param options - Optional filter by appId
+   * @returns Array of MemoryCaps
+   *
+   * @example
+   * ```typescript
+   * // List all capabilities
+   * const allCaps = await pdw.capability.list();
+   *
+   * // Filter by app ID
+   * const memoCaps = await pdw.capability.list({ appId: 'MEMO' });
+   * ```
+   */
+  async list(options?: ListCapabilityOptions): Promise<MemoryCap[]> {
+    const service = this.ensureService();
+
+    return await service.list({
+      userAddress: this.services.config.userAddress,
+      appId: options?.appId,
+    });
+  }
+
+  /**
+   * Transfer a capability to another address
+   *
+   * After transfer:
+   * - New owner can decrypt memories for this context
+   * - Original owner loses access
+   *
+   * @param capId - Capability object ID to transfer
+   * @param recipient - Recipient's Sui address
+   *
+   * @example
+   * ```typescript
+   * await pdw.capability.transfer(cap.id, '0x1234...');
+   * ```
+   */
+  async transfer(capId: string, recipient: string): Promise<void> {
+    const service = this.ensureService();
+    const signer = this.services.config.signer.getSigner();
+
+    await service.transfer({ capId, recipient }, signer);
+  }
+
+  /**
+   * Burn (revoke) a capability
+   *
+   * This permanently revokes the capability.
+   * After burning:
+   * - No one can decrypt memories for this context
+   * - Object is permanently deleted
+   *
+   * @param capId - Capability object ID to burn
+   *
+   * @example
+   * ```typescript
+   * await pdw.capability.burn(cap.id);
+   * ```
+   */
+  async burn(capId: string): Promise<void> {
+    const service = this.ensureService();
+    const signer = this.services.config.signer.getSigner();
+
+    await service.burn({ capId }, signer);
+  }
+
+  /**
+   * Check if user has capability for an app context
+   *
+   * @param appId - Application identifier
+   * @returns True if capability exists
+   */
+  async has(appId: string): Promise<boolean> {
+    const service = this.ensureService();
+    return await service.hasCapability(this.services.config.userAddress, appId);
+  }
+
+  /**
+   * Get capability by object ID
+   *
+   * @param capId - Capability object ID
+   * @returns MemoryCap or null
+   */
+  async getById(capId: string): Promise<MemoryCap | null> {
+    const service = this.ensureService();
+    return await service.getById(capId);
+  }
+
+  /**
+   * Compute SEAL key ID for a capability
+   *
+   * Used for SEAL encryption/decryption key derivation.
+   * key_id = keccak256(owner || nonce)
+   *
+   * @param cap - MemoryCap object
+   * @returns Key ID as hex string
+   */
+  computeKeyId(cap: MemoryCap): string {
+    const service = this.ensureService();
+    return service.computeKeyId(cap);
+  }
+}