@opendatalabs/vana-sdk 0.1.0-alpha.8f514ac → 0.1.0-alpha.98d1ef9

package/README.md

@@ -28,12 +28,19 @@ npm install viem@^2.31.7
 
 ## Quick Start
 
-The Vana SDK supports both browser and Node.js environments with explicit entry points:
+The Vana SDK provides optimized builds for different environments:
 
-### Browser Applications (React, Vue, etc.)
+| Build          | Use Case                          | Crypto Implementation              | Configuration     |
+| -------------- | --------------------------------- | ---------------------------------- | ----------------- |
+| **`/browser`** | Browser apps (React, Vue)         | Pure JavaScript (@noble/secp256k1) | **Zero config** ✓ |
+| **`/node`**    | Server-side (Node.js, API routes) | Native bindings (secp256k1)        | Zero config ✓     |
+
+### Browser Applications
+
+The browser build uses pure JavaScript cryptography and requires **no special configuration**:
 
 ```typescript
-// For browser-based applications (React, Vue, etc.)
+// Browser build - works out of the box with any bundler
 import { Vana, mokshaTestnet } from "@opendatalabs/vana-sdk/browser";
 import { createWalletClient, http } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
@@ -53,7 +60,9 @@ const vana = Vana({
 });
 ```
 
-### Server-side Applications (Next.js API routes, Express)
+### Server-side Applications (Node.js)
+
+The Node.js build uses native secp256k1 bindings for optimal performance:
 
 ```typescript
 // For server-side applications (Next.js API routes, Express)
@@ -360,6 +369,48 @@ vana.data.validateDataAgainstSchema(data: unknown, schema: DataSchema): void
 - **Issues**: [GitHub Issues](https://github.com/vana-com/vana-sdk/issues)
 - **Discord**: [Join our community](https://discord.gg/vanabuilders)
 
+## Generated Code
+
+The SDK includes automatically generated code from various sources to provide type-safe interfaces. All generated files are located in `src/generated/` and should **never be edited manually**.
+
+### Code Generation Scripts
+
+| Script                       | Purpose                                | Generated Files             |
+| ---------------------------- | -------------------------------------- | --------------------------- |
+| `npm run fetch-abis`         | Smart contract ABIs from blockchain    | `src/generated/abi/*.ts`    |
+| `npm run fetch-server-types` | Personal server API types from OpenAPI | `src/generated/server/*.ts` |
+| `npm run codegen:subgraph`   | GraphQL types from subgraph schema     | `src/generated/subgraph.ts` |
+
+### Network-Specific Generation
+
+Some generation scripts support different networks:
+
+```bash
+# Generate subgraph types for different networks
+npm run codegen:subgraph:moksha   # Moksha testnet (default)
+npm run codegen:subgraph:mainnet  # Vana mainnet
+
+# Generate ABIs for different networks
+npm run fetch-abis moksha         # Moksha testnet (default)
+npm run fetch-abis mainnet        # Vana mainnet
+```
+
+### Development Workflow
+
+When working with the SDK:
+
+1. **Never edit generated files** - They are overwritten on regeneration
+2. **Regenerate after schema changes** - Run generation scripts when external schemas change
+3. **Generated files are committed** - They're included in version control for consistency
+4. **ESLint ignores generated code** - Style rules don't apply to generated files
+
+```bash
+# Regenerate all code after schema updates
+npm run fetch-abis
+npm run fetch-server-types
+npm run codegen:subgraph
+```
+
 ## Development
 
 ```bash

package/dist/browser-Bb8gLWHp.d.ts

@@ -0,0 +1,288 @@
+/**
+ * Platform Adapter interface for environment-specific implementations
+ *
+ * This interface abstracts all environment-specific dependencies to ensure
+ * the SDK works seamlessly across Node.js and browser/SSR environments.
+ *
+ * **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
+ *
+ * **Usage Notes:**
+ * Platform adapters are automatically selected by the SDK. Direct usage is only
+ * needed for custom implementations or testing.
+ */
+/**
+ * Platform type identifier
+ */
+type PlatformType = "node" | "browser";
+/**
+ * Encryption operations that require different implementations per platform
+ */
+interface VanaCryptoAdapter {
+    /**
+     * Encrypt data with a public key using asymmetric cryptography
+     *
+     * **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 data to encrypt
+     * @param publicKey The public key for encryption
+     * @returns Promise resolving to encrypted data
+     */
+    encryptWithPublicKey(data: string, publicKey: string): Promise<string>;
+    /**
+     * Decrypt data with a private key using asymmetric cryptography
+     *
+     * @param encryptedData The encrypted data
+     * @param privateKey The private key for decryption
+     * @returns Promise resolving to decrypted data
+     */
+    decryptWithPrivateKey(encryptedData: string, privateKey: string): Promise<string>;
+    /**
+     * Generate a new key pair for asymmetric cryptography
+     *
+     * @returns Promise resolving to public and private key pair
+     */
+    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)
+     *
+     * **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 data to encrypt (string)
+     * @param publicKey The wallet's public key (secp256k1)
+     * @returns Promise resolving to encrypted data as hex string
+     */
+    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)
+     *
+     * @param encryptedData The encrypted data as hex string
+     * @param privateKey The wallet's private key (secp256k1)
+     * @returns Promise resolving to decrypted data as string
+     */
+    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
+     *
+     * @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
+     */
+    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
+     *
+     * @param encryptedData The encrypted data as Uint8Array
+     * @param password The password for decryption (typically wallet signature)
+     * @returns Promise resolving to decrypted data as Uint8Array
+     */
+    decryptWithPassword(encryptedData: Uint8Array, password: string): Promise<Uint8Array>;
+}
+/**
+ * PGP operations that require different configurations per platform
+ */
+interface VanaPGPAdapter {
+    /**
+     * Encrypt data using PGP with proper platform configuration
+     *
+     * @param data The data to encrypt
+     * @param publicKey The PGP public key
+     * @returns Promise resolving to encrypted data
+     */
+    encrypt(data: string, publicKey: string): Promise<string>;
+    /**
+     * Decrypt data using PGP with proper platform configuration
+     *
+     * @param encryptedData The encrypted data
+     * @param privateKey The PGP private key
+     * @returns Promise resolving to decrypted data
+     */
+    decrypt(encryptedData: string, privateKey: string): Promise<string>;
+    /**
+     * Generate a new PGP key pair with platform-appropriate configuration
+     *
+     * @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
+     */
+    generateKeyPair(options?: {
+        name?: string;
+        email?: string;
+        passphrase?: string;
+    }): Promise<{
+        publicKey: string;
+        privateKey: string;
+    }>;
+}
+/**
+ * HTTP operations that need consistent API across platforms
+ */
+interface VanaHttpAdapter {
+    /**
+     * Perform HTTP request with platform-appropriate fetch implementation
+     *
+     * @param url The URL to request
+     * @param options Request options
+     * @returns Promise resolving to response
+     */
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+/**
+ * Simple cache operations that work across platforms
+ */
+interface VanaCacheAdapter {
+    /**
+     * Get a value from the cache
+     *
+     * @param key The cache key
+     * @returns The cached value or null if not found/expired
+     */
+    get(key: string): string | null;
+    /**
+     * Set a value in the cache
+     *
+     * @param key The cache key
+     * @param value The value to cache
+     */
+    set(key: string, value: string): void;
+    /**
+     * Delete a value from the cache
+     *
+     * @param key The cache key
+     */
+    delete(key: string): void;
+    /**
+     * Clear all values from the cache
+     */
+    clear(): void;
+}
+/**
+ * Main platform adapter interface that combines all platform-specific functionality
+ *
+ * **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
+ *
+ * **Custom Implementation Example:**
+ * ```typescript
+ * class CustomPlatformAdapter implements VanaPlatformAdapter {
+ *   crypto = new CustomCryptoAdapter();
+ *   pgp = new CustomPGPAdapter();
+ *   http = new CustomHttpAdapter();
+ *   platform = 'browser' as const;
+ * }
+ * ```
+ */
+interface VanaPlatformAdapter {
+    /**
+     * Crypto operations adapter
+     */
+    crypto: VanaCryptoAdapter;
+    /**
+     * PGP operations adapter
+     */
+    pgp: VanaPGPAdapter;
+    /**
+     * HTTP operations adapter
+     */
+    http: VanaHttpAdapter;
+    /**
+     * Cache operations adapter
+     */
+    cache: VanaCacheAdapter;
+    /**
+     * Platform identifier for debugging/telemetry
+     */
+    readonly platform: PlatformType;
+}
+
+/**
+ * Browser implementation of the Vana Platform Adapter using Uint8Array
+ *
+ * This implementation uses browser-compatible libraries and native APIs
+ * without requiring Buffer or other Node.js polyfills.
+ */
+
+/**
+ * Browser implementation of crypto operations using Uint8Array
+ */
+declare class BrowserCryptoAdapter implements VanaCryptoAdapter {
+    private eciesProvider;
+    private walletKeyEncryptionService;
+    encryptWithPublicKey(data: string, publicKeyHex: string): Promise<string>;
+    decryptWithPrivateKey(encryptedData: string, privateKeyHex: string): Promise<string>;
+    encryptWithWalletPublicKey(data: string, publicKey: string): Promise<string>;
+    decryptWithWalletPrivateKey(encryptedData: string, privateKey: string): Promise<string>;
+    generateKeyPair(): Promise<{
+        privateKey: string;
+        publicKey: string;
+    }>;
+    encryptWithPassword(data: Uint8Array, password: string): Promise<Uint8Array>;
+    decryptWithPassword(encryptedData: Uint8Array, password: string): Promise<Uint8Array>;
+}
+/**
+ * Browser implementation of PGP operations
+ */
+declare class BrowserPGPAdapter implements VanaPGPAdapter {
+    encrypt(data: string, publicKeyArmored: string): Promise<string>;
+    decrypt(encryptedData: string, privateKeyArmored: string): Promise<string>;
+    generateKeyPair(options?: {
+        name?: string;
+        email?: string;
+        passphrase?: string;
+    }): Promise<{
+        publicKey: string;
+        privateKey: string;
+    }>;
+}
+/**
+ * Browser implementation of HTTP operations using Fetch API
+ */
+declare class BrowserHttpAdapter implements VanaHttpAdapter {
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+/**
+ * Browser implementation of caching using sessionStorage for security
+ * SessionStorage is cleared when the tab closes, making it more secure for signature caching
+ */
+declare class BrowserCacheAdapter implements VanaCacheAdapter {
+    private readonly prefix;
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    delete(key: string): void;
+    clear(): void;
+}
+/**
+ * Browser implementation of the Vana Platform Adapter
+ *
+ * This adapter provides all platform-specific functionality for browser environments
+ * without requiring any Node.js polyfills.
+ */
+declare class BrowserPlatformAdapter implements VanaPlatformAdapter {
+    readonly crypto: BrowserCryptoAdapter;
+    readonly pgp: BrowserPGPAdapter;
+    readonly http: BrowserHttpAdapter;
+    readonly cache: BrowserCacheAdapter;
+    readonly platform: "browser";
+}
+
+export { BrowserPlatformAdapter as B, type PlatformType as P, type VanaPlatformAdapter as V };

package/dist/browser.d.ts

@@ -0,0 +1 @@
+export { B as BrowserPlatformAdapter } from './browser-Bb8gLWHp.js';