@opendatalabs/vana-sdk 0.1.0-alpha.fd33fc9 → 2.0.0

package/dist/platform/interface.d.ts

@@ -1,126 +1,246 @@
 /**
- * Platform Adapter interface for environment-specific implementations
+ * Defines platform abstraction interfaces for environment-specific implementations.
  *
- * This interface abstracts all environment-specific dependencies to ensure
- * the SDK works seamlessly across Node.js and browser/SSR environments.
+ * @remarks
+ * This module provides the contract for platform-specific operations, allowing
+ * the SDK to work seamlessly across Node.js and browser environments. Platform
+ * adapters handle all environment-specific dependencies including cryptography,
+ * HTTP requests, caching, and PGP operations.
+ *
+ * The SDK automatically selects the appropriate adapter based on the runtime
+ * environment. Custom implementations can be provided for specialized use cases.
  *
  * **Implementation Context:**
- * - Node.js: Uses native crypto modules and full OpenPGP support
- * - Browser: Uses Web Crypto API and browser-compatible libraries
- * - SSR: Automatically selects appropriate implementation based on runtime
+ * - Node.js: Uses native crypto modules, in-memory cache, and full OpenPGP support
+ * - Browser: Uses Web Crypto API, sessionStorage cache, and browser-compatible libraries
+ * - SSR: Automatically selects appropriate implementation based on runtime detection
  *
- * **Usage Notes:**
- * Platform adapters are automatically selected by the SDK. Direct usage is only
- * needed for custom implementations or testing.
+ * @example
+ * ```typescript
+ * // Custom platform adapter implementation
+ * class CustomPlatformAdapter implements VanaPlatformAdapter {
+ *   crypto = new CustomCryptoAdapter();
+ *   pgp = new CustomPGPAdapter();
+ *   http = new CustomHttpAdapter();
+ *   cache = new CustomCacheAdapter();
+ *   platform = 'browser' as const;
+ * }
+ *
+ * // Use with SDK
+ * const client = createClient({
+ *   platformAdapter: new CustomPlatformAdapter()
+ * });
+ * ```
+ *
+ * @category Platform
+ * @module platform/interface
  */
 /**
- * Platform type identifier
+ * Identifies the runtime platform for adapter selection.
+ *
+ * @remarks
+ * Used for debugging, telemetry, and conditional logic based on
+ * the execution environment.
+ *
+ * @category Platform
  */
 export type PlatformType = "node" | "browser";
 /**
- * Encryption operations that require different implementations per platform
+ * Provides platform-specific cryptographic operations.
+ *
+ * @remarks
+ * Implements ECIES encryption/decryption, key generation, and password-based
+ * encryption using platform-appropriate libraries. Node.js uses Buffer-based
+ * libraries while browser uses Uint8Array and Web Crypto where possible.
+ *
+ * @category Platform
  */
 export interface VanaCryptoAdapter {
     /**
-     * Encrypt data with a public key using asymmetric cryptography
+     * Encrypts data with a public key using ECIES.
+     *
+     * @remarks
+     * Uses Elliptic Curve Integrated Encryption Scheme (ECIES) for
+     * asymmetric encryption. The implementation varies by platform but
+     * maintains compatible output format.
      *
-     * **Usage Context:**
-     * - Used internally for file encryption before storage
-     * - Public key format: Armored PGP public key string
-     * - Returns base64-encoded encrypted data
+     * @param data - The plaintext data to encrypt.
+     *   Typically user data or encryption keys.
+     * @param publicKey - The recipient's public key in hex format.
+     *   Can be compressed or uncompressed secp256k1 key.
+     * @returns Hex-encoded encrypted data containing IV, ephemeral key, ciphertext, and MAC
      *
-     * @param data The data to encrypt
-     * @param publicKey The public key for encryption
-     * @returns Promise resolving to encrypted data
+     * @example
+     * ```typescript
+     * const encrypted = await adapter.crypto.encryptWithPublicKey(
+     *   'sensitive data',
+     *   '04abcd...' // 65-byte uncompressed public key
+     * );
+     * ```
      */
     encryptWithPublicKey(data: string, publicKey: string): Promise<string>;
     /**
-     * Decrypt data with a private key using asymmetric cryptography
+     * Decrypts ECIES-encrypted data with a private key.
      *
-     * @param encryptedData The encrypted data
-     * @param privateKey The private key for decryption
-     * @returns Promise resolving to decrypted data
+     * @param encryptedData - Hex-encoded encrypted data.
+     *   Must contain IV, ephemeral key, ciphertext, and MAC.
+     * @param privateKey - The private key in hex format.
+     *   Must correspond to the public key used for encryption.
+     * @returns The decrypted plaintext string
+     *
+     * @throws {Error} If decryption or MAC verification fails
      */
     decryptWithPrivateKey(encryptedData: string, privateKey: string): Promise<string>;
     /**
-     * Generate a new key pair for asymmetric cryptography
+     * Generates a new secp256k1 key pair.
+     *
+     * @returns Object with hex-encoded keys
+     * @returns returns.publicKey - Compressed public key in hex
+     * @returns returns.privateKey - Private key in hex
      *
-     * @returns Promise resolving to public and private key pair
+     * @example
+     * ```typescript
+     * const { publicKey, privateKey } = await adapter.crypto.generateKeyPair();
+     * console.log('Public key:', publicKey); // 33 bytes compressed
+     * ```
      */
     generateKeyPair(): Promise<{
         publicKey: string;
         privateKey: string;
     }>;
     /**
-     * Encrypt data with a wallet's public key using ECDH cryptography
-     * Uses platform-appropriate ECDH implementation (eccrypto vs eccrypto-js)
+     * Encrypts data with an Ethereum wallet's public key.
+     *
+     * @remarks
+     * Specifically designed for wallet-based encryption where the public
+     * key comes from an Ethereum wallet. Handles key format conversion
+     * and uses ECIES for encryption.
      *
-     * **Usage Context:**
-     * - Used for sharing encryption keys with permission recipients
-     * - Public key format: Compressed or uncompressed secp256k1 hex string
-     * - Compatible with Ethereum wallet public keys
+     * @param data - The plaintext data to encrypt.
+     *   Typically permission grants or metadata.
+     * @param publicKey - The wallet's public key.
+     *   Accepts compressed/uncompressed, with/without 0x prefix.
+     * @returns Hex-encoded encrypted data
      *
-     * @param data The data to encrypt (string)
-     * @param publicKey The wallet's public key (secp256k1)
-     * @returns Promise resolving to encrypted data as hex string
+     * @example
+     * ```typescript
+     * const encrypted = await adapter.crypto.encryptWithWalletPublicKey(
+     *   JSON.stringify({ permission: 'read' }),
+     *   walletPublicKey
+     * );
+     * ```
      */
     encryptWithWalletPublicKey(data: string, publicKey: string): Promise<string>;
     /**
-     * Decrypt data with a wallet's private key using ECDH cryptography
-     * Uses platform-appropriate ECDH implementation (eccrypto vs eccrypto-js)
+     * Decrypts data with an Ethereum wallet's private key.
      *
-     * @param encryptedData The encrypted data as hex string
-     * @param privateKey The wallet's private key (secp256k1)
-     * @returns Promise resolving to decrypted data as string
+     * @param encryptedData - Hex-encoded encrypted data.
+     *   Must be encrypted with corresponding wallet public key.
+     * @param privateKey - The wallet's private key.
+     *   Handle with extreme care - never log or store.
+     * @returns The decrypted plaintext string
+     *
+     * @throws {Error} If decryption fails or key is invalid
      */
     decryptWithWalletPrivateKey(encryptedData: string, privateKey: string): Promise<string>;
     /**
-     * Encrypt data with a password using PGP password-based encryption
-     * Uses platform-appropriate OpenPGP implementation with consistent format
+     * Encrypts binary data with password-based encryption.
+     *
+     * @remarks
+     * Uses OpenPGP password-based encryption with automatic salt
+     * generation. Often used with wallet signatures as passwords for
+     * deterministic key derivation.
+     *
+     * @param data - Binary data to encrypt.
+     *   Typically file contents or serialized data.
+     * @param password - Password for encryption.
+     *   Often derived from wallet signatures.
+     * @returns Encrypted data as Uint8Array
      *
-     * @param data The data to encrypt as Uint8Array
-     * @param password The password for encryption (typically wallet signature)
-     * @returns Promise resolving to encrypted data as Uint8Array
+     * @example
+     * ```typescript
+     * const fileData = new Uint8Array([1, 2, 3, 4]);
+     * const encrypted = await adapter.crypto.encryptWithPassword(
+     *   fileData,
+     *   walletSignature
+     * );
+     * ```
      */
     encryptWithPassword(data: Uint8Array, password: string): Promise<Uint8Array>;
     /**
-     * Decrypt data with a password using PGP password-based decryption
-     * Uses platform-appropriate OpenPGP implementation with consistent format
+     * Decrypts password-encrypted binary data.
      *
-     * @param encryptedData The encrypted data as Uint8Array
-     * @param password The password for decryption (typically wallet signature)
-     * @returns Promise resolving to decrypted data as Uint8Array
+     * @param encryptedData - Password-encrypted data.
+     *   Must be encrypted with the same password.
+     * @param password - Password for decryption.
+     *   Must match the encryption password exactly.
+     * @returns Decrypted data as Uint8Array
+     *
+     * @throws {Error} If decryption fails or password is incorrect
      */
     decryptWithPassword(encryptedData: Uint8Array, password: string): Promise<Uint8Array>;
 }
 /**
- * PGP operations that require different configurations per platform
+ * Provides platform-specific PGP operations.
+ *
+ * @remarks
+ * Implements PGP encryption, decryption, and key generation using
+ * OpenPGP.js with platform-appropriate configuration. Node.js uses
+ * optimizations like zlib compression.
+ *
+ * @category Platform
  */
 export interface VanaPGPAdapter {
     /**
-     * Encrypt data using PGP with proper platform configuration
+     * Encrypts data using PGP public key encryption.
      *
-     * @param data The data to encrypt
-     * @param publicKey The PGP public key
-     * @returns Promise resolving to encrypted data
+     * @param data - The plaintext data to encrypt.
+     *   Typically messages or structured data.
+     * @param publicKey - ASCII-armored PGP public key.
+     *   Obtain from generateKeyPair or key servers.
+     * @returns ASCII-armored encrypted message
+     *
+     * @example
+     * ```typescript
+     * const encrypted = await adapter.pgp.encrypt(
+     *   'secret message',
+     *   armoredPublicKey
+     * );
+     * ```
      */
     encrypt(data: string, publicKey: string): Promise<string>;
     /**
-     * Decrypt data using PGP with proper platform configuration
+     * Decrypts PGP-encrypted data.
+     *
+     * @param encryptedData - ASCII-armored encrypted message.
+     *   Must be encrypted with corresponding public key.
+     * @param privateKey - ASCII-armored PGP private key.
+     *   May be passphrase-protected.
+     * @returns The decrypted plaintext string
      *
-     * @param encryptedData The encrypted data
-     * @param privateKey The PGP private key
-     * @returns Promise resolving to decrypted data
+     * @throws {Error} If decryption fails or key is invalid
      */
     decrypt(encryptedData: string, privateKey: string): Promise<string>;
     /**
-     * Generate a new PGP key pair with platform-appropriate configuration
+     * Generates a new PGP key pair.
+     *
+     * @param options - Key generation configuration
+     * @param options.name - Identity name.
+     *   Defaults to 'Vana User'.
+     * @param options.email - Identity email.
+     *   Defaults to 'user@vana.com'.
+     * @param options.passphrase - Private key passphrase.
+     *   If omitted, private key is unprotected.
+     * @returns ASCII-armored public and private keys
      *
-     * @param options - Key generation options
-     * @param options.name - The name for the PGP key
-     * @param options.email - The email for the PGP key
-     * @param options.passphrase - Optional passphrase to protect the private key
-     * @returns Promise resolving to public and private key pair
+     * @example
+     * ```typescript
+     * const { publicKey, privateKey } = await adapter.pgp.generateKeyPair({
+     *   name: 'Alice Smith',
+     *   email: 'alice@example.com',
+     *   passphrase: 'secure-passphrase'
+     * });
+     * ```
      */
     generateKeyPair(options?: {
         name?: string;
@@ -132,49 +252,97 @@ export interface VanaPGPAdapter {
     }>;
 }
 /**
- * HTTP operations that need consistent API across platforms
+ * Provides platform-specific HTTP operations.
+ *
+ * @remarks
+ * Wraps the fetch API to ensure consistent behavior across
+ * Node.js and browser environments.
+ *
+ * @category Platform
  */
 export interface VanaHttpAdapter {
     /**
-     * Perform HTTP request with platform-appropriate fetch implementation
+     * Performs an HTTP request.
+     *
+     * @param url - The URL to request.
+     *   Must be a valid HTTP/HTTPS URL.
+     * @param options - Standard fetch RequestInit options.
+     *   See MDN documentation for details.
+     * @returns Standard fetch Response object
      *
-     * @param url The URL to request
-     * @param options Request options
-     * @returns Promise resolving to response
+     * @example
+     * ```typescript
+     * const response = await adapter.http.fetch(
+     *   'https://api.vana.com/data',
+     *   { method: 'GET', headers: { 'Authorization': 'Bearer token' } }
+     * );
+     * ```
      */
     fetch(url: string, options?: RequestInit): Promise<Response>;
 }
 /**
- * Simple cache operations that work across platforms
+ * Provides platform-specific caching operations.
+ *
+ * @remarks
+ * Implements simple key-value caching with platform-appropriate storage.
+ * Node.js uses in-memory Map with TTL, browser uses sessionStorage for
+ * security (cleared on tab close).
+ *
+ * @category Platform
  */
 export interface VanaCacheAdapter {
     /**
-     * Get a value from the cache
+     * Retrieves a cached value.
      *
-     * @param key The cache key
+     * @param key - The cache key.
+     *   Should be unique per operation.
      * @returns The cached value or null if not found/expired
+     *
+     * @example
+     * ```typescript
+     * const cachedSignature = adapter.cache.get('sig_0x123...');
+     * if (cachedSignature) {
+     *   return cachedSignature;
+     * }
+     * ```
      */
     get(key: string): string | null;
     /**
-     * Set a value in the cache
+     * Stores a value in the cache.
      *
-     * @param key The cache key
-     * @param value The value to cache
+     * @param key - The cache key.
+     *   Should be unique and descriptive.
+     * @param value - The value to cache.
+     *   Typically signatures or computed results.
+     *
+     * @remarks
+     * Node.js: Cached for 2 hours with TTL
+     * Browser: Cached until tab closes (sessionStorage)
      */
     set(key: string, value: string): void;
     /**
-     * Delete a value from the cache
+     * Removes a cached value.
      *
-     * @param key The cache key
+     * @param key - The cache key to remove.
+     *   Use when cached data becomes invalid.
      */
     delete(key: string): void;
     /**
-     * Clear all values from the cache
+     * Clears all cached values.
+     *
+     * @remarks
+     * Use with caution as this removes all performance optimizations.
+     * Browser implementation only clears Vana-prefixed keys.
      */
     clear(): void;
 }
 /**
- * Main platform adapter interface that combines all platform-specific functionality
+ * Aggregates all platform-specific adapters into a single interface.
+ *
+ * @remarks
+ * This is the main interface for platform abstraction. Implementations
+ * must provide all required adapters while maintaining consistent behavior
+ * and data formats across platforms.
  *
  * **Implementation Guidelines:**
  * 1. All methods must maintain consistent behavior across platforms
@@ -182,35 +350,60 @@ export interface VanaCacheAdapter {
  * 3. Data formats (encoding, serialization) must be identical
  * 4. Performance characteristics can vary but API must be consistent
  *
- * **Custom Implementation Example:**
+ * @example
  * ```typescript
- * class CustomPlatformAdapter implements VanaPlatformAdapter {
- *   crypto = new CustomCryptoAdapter();
- *   pgp = new CustomPGPAdapter();
- *   http = new CustomHttpAdapter();
- *   platform = 'browser' as const;
+ * // Custom implementation for specialized environment
+ * class EdgePlatformAdapter implements VanaPlatformAdapter {
+ *   crypto = new EdgeCryptoAdapter();
+ *   pgp = new EdgePGPAdapter();
+ *   http = new EdgeHttpAdapter();
+ *   cache = new EdgeCacheAdapter();
+ *   platform = 'browser' as const; // Edge is browser-like
  * }
+ *
+ * // Use with SDK
+ * const client = createClient({
+ *   platformAdapter: new EdgePlatformAdapter()
+ * });
  * ```
+ *
+ * @category Platform
  */
 export interface VanaPlatformAdapter {
     /**
-     * Crypto operations adapter
+     * Provides cryptographic operations.
+     *
+     * @remarks
+     * Handles ECIES, wallet encryption, and password-based encryption.
      */
     crypto: VanaCryptoAdapter;
     /**
-     * PGP operations adapter
+     * Provides PGP operations.
+     *
+     * @remarks
+     * Handles PGP encryption, decryption, and key generation.
      */
     pgp: VanaPGPAdapter;
     /**
-     * HTTP operations adapter
+     * Provides HTTP operations.
+     *
+     * @remarks
+     * Wraps fetch API for consistent cross-platform behavior.
      */
     http: VanaHttpAdapter;
     /**
-     * Cache operations adapter
+     * Provides caching operations.
+     *
+     * @remarks
+     * Platform-appropriate storage for temporary data.
      */
     cache: VanaCacheAdapter;
     /**
-     * Platform identifier for debugging/telemetry
+     * Identifies the platform type.
+     *
+     * @remarks
+     * Used for debugging, telemetry, and conditional logic.
+     * Must be 'node' or 'browser'.
      */
     readonly platform: PlatformType;
 }