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

package/README.md

@@ -1,417 +1,142 @@
 # 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.
+Build user-owned data applications with gasless permissions, encrypted data management, and 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)
+[![Downloads](https://img.shields.io/npm/dm/@opendatalabs/vana-sdk)](https://www.npmjs.com/package/@opendatalabs/vana-sdk)
+[![License](https://img.shields.io/npm/l/@opendatalabs/vana-sdk)](https://opensource.org/licenses/ISC)
 
-## Installation
+The SDK is production-ready. APIs may evolve in minor versions as we incorporate feedback and expand functionality.
 
-```bash
-npm install @opendatalabs/vana-sdk
-```
+## Get Started
 
-**Peer Dependencies:**
+### 1. Install
 
 ```bash
-npm install viem@^2.31.7
+npm install @opendatalabs/vana-sdk viem
 ```
 
-## Quick Start
+### 2. Set up your client
 
-The Vana SDK supports both browser and Node.js environments with explicit entry points:
+Choose the build for your environment:
 
-### Browser Applications (React, Vue, etc.)
+**Browser:**
 
 ```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";
+import { createWalletClient, custom } from "viem";
 
-// Create wallet client
-const account = privateKeyToAccount("0x...");
 const walletClient = createWalletClient({
-  account,
   chain: mokshaTestnet,
-  transport: http("https://rpc.moksha.vana.org"),
+  transport: custom(window.ethereum),
 });
 
-// Initialize SDK
-const vana = Vana({
-  walletClient,
-  relayerUrl: "https://relayer.moksha.vana.org",
-});
+const vana = Vana({ walletClient });
 ```
 
-### Server-side Applications (Next.js API routes, Express)
+**Node.js:**
 
 ```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,
+  walletClient: createWalletClient({
+    account,
+    chain: mokshaTestnet,
+    transport: http("https://rpc.moksha.vana.org"),
+  }),
   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.
+### 3. Use the SDK
 
 ```typescript
-// Grant permission with custom parameters
+// Grant gasless data access permission
 await vana.permissions.grant({
-  grantee: applicationAddress,
-  operation: "data_analysis",
+  grantee: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+  operation: "llm_inference",
   parameters: {
-    analysisType: "sentiment",
-    files: [12, 15, 28],
-    model: "gpt-4",
+    prompt: "Analyze my data for insights",
+    maxTokens: 1000,
   },
-});
-```
-
-### 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",
+  expiresAt: Math.floor(Date.now() / 1000) + 86400,
 });
 
 // Upload encrypted file with decryption permissions
-const result = await vana.data.upload({
+await vana.data.upload({
   content: "Sensitive user data",
-  filename: "user-data.json",
+  filename: "data.json",
   schemaId: 123,
   permissions: [
     {
-      account: "0xServerAddress...", // Who can decrypt
-      publicKey: "0x04ServerKey...", // Their public key
+      account: "0xServerAddress...",
+      publicKey: "0x04ServerKey...",
     },
   ],
 });
-```
 
-### 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,
-  }),
-);
+// Query user files
+const files = await vana.data.getUserFiles({
+  owner: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36",
+});
 ```
 
-## Architecture
+## Features
 
-The SDK provides four main controllers:
+The SDK provides six 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()`                        |
+| Controller    | Purpose                                      |
+| ------------- | -------------------------------------------- |
+| `permissions` | Grant and revoke gasless data access         |
+| `data`        | Upload, query, and decrypt encrypted files   |
+| `schemas`     | Validate data against schemas                |
+| `server`      | Interact with trusted servers                |
+| `protocol`    | Direct smart contract access                 |
+| `operations`  | Track and poll transaction status            |
 
 ## Configuration
 
+Configure storage, relay, and subgraph services:
+
 ```typescript
+import { StorageManager, PinataStorage } from "@opendatalabs/vana-sdk/node";
+
 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
+  storageManager: new StorageManager().register(
+    "ipfs",
+    new PinataStorage({
+      apiKey: process.env.PINATA_API_KEY,
+      secretKey: process.env.PINATA_SECRET_KEY,
+    })
+  ),
   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
+## Networks
 
-```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
-```
+| Network        | Chain ID | RPC URL                     |
+| -------------- | -------- | --------------------------- |
+| Vana Mainnet   | 1480     | https://rpc.vana.org        |
+| Moksha Testnet | 14800    | https://rpc.moksha.vana.org |
 
-## Documentation
+## Learn More
 
-- [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
+- [Documentation](https://docs.vana.org/docs/sdk) - Comprehensive guides and tutorials
+- [API Reference](https://vana-com.github.io/vana-sdk) - Complete TypeScript documentation
+- [Examples](https://github.com/vana-com/vana-sdk/tree/main/examples) - Full demo applications
+- [Discord](https://discord.gg/vanabuilders) - Community support
 
 ## 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
-```
+Report issues on [GitHub Issues](https://github.com/vana-com/vana-sdk/issues).
 
 ## License
 
-[ISC License](LICENSE) © Vana Foundation
+[ISC](https://opensource.org/licenses/ISC)

package/dist/__tests__/waitForTransactionEvents.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/browser.cjs

@@ -0,0 +1,29 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var browser_exports = {};
+__export(browser_exports, {
+  BrowserPlatformAdapter: () => import_browser.BrowserPlatformAdapter
+});
+module.exports = __toCommonJS(browser_exports);
+var import_browser = require("./platform/browser");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BrowserPlatformAdapter
+});
+//# sourceMappingURL=browser.cjs.map

package/dist/browser.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/browser.ts"],"sourcesContent":["/**\n * Browser-specific entry point for the Vana SDK.\n *\n * @remarks\n * This module provides the browser implementation of the Vana SDK,\n * optimized for web applications and browser environments. It includes\n * platform-specific implementations using Web APIs for cryptography,\n * storage, and networking operations.\n *\n * Import this module when building web applications:\n * ```typescript\n * import { BrowserPlatformAdapter } from '@opendatalabs/vana-sdk/browser';\n * ```\n *\n * Features:\n * - Web Crypto API for encryption operations\n * - SessionStorage for caching\n * - Fetch API for HTTP requests\n * - Optimized bundle size for browser deployment\n *\n * @example\n * ```typescript\n * // In a React/Vue/Angular application\n * import { BrowserPlatformAdapter } from '@opendatalabs/vana-sdk/browser';\n * import { Vana } from '@opendatalabs/vana-sdk-experimental';\n *\n * const vana = new Vana({\n *   platform: new BrowserPlatformAdapter(),\n *   network: 'moksha'\n * });\n * ```\n *\n * @category Browser\n * @module browser\n */\nexport { BrowserPlatformAdapter } from \"./platform/browser\";\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAmCA,qBAAuC;","names":[]}

package/dist/browser.d.ts

@@ -1 +1,36 @@
-export { B as BrowserPlatformAdapter } from './browser-DY8XDblx.js';
+/**
+ * Browser-specific entry point for the Vana SDK.
+ *
+ * @remarks
+ * This module provides the browser implementation of the Vana SDK,
+ * optimized for web applications and browser environments. It includes
+ * platform-specific implementations using Web APIs for cryptography,
+ * storage, and networking operations.
+ *
+ * Import this module when building web applications:
+ * ```typescript
+ * import { BrowserPlatformAdapter } from '@opendatalabs/vana-sdk/browser';
+ * ```
+ *
+ * Features:
+ * - Web Crypto API for encryption operations
+ * - SessionStorage for caching
+ * - Fetch API for HTTP requests
+ * - Optimized bundle size for browser deployment
+ *
+ * @example
+ * ```typescript
+ * // In a React/Vue/Angular application
+ * import { BrowserPlatformAdapter } from '@opendatalabs/vana-sdk/browser';
+ * import { Vana } from '@opendatalabs/vana-sdk-experimental';
+ *
+ * const vana = new Vana({
+ *   platform: new BrowserPlatformAdapter(),
+ *   network: 'moksha'
+ * });
+ * ```
+ *
+ * @category Browser
+ * @module browser
+ */
+export { BrowserPlatformAdapter } from "./platform/browser";