@cmdoss/memwal-sdk 0.6.2 → 0.8.0

package/src/client/namespaces/EmbeddingsNamespace.ts

@@ -1,99 +1,99 @@
-/**
- * Embeddings Namespace - Direct Embedding Operations
- *
- * Pure delegation to EmbeddingService for direct embedding access.
- * Useful for custom RAG pipelines and advanced AI integrations.
- *
- * @module client/namespaces
- */
-
-import type { ServiceContainer } from '../SimplePDWClient';
-
-/**
- * Embeddings Namespace
- *
- * Handles direct embedding generation and operations
- */
-export class EmbeddingsNamespace {
-  constructor(private services: ServiceContainer) {}
-
-  /**
-   * Generate embedding for single text
-   *
-   * Delegates to: EmbeddingService.embedText()
-   *
-   * @param text - Text to embed
-   * @param options - Embedding options
-   * @returns Embedding vector (768 dimensions for Gemini)
-   */
-  async generate(text: string, options?: { type?: 'query' | 'document' }): Promise<number[]> {
-    if (!this.services.embedding) {
-      throw new Error('Embedding service not configured. Please provide geminiApiKey.');
-    }
-
-    const result = await this.services.embedding.embedText({ text });
-    return result.vector;
-  }
-
-  /**
-   * Generate embeddings for multiple texts
-   *
-   * Delegates to: EmbeddingService.embedBatch()
-   *
-   * @param texts - Array of texts
-   * @returns Array of embedding vectors
-   */
-  async batch(texts: string[]): Promise<number[][]> {
-    if (!this.services.embedding) {
-      throw new Error('Embedding service not configured.');
-    }
-
-    const result = await this.services.embedding.embedBatch(texts);
-    return result.vectors;
-  }
-
-  /**
-   * Calculate cosine similarity between two vectors
-   *
-   * Delegates to: EmbeddingService.calculateCosineSimilarity()
-   *
-   * @param vector1 - First vector
-   * @param vector2 - Second vector
-   * @returns Similarity score (0-1, higher is more similar)
-   */
-  similarity(vector1: number[], vector2: number[]): number {
-    if (!this.services.embedding) {
-      throw new Error('Embedding service not configured.');
-    }
-
-    return this.services.embedding.calculateCosineSimilarity(vector1, vector2);
-  }
-
-  /**
-   * Find most similar vectors from candidates
-   *
-   * Delegates to: EmbeddingService.findMostSimilar()
-   *
-   * @param queryVector - Query vector
-   * @param candidateVectors - Candidate vectors to compare
-   * @param k - Number of results (default: 5)
-   * @returns Top k similar vectors with scores
-   */
-  findSimilar(
-    queryVector: number[],
-    candidateVectors: number[][],
-    k: number = 5
-  ): Array<{ index: number; score: number }> {
-    if (!this.services.embedding) {
-      throw new Error('Embedding service not configured.');
-    }
-
-    const results = this.services.embedding.findMostSimilar(queryVector, candidateVectors, k);
-
-    // Adapt result format (similarity → score)
-    return results.map(r => ({
-      index: r.index,
-      score: r.similarity
-    }));
-  }
-}
+/**
+ * Embeddings Namespace - Direct Embedding Operations
+ *
+ * Pure delegation to EmbeddingService for direct embedding access.
+ * Useful for custom RAG pipelines and advanced AI integrations.
+ *
+ * @module client/namespaces
+ */
+
+import type { ServiceContainer } from '../SimplePDWClient';
+
+/**
+ * Embeddings Namespace
+ *
+ * Handles direct embedding generation and operations
+ */
+export class EmbeddingsNamespace {
+  constructor(private services: ServiceContainer) {}
+
+  /**
+   * Generate embedding for single text
+   *
+   * Delegates to: EmbeddingService.embedText()
+   *
+   * @param text - Text to embed
+   * @param options - Embedding options
+   * @returns Embedding vector (3072 dimensions for Gemini)
+   */
+  async generate(text: string, options?: { type?: 'query' | 'document' }): Promise<number[]> {
+    if (!this.services.embedding) {
+      throw new Error('Embedding service not configured. Please provide geminiApiKey.');
+    }
+
+    const result = await this.services.embedding.embedText({ text });
+    return result.vector;
+  }
+
+  /**
+   * Generate embeddings for multiple texts
+   *
+   * Delegates to: EmbeddingService.embedBatch()
+   *
+   * @param texts - Array of texts
+   * @returns Array of embedding vectors
+   */
+  async batch(texts: string[]): Promise<number[][]> {
+    if (!this.services.embedding) {
+      throw new Error('Embedding service not configured.');
+    }
+
+    const result = await this.services.embedding.embedBatch(texts);
+    return result.vectors;
+  }
+
+  /**
+   * Calculate cosine similarity between two vectors
+   *
+   * Delegates to: EmbeddingService.calculateCosineSimilarity()
+   *
+   * @param vector1 - First vector
+   * @param vector2 - Second vector
+   * @returns Similarity score (0-1, higher is more similar)
+   */
+  similarity(vector1: number[], vector2: number[]): number {
+    if (!this.services.embedding) {
+      throw new Error('Embedding service not configured.');
+    }
+
+    return this.services.embedding.calculateCosineSimilarity(vector1, vector2);
+  }
+
+  /**
+   * Find most similar vectors from candidates
+   *
+   * Delegates to: EmbeddingService.findMostSimilar()
+   *
+   * @param queryVector - Query vector
+   * @param candidateVectors - Candidate vectors to compare
+   * @param k - Number of results (default: 5)
+   * @returns Top k similar vectors with scores
+   */
+  findSimilar(
+    queryVector: number[],
+    candidateVectors: number[][],
+    k: number = 5
+  ): Array<{ index: number; score: number }> {
+    if (!this.services.embedding) {
+      throw new Error('Embedding service not configured.');
+    }
+
+    const results = this.services.embedding.findMostSimilar(queryVector, candidateVectors, k);
+
+    // Adapt result format (similarity → score)
+    return results.map(r => ({
+      index: r.index,
+      score: r.similarity
+    }));
+  }
+}

package/src/client/namespaces/EncryptionNamespace.ts

@@ -1,221 +1,221 @@
-/**
- * Encryption Namespace - SEAL-based Encryption Operations
- *
- * Pure delegation to EncryptionService for SEAL encryption.
- * Provides identity-based encryption with decentralized key management.
- *
- * @module client/namespaces
- */
-
-import type { ServiceContainer } from '../SimplePDWClient';
-import type { SessionKey } from '@mysten/seal';
-
-/**
- * Encryption result
- */
-export interface EncryptionResult {
-  encryptedData: Uint8Array;
-  backupKey: Uint8Array;
-}
-
-/**
- * Decryption options
- */
-export interface DecryptionOptions {
-  encryptedData: Uint8Array;
-  sessionKey?: SessionKey;
-  requestingWallet?: string;
-  /** MemoryCap object ID for capability-based access control */
-  memoryCapId?: string;
-  /** SEAL key ID bytes - required with memoryCapId */
-  keyId?: Uint8Array;
-}
-
-/**
- * Encryption Namespace
- *
- * Handles SEAL-based encryption with identity-based access control
- */
-export class EncryptionNamespace {
-  constructor(private services: ServiceContainer) {}
-
-  /**
-   * Encrypt data using SEAL
-   *
-   * Delegates to: EncryptionService.encrypt()
-   *
-   * NOTE: This uses userAddress as identity. For capability pattern,
-   * use encryptWithKeyId() instead.
-   *
-   * @param data - Data to encrypt
-   * @param threshold - Min key servers required (default: 2)
-   * @returns Encrypted data and backup key
-   */
-  async encrypt(data: Uint8Array, threshold: number = 2): Promise<EncryptionResult> {
-    if (!this.services.encryption) {
-      throw new Error('Encryption service not configured. Initialize with encryption config.');
-    }
-
-    const result = await this.services.encryption.encrypt(
-      data,
-      this.services.config.userAddress,
-      threshold
-    );
-
-    return {
-      encryptedData: result.encryptedObject,
-      backupKey: result.backupKey
-    };
-  }
-
-  /**
-   * Encrypt data using SEAL with capability-based key ID
-   *
-   * Use this for capability pattern where keyId = keccak256(owner || nonce)
-   * The keyId MUST match what's passed to seal_approve during decryption.
-   *
-   * @param data - Data to encrypt
-   * @param keyId - Key ID bytes (compute with computeKeyId())
-   * @param threshold - Min key servers required (default: 2)
-   * @returns Encrypted data and backup key
-   */
-  async encryptWithKeyId(data: Uint8Array, keyId: Uint8Array, threshold: number = 2): Promise<EncryptionResult> {
-    if (!this.services.encryption) {
-      throw new Error('Encryption service not configured. Initialize with encryption config.');
-    }
-
-    // Convert keyId to hex string for SEAL identity
-    const keyIdHex = '0x' + Array.from(keyId).map(b => b.toString(16).padStart(2, '0')).join('');
-    console.log(`🔒 Encrypting with capability keyId: ${keyIdHex.substring(0, 20)}...`);
-
-    const result = await this.services.encryption.encrypt(
-      data,
-      keyIdHex,
-      threshold
-    );
-
-    return {
-      encryptedData: result.encryptedObject,
-      backupKey: result.backupKey
-    };
-  }
-
-  /**
-   * Decrypt SEAL-encrypted data
-   *
-   * Delegates to: EncryptionService.decrypt()
-   *
-   * Supports two access control patterns:
-   * 1. Capability pattern (recommended): Pass memoryCapId and keyId
-   * 2. Legacy allowlist pattern: Only requestingWallet needed
-   *
-   * @param options - Decryption options
-   * @returns Decrypted data
-   */
-  async decrypt(options: DecryptionOptions): Promise<Uint8Array> {
-    if (!this.services.encryption) {
-      throw new Error('Encryption service not configured.');
-    }
-
-    return await this.services.encryption.decrypt({
-      encryptedContent: options.encryptedData,
-      userAddress: this.services.config.userAddress,
-      sessionKey: options.sessionKey,
-      requestingWallet: options.requestingWallet || this.services.config.userAddress,
-      memoryCapId: options.memoryCapId,
-      keyId: options.keyId
-    });
-  }
-
-  /**
-   * Compute SEAL key_id from owner and nonce
-   *
-   * Use this to compute the key_id needed for capability-based decryption.
-   * The nonce comes from the MemoryCap object on-chain.
-   *
-   * @param ownerAddress - Owner's Sui address
-   * @param nonce - Nonce from MemoryCap object (32 bytes)
-   * @returns key_id bytes for SEAL approval
-   */
-  computeKeyId(ownerAddress: string, nonce: Uint8Array): Uint8Array {
-    if (!this.services.encryption) {
-      throw new Error('Encryption service not configured.');
-    }
-
-    return this.services.encryption.computeKeyId(ownerAddress, nonce);
-  }
-
-  /**
-   * Create session key for SEAL operations
-   *
-   * Delegates to: EncryptionService.createSessionKey()
-   *
-   * @param signer - Optional signer (keypair or signPersonalMessage function)
-   * @returns Session key
-   */
-  async createSessionKey(signer?: {
-    signPersonalMessageFn?: (message: string) => Promise<{ signature: string }>;
-    keypair?: any;
-  }): Promise<SessionKey> {
-    if (!this.services.encryption) {
-      throw new Error('Encryption service not configured.');
-    }
-
-    return await this.services.encryption.createSessionKey(
-      this.services.config.userAddress,
-      signer
-    );
-  }
-
-  /**
-   * Get or create session key (cached)
-   *
-   * Delegates to: EncryptionService.getOrCreateSessionKey()
-   *
-   * @returns Cached or new session key
-   */
-  async getSessionKey(): Promise<SessionKey> {
-    if (!this.services.encryption) {
-      throw new Error('Encryption service not configured.');
-    }
-
-    return await this.services.encryption.getOrCreateSessionKey(
-      this.services.config.userAddress
-    );
-  }
-
-  /**
-   * Export session key for persistence
-   *
-   * Delegates to: EncryptionService.exportSessionKey()
-   *
-   * @param sessionKey - Session key to export
-   * @returns Serialized session key
-   */
-  async exportSessionKey(sessionKey: SessionKey): Promise<string> {
-    if (!this.services.encryption) {
-      throw new Error('Encryption service not configured.');
-    }
-
-    return await this.services.encryption.exportSessionKey(sessionKey);
-  }
-
-  /**
-   * Import previously exported session key
-   *
-   * Delegates to: EncryptionService.importSessionKey()
-   *
-   * @param exportedKey - Serialized session key
-   * @returns Session key instance
-   */
-  async importSessionKey(exportedKey: string): Promise<SessionKey> {
-    if (!this.services.encryption) {
-      throw new Error('Encryption service not configured.');
-    }
-
-    return await this.services.encryption.importSessionKey(
-      exportedKey,
-      this.services.config.userAddress
-    );
-  }
-}
+/**
+ * Encryption Namespace - SEAL-based Encryption Operations
+ *
+ * Pure delegation to EncryptionService for SEAL encryption.
+ * Provides identity-based encryption with decentralized key management.
+ *
+ * @module client/namespaces
+ */
+
+import type { ServiceContainer } from '../SimplePDWClient';
+import type { SessionKey } from '@mysten/seal';
+
+/**
+ * Encryption result
+ */
+export interface EncryptionResult {
+  encryptedData: Uint8Array;
+  backupKey: Uint8Array;
+}
+
+/**
+ * Decryption options
+ */
+export interface DecryptionOptions {
+  encryptedData: Uint8Array;
+  sessionKey?: SessionKey;
+  requestingWallet?: string;
+  /** MemoryCap object ID for capability-based access control */
+  memoryCapId?: string;
+  /** SEAL key ID bytes - required with memoryCapId */
+  keyId?: Uint8Array;
+}
+
+/**
+ * Encryption Namespace
+ *
+ * Handles SEAL-based encryption with identity-based access control
+ */
+export class EncryptionNamespace {
+  constructor(private services: ServiceContainer) {}
+
+  /**
+   * Encrypt data using SEAL
+   *
+   * Delegates to: EncryptionService.encrypt()
+   *
+   * NOTE: This uses userAddress as identity. For capability pattern,
+   * use encryptWithKeyId() instead.
+   *
+   * @param data - Data to encrypt
+   * @param threshold - Min key servers required (default: 2)
+   * @returns Encrypted data and backup key
+   */
+  async encrypt(data: Uint8Array, threshold: number = 2): Promise<EncryptionResult> {
+    if (!this.services.encryption) {
+      throw new Error('Encryption service not configured. Initialize with encryption config.');
+    }
+
+    const result = await this.services.encryption.encrypt(
+      data,
+      this.services.config.userAddress,
+      threshold
+    );
+
+    return {
+      encryptedData: result.encryptedObject,
+      backupKey: result.backupKey
+    };
+  }
+
+  /**
+   * Encrypt data using SEAL with capability-based key ID
+   *
+   * Use this for capability pattern where keyId = keccak256(owner || nonce)
+   * The keyId MUST match what's passed to seal_approve during decryption.
+   *
+   * @param data - Data to encrypt
+   * @param keyId - Key ID bytes (compute with computeKeyId())
+   * @param threshold - Min key servers required (default: 2)
+   * @returns Encrypted data and backup key
+   */
+  async encryptWithKeyId(data: Uint8Array, keyId: Uint8Array, threshold: number = 2): Promise<EncryptionResult> {
+    if (!this.services.encryption) {
+      throw new Error('Encryption service not configured. Initialize with encryption config.');
+    }
+
+    // Convert keyId to hex string for SEAL identity
+    const keyIdHex = '0x' + Array.from(keyId).map(b => b.toString(16).padStart(2, '0')).join('');
+    console.log(`🔒 Encrypting with capability keyId: ${keyIdHex.substring(0, 20)}...`);
+
+    const result = await this.services.encryption.encrypt(
+      data,
+      keyIdHex,
+      threshold
+    );
+
+    return {
+      encryptedData: result.encryptedObject,
+      backupKey: result.backupKey
+    };
+  }
+
+  /**
+   * Decrypt SEAL-encrypted data
+   *
+   * Delegates to: EncryptionService.decrypt()
+   *
+   * Supports two access control patterns:
+   * 1. Capability pattern (recommended): Pass memoryCapId and keyId
+   * 2. Legacy allowlist pattern: Only requestingWallet needed
+   *
+   * @param options - Decryption options
+   * @returns Decrypted data
+   */
+  async decrypt(options: DecryptionOptions): Promise<Uint8Array> {
+    if (!this.services.encryption) {
+      throw new Error('Encryption service not configured.');
+    }
+
+    return await this.services.encryption.decrypt({
+      encryptedContent: options.encryptedData,
+      userAddress: this.services.config.userAddress,
+      sessionKey: options.sessionKey,
+      requestingWallet: options.requestingWallet || this.services.config.userAddress,
+      memoryCapId: options.memoryCapId,
+      keyId: options.keyId
+    });
+  }
+
+  /**
+   * Compute SEAL key_id from owner and nonce
+   *
+   * Use this to compute the key_id needed for capability-based decryption.
+   * The nonce comes from the MemoryCap object on-chain.
+   *
+   * @param ownerAddress - Owner's Sui address
+   * @param nonce - Nonce from MemoryCap object (32 bytes)
+   * @returns key_id bytes for SEAL approval
+   */
+  computeKeyId(ownerAddress: string, nonce: Uint8Array): Uint8Array {
+    if (!this.services.encryption) {
+      throw new Error('Encryption service not configured.');
+    }
+
+    return this.services.encryption.computeKeyId(ownerAddress, nonce);
+  }
+
+  /**
+   * Create session key for SEAL operations
+   *
+   * Delegates to: EncryptionService.createSessionKey()
+   *
+   * @param signer - Optional signer (keypair or signPersonalMessage function)
+   * @returns Session key
+   */
+  async createSessionKey(signer?: {
+    signPersonalMessageFn?: (message: string) => Promise<{ signature: string }>;
+    keypair?: any;
+  }): Promise<SessionKey> {
+    if (!this.services.encryption) {
+      throw new Error('Encryption service not configured.');
+    }
+
+    return await this.services.encryption.createSessionKey(
+      this.services.config.userAddress,
+      signer
+    );
+  }
+
+  /**
+   * Get or create session key (cached)
+   *
+   * Delegates to: EncryptionService.getOrCreateSessionKey()
+   *
+   * @returns Cached or new session key
+   */
+  async getSessionKey(): Promise<SessionKey> {
+    if (!this.services.encryption) {
+      throw new Error('Encryption service not configured.');
+    }
+
+    return await this.services.encryption.getOrCreateSessionKey(
+      this.services.config.userAddress
+    );
+  }
+
+  /**
+   * Export session key for persistence
+   *
+   * Delegates to: EncryptionService.exportSessionKey()
+   *
+   * @param sessionKey - Session key to export
+   * @returns Serialized session key
+   */
+  async exportSessionKey(sessionKey: SessionKey): Promise<string> {
+    if (!this.services.encryption) {
+      throw new Error('Encryption service not configured.');
+    }
+
+    return await this.services.encryption.exportSessionKey(sessionKey);
+  }
+
+  /**
+   * Import previously exported session key
+   *
+   * Delegates to: EncryptionService.importSessionKey()
+   *
+   * @param exportedKey - Serialized session key
+   * @returns Session key instance
+   */
+  async importSessionKey(exportedKey: string): Promise<SessionKey> {
+    if (!this.services.encryption) {
+      throw new Error('Encryption service not configured.');
+    }
+
+    return await this.services.encryption.importSessionKey(
+      exportedKey,
+      this.services.config.userAddress
+    );
+  }
+}