@opendatalabs/vana-sdk 0.1.0-alpha.eebb656 → 0.1.0-alpha.ef15099

package/dist/types/config.d.ts

@@ -1,7 +1,8 @@
-import type { WalletClient, Account, Hash, Address } from "viem";
+import type { WalletClient, PublicClient, Account, Address, Chain } from "viem";
 import type { VanaChainId, VanaChain } from "./chains";
 import type { StorageProvider, StorageUploadResult, StorageListOptions } from "./storage";
-import type { PermissionGrantTypedData, TrustServerTypedData, UntrustServerTypedData, AddAndTrustServerTypedData, GenericTypedData, GrantFile, ServerFilesAndPermissionTypedData } from "./permissions";
+import type { RelayerConfig } from "./relayer";
+import type { IOperationStore, IRelayerStateStore } from "./operationStore";
 /**
  * Marker interface to indicate that a Vana instance has storage configured.
  * Used for compile-time type safety to ensure storage-dependent methods
@@ -13,10 +14,12 @@ export interface StorageRequiredMarker {
     readonly __storageRequired: true;
 }
 /**
- * Configuration for storage providers used by the SDK.
+ * Configures storage providers for SDK file operations.
  *
- * Allows you to configure multiple storage backends (IPFS, Pinata, Google Drive, etc.)
- * and specify which one to use by default for file operations.
+ * @remarks
+ * Supports multiple backends with automatic fallback.
+ * IPFS for decentralization, Pinata for reliability,
+ * Google Drive for development, custom for flexibility.
  *
  * **Provider Selection:**
  * - IPFS: Decentralized, permanent storage ideal for production
@@ -30,7 +33,7 @@ export interface StorageRequiredMarker {
  * const storage: StorageConfig = {
  *   providers: {
  *     ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' }),
- *     pinata: new PinataStorage({ apiKey: 'your-key', secretKey: 'your-secret' })
+ *     pinata: new PinataStorage({ apiKey: 'key', secretKey: 'secret' })
  *   },
  *   defaultProvider: 'ipfs'
  * };
@@ -128,183 +131,6 @@ export interface DownloadRelayerCallbacks {
      */
     proxyDownload: (url: string) => Promise<Blob>;
 }
-/**
- * Relayer callback functions for handling gasless transactions.
- *
- * Instead of hardcoding HTTP/REST API calls, users can provide custom callback
- * functions to handle transaction relay in any way they choose (HTTP, WebSocket,
- * direct blockchain submission, etc.).
- *
- * @category Configuration
- * @example
- * ```typescript
- * const relayerCallbacks: RelayerCallbacks = {
- *   async submitPermissionGrant(typedData, signature) {
- *     // Custom implementation - could be HTTP, WebSocket, etc.
- *     const response = await fetch('https://my-relayer.com/api/grant', {
- *       method: 'POST',
- *       headers: { 'Content-Type': 'application/json' },
- *       body: JSON.stringify({ typedData, signature })
- *     });
- *     const result = await response.json();
- *     return result.transactionHash;
- *   },
- *
- *   async submitFileAddition(url, userAddress) {
- *     // Custom relay implementation
- *     return await myCustomRelayer.addFile(url, userAddress);
- *   }
- * };
- * ```
- */
-export interface RelayerCallbacks {
-    /**
-     * Submit a signed permission grant transaction for relay
-     *
-     * @param typedData - The EIP-712 typed data that was signed
-     * @param signature - The user's signature
-     * @returns Promise resolving to the transaction hash
-     */
-    submitPermissionGrant?: (typedData: PermissionGrantTypedData, signature: Hash) => Promise<Hash>;
-    /**
-     * Submit a signed permission revocation transaction for relay
-     *
-     * @param typedData - The EIP-712 typed data that was signed
-     * @param signature - The user's signature
-     * @returns Promise resolving to the transaction hash
-     */
-    submitPermissionRevoke?: (typedData: GenericTypedData, signature: Hash) => Promise<Hash>;
-    /**
-     * Submit a signed trust server transaction for relay
-     *
-     * @param typedData - The EIP-712 typed data that was signed
-     * @param signature - The user's signature
-     * @returns Promise resolving to the transaction hash
-     */
-    submitTrustServer?: (typedData: TrustServerTypedData, signature: Hash) => Promise<Hash>;
-    /**
-     * Submit a signed untrust server transaction for relay
-     *
-     * @param typedData - The EIP-712 typed data that was signed
-     * @param signature - The user's signature
-     * @returns Promise resolving to the transaction hash
-     */
-    submitUntrustServer?: (typedData: UntrustServerTypedData, signature: Hash) => Promise<Hash>;
-    /**
-     * Submit a signed add and trust server transaction for relay
-     *
-     * @param typedData - The EIP-712 typed data that was signed
-     * @param signature - The user's signature
-     * @returns Promise resolving to the transaction hash
-     */
-    submitAddAndTrustServer?: (typedData: AddAndTrustServerTypedData, signature: Hash) => Promise<Hash>;
-    /**
-     * Submit a signed permission addition transaction for relay
-     *
-     * @param typedData - The EIP-712 typed data that was signed
-     * @param signature - The user's signature
-     * @returns Promise resolving to the transaction hash
-     */
-    submitAddPermission?: (typedData: GenericTypedData, signature: Hash) => Promise<Hash>;
-    /**
-     * Submit a signed server files and permissions transaction for relay
-     *
-     * @param typedData - The EIP-712 typed data that was signed
-     * @param signature - The user's signature
-     * @returns Promise resolving to the transaction hash
-     */
-    submitAddServerFilesAndPermissions?: (typedData: ServerFilesAndPermissionTypedData, signature: Hash) => Promise<Hash>;
-    /**
-     * Submit a file addition for relay
-     *
-     * @deprecated Since v2.0.0 - Use submitFileAdditionComplete() instead for full support.
-     * Will be removed in v3.0.0.
-     *
-     * Migration guide:
-     * ```typescript
-     * // Old:
-     * await submitFileAddition(url, userAddress);
-     *
-     * // New:
-     * await submitFileAdditionComplete({
-     *   url,
-     *   userAddress,
-     *   permissions: [] // Optional
-     * });
-     * ```
-     * @param url - The file URL to register
-     * @param userAddress - The user's address
-     * @returns Promise resolving to object with fileId and transactionHash
-     */
-    submitFileAddition?: (url: string, userAddress: string) => Promise<{
-        fileId: number;
-        transactionHash: Hash;
-    }>;
-    /**
-     * Submit a file addition with permissions for relay
-     *
-     * @deprecated Since v2.0.0 - Use submitFileAdditionComplete() instead for full support.
-     * Will be removed in v3.0.0.
-     *
-     * Migration guide:
-     * ```typescript
-     * // Old:
-     * await submitFileAdditionWithPermissions(url, userAddress, permissions);
-     *
-     * // New:
-     * await submitFileAdditionComplete({
-     *   url,
-     *   userAddress,
-     *   permissions
-     * });
-     * ```
-     * @param url - The file URL to register
-     * @param userAddress - The user's address
-     * @param permissions - Array of encrypted permissions
-     * @returns Promise resolving to object with fileId and transactionHash
-     */
-    submitFileAdditionWithPermissions?: (url: string, userAddress: string, permissions: Array<{
-        account: string;
-        key: string;
-    }>) => Promise<{
-        fileId: number;
-        transactionHash: Hash;
-    }>;
-    /**
-     * Submit a comprehensive file addition with optional schema and permissions for relay
-     *
-     * This is the preferred callback that supports all file addition scenarios.
-     * It can handle files with schemas, permissions, or both.
-     *
-     * @param params - Complete parameters for file addition
-     * @param params.url - The file URL to register
-     * @param params.userAddress - The user's address (defaults to connected wallet if not specified)
-     * @param params.permissions - Array of encrypted permissions (empty array if none)
-     * @param params.schemaId - Schema ID for validation (0 if none)
-     * @param params.ownerAddress - Optional owner address (defaults to userAddress if not specified)
-     * @returns Promise resolving to object with fileId and transactionHash
-     */
-    submitFileAdditionComplete?: (params: {
-        url: string;
-        userAddress: Address;
-        permissions: Array<{
-            account: Address;
-            key: string;
-        }>;
-        schemaId: number;
-        ownerAddress?: Address;
-    }) => Promise<{
-        fileId: number;
-        transactionHash: Hash;
-    }>;
-    /**
-     * Store a grant file for relay (e.g., upload to IPFS)
-     *
-     * @param grantData - The grant file data
-     * @returns Promise resolving to the storage URL
-     */
-    storeGrantFile?: (grantData: GrantFile) => Promise<string>;
-}
 /**
  * Storage callback functions for flexible storage operations.
  *
@@ -427,10 +253,25 @@ export interface StorageListResult {
  */
 export interface BaseConfig {
     /**
-     * Optional relayer callback functions for handling gasless transactions.
-     * Provides flexible relay mechanism - can use HTTP, WebSocket, or any custom implementation.
+     * Optional relayer configuration for handling gasless transactions.
+     * Can be a URL string for convenience, or a callback for full control.
+     *
+     * @example
+     * ```typescript
+     * // Simple URL (SDK handles transport)
+     * relayer: '/api/relay'
+     *
+     * // Full control with callback
+     * relayer: async (request) => {
+     *   const response = await fetch('/api/relay', {
+     *     method: 'POST',
+     *     body: JSON.stringify(request)
+     *   });
+     *   return response.json();
+     * }
+     * ```
      */
-    relayerCallbacks?: RelayerCallbacks;
+    relayer?: RelayerConfig;
     /**
      * Optional download relayer for proxying CORS-restricted downloads.
      * Provides a proxy mechanism for files stored on servers with CORS restrictions.
@@ -465,6 +306,21 @@ export interface BaseConfig {
      * @example 'https://my-personal-server.example.com'
      */
     defaultPersonalServerUrl?: string;
+    /**
+     * Optional operation store for tracking async relayed transactions.
+     * When provided with a relayer, enables resilient transaction management
+     * with polling support for pending operations.
+     *
+     * @example
+     * ```typescript
+     * const vana = createVana({
+     *   walletClient,
+     *   relayer: '/api/relay',
+     *   operationStore: myOperationStore
+     * });
+     * ```
+     */
+    operationStore?: IOperationStore | IRelayerStateStore;
 }
 /**
  * Base configuration interface that requires storage for storage-dependent operations
@@ -473,10 +329,25 @@ export interface BaseConfig {
  */
 export interface BaseConfigWithStorage {
     /**
-     * Optional relayer callback functions for handling gasless transactions.
-     * Provides flexible relay mechanism - can use HTTP, WebSocket, or any custom implementation.
+     * Optional relayer configuration for handling gasless transactions.
+     * Can be a URL string for convenience, or a callback for full control.
+     *
+     * @example
+     * ```typescript
+     * // Simple URL (SDK handles transport)
+     * relayer: '/api/relay'
+     *
+     * // Full control with callback
+     * relayer: async (request) => {
+     *   const response = await fetch('/api/relay', {
+     *     method: 'POST',
+     *     body: JSON.stringify(request)
+     *   });
+     *   return response.json();
+     * }
+     * ```
      */
-    relayerCallbacks?: RelayerCallbacks;
+    relayer?: RelayerConfig;
     /**
      * Optional download relayer for proxying CORS-restricted downloads.
      * Provides a proxy mechanism for files stored on servers with CORS restrictions.
@@ -505,6 +376,12 @@ export interface BaseConfigWithStorage {
      * @example 'https://my-personal-server.example.com'
      */
     defaultPersonalServerUrl?: string;
+    /**
+     * Optional operation store for tracking async relayed transactions.
+     * When provided with a relayer, enables resilient transaction management
+     * with polling support for pending operations.
+     */
+    operationStore?: IOperationStore | IRelayerStateStore;
 }
 /**
  * Configuration with wallet client
@@ -566,56 +443,125 @@ export interface ChainConfigWithStorage extends BaseConfigWithStorage {
     /** Optional account for signing transactions */
     account?: Account;
 }
+/**
+ * Configuration with wallet client and optional public client
+ *
+ * @category Configuration
+ */
+export interface VanaConfigWithWallet extends BaseConfig {
+    /** The viem WalletClient instance used for signing transactions */
+    walletClient: WalletClient;
+    /** Optional PublicClient for read operations (derived from wallet if not provided) */
+    publicClient?: PublicClient;
+}
+/**
+ * Configuration for read-only operations with public client and address
+ *
+ * @category Configuration
+ */
+export interface VanaConfigReadOnly extends BaseConfig {
+    /** The viem PublicClient instance for read operations */
+    publicClient: PublicClient;
+    /** The user's address for read operations */
+    address: Address;
+}
+/**
+ * Configuration for minimal read-only operations with just an address
+ *
+ * @category Configuration
+ */
+export interface VanaConfigAddressOnly extends BaseConfig {
+    /** The user's address for read operations */
+    address: Address;
+    /** Optional chain configuration (will use default if not provided) */
+    chain?: Chain;
+}
+/**
+ * Configuration with wallet client and optional public client that requires storage
+ *
+ * @category Configuration
+ */
+export interface VanaConfigWithWalletWithStorage extends BaseConfigWithStorage {
+    /** The viem WalletClient instance used for signing transactions */
+    walletClient: WalletClient;
+    /** Optional PublicClient for read operations (derived from wallet if not provided) */
+    publicClient?: PublicClient;
+}
+/**
+ * Configuration for read-only operations with public client and address that requires storage
+ *
+ * @category Configuration
+ */
+export interface VanaConfigReadOnlyWithStorage extends BaseConfigWithStorage {
+    /** The viem PublicClient instance for read operations */
+    publicClient: PublicClient;
+    /** The user's address for read operations */
+    address: Address;
+}
+/**
+ * Configuration for minimal read-only operations with just an address that requires storage
+ *
+ * @category Configuration
+ */
+export interface VanaConfigAddressOnlyWithStorage extends BaseConfigWithStorage {
+    /** The user's address for read operations */
+    address: Address;
+    /** Optional chain configuration (will use default if not provided) */
+    chain?: Chain;
+}
 /**
  * Main configuration interface for initializing the Vana SDK.
  *
- * You can configure the SDK using either a pre-configured wallet client
- * (WalletConfig) or by providing chain and account details (ChainConfig).
- * Both approaches support optional storage providers and relayer configuration.
+ * The SDK supports three initialization modes:
+ * 1. Full mode with wallet client for signing transactions
+ * 2. Read-only mode with public client and address for read operations
+ * 3. Minimal mode with just an address and optional chain
  *
  * @category Configuration
  * @example
  * ```typescript
- * // Using WalletConfig with pre-configured client
- * const config: VanaConfig = {
+ * // Mode 1: Full configuration with wallet client
+ * const configWithWallet: VanaConfig = {
  *   walletClient: createWalletClient({
  *     account: privateKeyToAccount('0x...'),
  *     chain: moksha,
  *     transport: http()
  *   }),
- *   relayerCallbacks: {
- *     submitPermissionGrant: async (typedData, signature) => {
- *       // Custom relay implementation
- *       return await myRelayer.submit(typedData, signature);
- *     }
- *   }
+ *   publicClient: createPublicClient({
+ *     chain: moksha,
+ *     transport: http()
+ *   })
  * };
  *
- * // Using ChainConfig with chain ID and account
- * const config: VanaConfig = {
- *   chainId: 14800,
- *   account: privateKeyToAccount('0x...'),
- *   relayerCallbacks: {
- *     submitPermissionGrant: async (typedData, signature) => {
- *       // Custom relay implementation
- *       return await myRelayer.submit(typedData, signature);
- *     }
- *   }
+ * // Mode 2: Read-only with public client and address
+ * const configReadOnly: VanaConfig = {
+ *   publicClient: createPublicClient({
+ *     chain: moksha,
+ *     transport: http()
+ *   }),
+ *   address: '0x1234...'
+ * };
+ *
+ * // Mode 3: Minimal with just address
+ * const configMinimal: VanaConfig = {
+ *   address: '0x1234...',
+ *   chain: moksha // optional
  * };
  * ```
  */
-export type VanaConfig = WalletConfig | ChainConfig;
+export type VanaConfig = VanaConfigWithWallet | VanaConfigReadOnly | VanaConfigAddressOnly | WalletConfig | ChainConfig;
 /**
  * Configuration interface for Vana SDK that requires storage providers.
  *
  * Use this type when you need to ensure storage is configured for operations
  * like file uploads, permission grants without pre-stored URLs, or schema creation.
+ * Supports all three initialization modes with required storage.
  *
  * @category Configuration
  * @example
  * ```typescript
- * // Configuration that guarantees storage availability
- * const config: VanaConfigWithStorage = {
+ * // Full configuration with wallet client and storage
+ * const configWithWallet: VanaConfigWithStorage = {
  *   walletClient: createWalletClient({
  *     account: privateKeyToAccount('0x...'),
  *     chain: moksha,
@@ -628,9 +574,24 @@ export type VanaConfig = WalletConfig | ChainConfig;
  *     defaultProvider: 'ipfs'
  *   }
  * };
+ *
+ * // Read-only configuration with storage
+ * const configReadOnly: VanaConfigWithStorage = {
+ *   publicClient: createPublicClient({
+ *     chain: moksha,
+ *     transport: http()
+ *   }),
+ *   address: '0x1234...',
+ *   storage: {
+ *     providers: {
+ *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })
+ *     },
+ *     defaultProvider: 'ipfs'
+ *   }
+ * };
  * ```
  */
-export type VanaConfigWithStorage = WalletConfigWithStorage | ChainConfigWithStorage;
+export type VanaConfigWithStorage = VanaConfigWithWalletWithStorage | VanaConfigReadOnlyWithStorage | VanaConfigAddressOnlyWithStorage | WalletConfigWithStorage | ChainConfigWithStorage;
 /**
  * Runtime configuration information
  *
@@ -645,24 +606,50 @@ export interface RuntimeConfig {
     storageProviders: string[];
     /** Default storage provider */
     defaultStorageProvider?: string;
-    /** Current relayer callbacks configuration */
-    relayerCallbacks?: RelayerCallbacks;
+    /** Current relayer configuration */
+    relayerConfig?: RelayerConfig;
 }
 /**
- * Validates whether a configuration object is a WalletConfig.
+ * Validates whether a configuration object has a wallet client (any wallet-based config).
  *
  * @param config - The configuration object to check
- * @returns True if the config is a WalletConfig (contains walletClient)
+ * @returns True if the config contains a walletClient
  * @example
  * ```typescript
  * if (isWalletConfig(config)) {
  *   console.log('Using wallet client:', config.walletClient.account?.address);
  * } else {
- *   console.log('Using chain config with chain ID:', config.chainId);
+ *   console.log('Read-only or chain config');
+ * }
+ * ```
+ */
+export declare function isWalletConfig(config: VanaConfig): config is VanaConfigWithWallet | WalletConfig;
+/**
+ * Validates whether a configuration object is a read-only config with public client.
+ *
+ * @param config - The configuration object to check
+ * @returns True if the config has publicClient and address but no walletClient
+ * @example
+ * ```typescript
+ * if (isReadOnlyConfig(config)) {
+ *   console.log('Read-only mode with address:', config.address);
  * }
  * ```
  */
-export declare function isWalletConfig(config: VanaConfig): config is WalletConfig;
+export declare function isReadOnlyConfig(config: VanaConfig): config is VanaConfigReadOnly;
+/**
+ * Validates whether a configuration object is an address-only config.
+ *
+ * @param config - The configuration object to check
+ * @returns True if the config has only address (and optionally chain) but no clients
+ * @example
+ * ```typescript
+ * if (isAddressOnlyConfig(config)) {
+ *   console.log('Address-only mode:', config.address);
+ * }
+ * ```
+ */
+export declare function isAddressOnlyConfig(config: VanaConfig): config is VanaConfigAddressOnly;
 /**
  * Validates whether a configuration object is a ChainConfig.
  *
@@ -721,3 +708,13 @@ export interface ConfigValidationResult {
     /** List of validation warnings */
     warnings: string[];
 }
+/**
+ * Marker interface to enforce the presence of operationStore at compile time.
+ * This interface is used to ensure that certain operations requiring a relayer
+ * can only be called when the SDK has been properly configured with an operation store.
+ *
+ * @category Configuration
+ */
+export interface RelayerRequiredMarker {
+    readonly __relayerConfigured: true;
+}

package/dist/types/config.js

@@ -1,6 +1,12 @@
 function isWalletConfig(config) {
   return "walletClient" in config;
 }
+function isReadOnlyConfig(config) {
+  return "publicClient" in config && "address" in config && !("walletClient" in config);
+}
+function isAddressOnlyConfig(config) {
+  return "address" in config && !("publicClient" in config) && !("walletClient" in config) && !("chainId" in config);
+}
 function isChainConfig(config) {
   return "chainId" in config && !("walletClient" in config);
 }
@@ -9,7 +15,9 @@ function hasStorageConfig(config) {
 }
 export {
   hasStorageConfig,
+  isAddressOnlyConfig,
   isChainConfig,
+  isReadOnlyConfig,
   isWalletConfig
 };
 //# sourceMappingURL=config.js.map