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

package/dist/platform/interface.cjs.map

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

package/dist/platform/interface.d.ts

@@ -0,0 +1,409 @@
+/**
+ * Defines platform abstraction interfaces for environment-specific implementations.
+ *
+ * @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, 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
+ *
+ * @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
+ */
+/**
+ * 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";
+/**
+ * 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 {
+    /**
+     * 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.
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const encrypted = await adapter.crypto.encryptWithPublicKey(
+     *   'sensitive data',
+     *   '04abcd...' // 65-byte uncompressed public key
+     * );
+     * ```
+     */
+    encryptWithPublicKey(data: string, publicKey: string): Promise<string>;
+    /**
+     * Decrypts ECIES-encrypted data with a private key.
+     *
+     * @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>;
+    /**
+     * 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
+     *
+     * @example
+     * ```typescript
+     * const { publicKey, privateKey } = await adapter.crypto.generateKeyPair();
+     * console.log('Public key:', publicKey); // 33 bytes compressed
+     * ```
+     */
+    generateKeyPair(): Promise<{
+        publicKey: string;
+        privateKey: string;
+    }>;
+    /**
+     * 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.
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * const encrypted = await adapter.crypto.encryptWithWalletPublicKey(
+     *   JSON.stringify({ permission: 'read' }),
+     *   walletPublicKey
+     * );
+     * ```
+     */
+    encryptWithWalletPublicKey(data: string, publicKey: string): Promise<string>;
+    /**
+     * Decrypts data with an Ethereum wallet's private key.
+     *
+     * @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>;
+    /**
+     * 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
+     *
+     * @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>;
+    /**
+     * Decrypts password-encrypted binary data.
+     *
+     * @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>;
+}
+/**
+ * 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 {
+    /**
+     * Encrypts data using PGP public key encryption.
+     *
+     * @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>;
+    /**
+     * 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
+     *
+     * @throws {Error} If decryption fails or key is invalid
+     */
+    decrypt(encryptedData: string, privateKey: string): Promise<string>;
+    /**
+     * 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
+     *
+     * @example
+     * ```typescript
+     * const { publicKey, privateKey } = await adapter.pgp.generateKeyPair({
+     *   name: 'Alice Smith',
+     *   email: 'alice@example.com',
+     *   passphrase: 'secure-passphrase'
+     * });
+     * ```
+     */
+    generateKeyPair(options?: {
+        name?: string;
+        email?: string;
+        passphrase?: string;
+    }): Promise<{
+        publicKey: string;
+        privateKey: string;
+    }>;
+}
+/**
+ * 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 {
+    /**
+     * 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
+     *
+     * @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>;
+}
+/**
+ * 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 {
+    /**
+     * Retrieves a cached value.
+     *
+     * @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;
+    /**
+     * Stores a value in the 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;
+    /**
+     * Removes a cached value.
+     *
+     * @param key - The cache key to remove.
+     *   Use when cached data becomes invalid.
+     */
+    delete(key: string): void;
+    /**
+     * Clears all cached values.
+     *
+     * @remarks
+     * Use with caution as this removes all performance optimizations.
+     * Browser implementation only clears Vana-prefixed keys.
+     */
+    clear(): void;
+}
+/**
+ * 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
+ * 2. Error types and messages should be unified
+ * 3. Data formats (encoding, serialization) must be identical
+ * 4. Performance characteristics can vary but API must be consistent
+ *
+ * @example
+ * ```typescript
+ * // 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 {
+    /**
+     * Provides cryptographic operations.
+     *
+     * @remarks
+     * Handles ECIES, wallet encryption, and password-based encryption.
+     */
+    crypto: VanaCryptoAdapter;
+    /**
+     * Provides PGP operations.
+     *
+     * @remarks
+     * Handles PGP encryption, decryption, and key generation.
+     */
+    pgp: VanaPGPAdapter;
+    /**
+     * Provides HTTP operations.
+     *
+     * @remarks
+     * Wraps fetch API for consistent cross-platform behavior.
+     */
+    http: VanaHttpAdapter;
+    /**
+     * Provides caching operations.
+     *
+     * @remarks
+     * Platform-appropriate storage for temporary data.
+     */
+    cache: VanaCacheAdapter;
+    /**
+     * Identifies the platform type.
+     *
+     * @remarks
+     * Used for debugging, telemetry, and conditional logic.
+     * Must be 'node' or 'browser'.
+     */
+    readonly platform: PlatformType;
+}

package/dist/platform/interface.js

@@ -0,0 +1 @@
+//# sourceMappingURL=interface.js.map

package/dist/platform/interface.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}