@opendatalabs/vana-sdk 0.1.0-alpha.05db05d

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, Vana
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 

package/README.md

@@ -0,0 +1,417 @@
+# Vana SDK
+
+> **⚠️ ALPHA SOFTWARE - EXPERIMENTAL USE ONLY**
+>
+> This SDK is in early alpha development and is **NOT SUITABLE FOR PRODUCTION USE**.
+> Features may change without notice, and data loss or unexpected behavior may occur.
+> Use at your own risk and avoid using with mainnet assets or critical operations.
+
+A TypeScript SDK for building data-driven applications on the Vana Network. Enable users to grant gasless permissions, manage encrypted data, and interact with privacy-preserving infrastructure.
+
+[![npm version](https://img.shields.io/npm/v/@opendatalabs/vana-sdk)](https://www.npmjs.com/package/@opendatalabs/vana-sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
+[![License: ISC](https://img.shields.io/badge/License-ISC-green.svg)](https://opensource.org/licenses/ISC)
+
+[API Documentation](https://vana-com.github.io/vana-sdk) • [Examples](#examples) • [Configuration](#configuration)
+
+## Installation
+
+```bash
+npm install @opendatalabs/vana-sdk
+```
+
+**Peer Dependencies:**
+
+```bash
+npm install viem@^2.31.7
+```
+
+## Quick Start
+
+The Vana SDK supports both browser and Node.js environments with explicit entry points:
+
+### Browser Applications (React, Vue, etc.)
+
+```typescript
+// For browser-based applications (React, Vue, etc.)
+import { Vana, mokshaTestnet } from "@opendatalabs/vana-sdk/browser";
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+
+// Create wallet client
+const account = privateKeyToAccount("0x...");
+const walletClient = createWalletClient({
+  account,
+  chain: mokshaTestnet,
+  transport: http("https://rpc.moksha.vana.org"),
+});
+
+// Initialize SDK
+const vana = Vana({
+  walletClient,
+  relayerUrl: "https://relayer.moksha.vana.org",
+});
+```
+
+### Server-side Applications (Next.js API routes, Express)
+
+```typescript
+// For server-side applications (Next.js API routes, Express)
+import { Vana, mokshaTestnet } from "@opendatalabs/vana-sdk/node";
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+
+// Create wallet client
+const account = privateKeyToAccount("0x...");
+const walletClient = createWalletClient({
+  account,
+  chain: mokshaTestnet,
+  transport: http("https://rpc.moksha.vana.org"),
+});
+
+// Initialize SDK
+const vana = Vana({
+  walletClient,
+  relayerUrl: "https://relayer.moksha.vana.org",
+});
+
+// Grant gasless permission
+const txHash = await vana.permissions.grant({
+  grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+  operation: "llm_inference",
+  parameters: {
+    prompt: "Analyze my data for insights",
+    maxTokens: 1000,
+  },
+  expiresAt: Math.floor(Date.now() / 1000) + 86400, // 24 hours
+});
+```
+
+## Core Features
+
+### Gasless Permissions
+
+Users can grant data access permissions without paying gas fees through EIP-712 signatures and relay infrastructure.
+
+```typescript
+// Grant permission with custom parameters
+await vana.permissions.grant({
+  grantee: applicationAddress,
+  operation: "data_analysis",
+  parameters: {
+    analysisType: "sentiment",
+    files: [12, 15, 28],
+    model: "gpt-4",
+  },
+});
+```
+
+### Encrypted Data Management
+
+Upload, query, and manage encrypted user data files with built-in schema validation.
+
+```typescript
+// Query user files
+const files = await vana.data.getUserFiles({
+  owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+});
+
+// Upload encrypted file with decryption permissions
+const result = await vana.data.upload({
+  content: "Sensitive user data",
+  filename: "user-data.json",
+  schemaId: 123,
+  permissions: [
+    {
+      account: "0xServerAddress...", // Who can decrypt
+      publicKey: "0x04ServerKey...", // Their public key
+    },
+  ],
+});
+```
+
+### Flexible Storage
+
+Abstract storage layer supporting IPFS, Google Drive, and custom providers.
+
+```typescript
+// For browser applications
+import { StorageManager, PinataStorage } from "@opendatalabs/vana-sdk/browser";
+// OR for server-side applications
+// import { StorageManager, PinataStorage } from "@opendatalabs/vana-sdk/node";
+
+const storageManager = new StorageManager();
+storageManager.register(
+  "ipfs",
+  new PinataStorage({
+    apiKey: process.env.PINATA_API_KEY,
+    secretKey: process.env.PINATA_SECRET_KEY,
+  }),
+);
+```
+
+## Architecture
+
+The SDK provides four main controllers:
+
+| Controller    | Purpose                        | Key Methods                                                       |
+| ------------- | ------------------------------ | ----------------------------------------------------------------- |
+| `permissions` | Gasless permission management  | `grant()`, `revoke()`, `getUserPermissions()`                     |
+| `data`        | File management and validation | `getUserFiles()`, `uploadEncryptedFile()`, `validateDataSchema()` |
+| `server`      | Trusted server operations      | `trustServer()`, `processWithTrustedServer()`                     |
+| `protocol`    | Contract interaction           | `getContract()`, `getAvailableContracts()`                        |
+
+## Configuration
+
+```typescript
+const vana = Vana({
+  walletClient,
+
+  // Gasless transaction relay
+  relayerUrl: "https://relayer.moksha.vana.org",
+
+  // Custom relay callbacks
+  relayerCallbacks: {
+    submitPermissionGrant: async (typedData, signature) => {
+      return await customRelayer.submit(typedData, signature);
+    },
+  },
+
+  // Storage configuration
+  storageManager: new StorageManager({
+    defaultProvider: "ipfs",
+    providers: {
+      ipfs: new PinataStorage({ apiKey: "...", secretKey: "..." }),
+    },
+  }),
+
+  // Subgraph for efficient queries
+  subgraphUrl: "https://api.thegraph.com/subgraphs/name/vana/moksha",
+});
+```
+
+## Error Handling
+
+The SDK provides specific error types for different failure scenarios:
+
+```typescript
+import {
+  RelayerError,
+  UserRejectedRequestError,
+  SchemaValidationError,
+  NetworkError,
+} from "@opendatalabs/vana-sdk/browser";
+// OR for server-side applications
+// } from "@opendatalabs/vana-sdk/node";
+
+try {
+  await vana.permissions.grant(params);
+} catch (error) {
+  if (error instanceof UserRejectedRequestError) {
+    // User cancelled transaction
+  } else if (error instanceof RelayerError) {
+    // Relayer service error
+  } else if (error instanceof SchemaValidationError) {
+    // Schema validation failed
+  }
+}
+```
+
+## Supported Networks
+
+| Network            | Chain ID | RPC URL                       |
+| ------------------ | -------- | ----------------------------- |
+| **Vana Mainnet**   | `1480`   | `https://rpc.vana.org`        |
+| **Moksha Testnet** | `14800`  | `https://rpc.moksha.vana.org` |
+
+## Examples
+
+### Complete Data Sharing Flow
+
+```typescript
+import { Vana } from "@opendatalabs/vana-sdk/browser";
+// OR for server-side applications
+// } from "@opendatalabs/vana-sdk/node";
+
+async function shareDataWithServer() {
+  const vana = Vana({ walletClient });
+
+  // Step 1: Upload encrypted file with decryption permissions
+  const uploadResult = await vana.data.upload({
+    content: { data: "sensitive medical records" },
+    filename: "health-data.json",
+    schemaId: 123,
+    permissions: [
+      {
+        // Grant decryption access to the AI server
+        account: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+        publicKey: "0x04abc...", // Server's public key for encryption
+      },
+    ],
+  });
+
+  // Step 2: Grant operation permissions for what the server can do
+  const permissionResult = await vana.permissions.grant({
+    grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+    fileIds: [BigInt(uploadResult.fileId)],
+    operation: "medical_analysis",
+    parameters: {
+      model: "medical-ai-v2",
+      analysisType: "comprehensive",
+    },
+  });
+
+  return { uploadResult, permissionResult };
+}
+```
+
+### Schema Validation
+
+```typescript
+// Define data schema
+const schema = {
+  name: "Social Media Export",
+  version: "1.0.0",
+  dialect: "json",
+  schema: {
+    type: "object",
+    properties: {
+      posts: { type: "array" },
+      profile: { type: "object" },
+    },
+    required: ["profile"],
+  },
+};
+
+// Validate schema
+vana.data.validateDataSchema(schema);
+
+// Validate user data
+const userData = {
+  profile: { username: "alice" },
+  posts: [],
+};
+vana.data.validateDataAgainstSchema(userData, schema);
+```
+
+## API Reference
+
+### Permissions
+
+```typescript
+// Grant operation permission
+await vana.permissions.grant({
+  grantee: Address,
+  fileIds: bigint[],
+  operation: string,
+  parameters: object,
+  expiresAt?: number
+}): Promise<PermissionGrantResult>
+
+// Revoke permission
+await vana.permissions.revoke({
+  grantId: string
+}): Promise<Hash>
+
+// Get user permissions
+await vana.permissions.getUserPermissions({
+  owner: Address
+}): Promise<GrantedPermission[]>
+```
+
+### Data
+
+```typescript
+// Get user files
+await vana.data.getUserFiles({
+  owner: Address
+}): Promise<UserFile[]>
+
+// Upload data with automatic encryption
+await vana.data.upload({
+  content: string | Blob | Buffer,
+  filename?: string,
+  schemaId?: number,
+  permissions?: Array<{
+    account: Address,     // Who can decrypt
+    publicKey: string     // Their public key
+  }>,
+  encrypt?: boolean       // Default: true
+}): Promise<UploadResult>
+
+// Validate schema
+vana.data.validateDataSchema(schema: unknown): void
+
+// Validate data against schema
+vana.data.validateDataAgainstSchema(data: unknown, schema: DataSchema): void
+```
+
+## Documentation
+
+- [API Documentation](https://vana-com.github.io/vana-sdk) - Complete TypeDoc API reference
+- [Getting Started](https://vana-com.github.io/vana-sdk/getting-started) - Step-by-step setup guide
+- [Architecture](https://vana-com.github.io/vana-sdk/architecture) - SDK design and patterns
+- [Configuration](https://vana-com.github.io/vana-sdk/configuration) - All configuration options
+- [Security](https://vana-com.github.io/vana-sdk/security) - Best practices and security
+
+## Support
+
+- **Documentation**: [vana-com.github.io/vana-sdk](https://vana-com.github.io/vana-sdk)
+- **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
+git clone https://github.com/vana-com/vana-sdk.git
+cd vana-sdk
+npm install
+npm run build
+npm test
+```
+
+## License
+
+[ISC License](LICENSE) © Vana Foundation

package/dist/browser-DY8XDblx.d.ts

@@ -0,0 +1,241 @@
+/**
+ * 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
+ *
+ * This implementation uses browser-compatible libraries and configurations
+ * to provide crypto, PGP, and HTTP functionality without Node.js dependencies.
+ *
+ * WARNING: Dependencies that access globals during init
+ * MUST be dynamically imported to support Turbopack.
+ * See: https://github.com/vercel/next.js/issues/82632
+ */
+
+/**
+ * Complete browser platform adapter implementation
+ */
+declare class BrowserPlatformAdapter implements VanaPlatformAdapter {
+    crypto: VanaCryptoAdapter;
+    pgp: VanaPGPAdapter;
+    http: VanaHttpAdapter;
+    cache: VanaCacheAdapter;
+    platform: "browser";
+    constructor();
+}
+
+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-DY8XDblx.js';