@opendatalabs/vana-sdk 0.1.0-alpha.276ea01 → 0.1.0-alpha.2b6935d

package/dist/types/config.d.ts

@@ -1,8 +1,7 @@
-import { Hash, Address, WalletClient, Account } from 'viem';
-import { VanaChain, VanaChainId } from './chains.js';
-import { StorageProvider, StorageUploadResult, StorageListOptions } from './storage.js';
-import { PermissionGrantTypedData, GenericTypedData, TrustServerTypedData, UntrustServerTypedData, AddAndTrustServerTypedData, ServerFilesAndPermissionTypedData, GrantFile } from './permissions.js';
-
+import type { WalletClient, PublicClient, Account, Address, Chain } from "viem";
+import type { VanaChainId, VanaChain } from "./chains";
+import type { StorageProvider, StorageUploadResult, StorageListOptions } from "./storage";
+import type { RelayerConfig } from "./relayer";
 /**
  * Marker interface to indicate that a Vana instance has storage configured.
  * Used for compile-time type safety to ensure storage-dependent methods
@@ -10,7 +9,7 @@ import { PermissionGrantTypedData, GenericTypedData, TrustServerTypedData, Untru
  *
  * @category Configuration
  */
-interface StorageRequiredMarker {
+export interface StorageRequiredMarker {
     readonly __storageRequired: true;
 }
 /**
@@ -37,7 +36,7 @@ interface StorageRequiredMarker {
  * };
  * ```
  */
-interface StorageConfig {
+export interface StorageConfig {
     /**
      * Map of provider name to storage provider instance.
      *   Common provider names: "ipfs", "pinata", "googledrive", "s3".
@@ -120,7 +119,7 @@ interface StorageConfig {
  * }
  * ```
  */
-interface DownloadRelayerCallbacks {
+export interface DownloadRelayerCallbacks {
     /**
      * Proxy a download request through your application server
      *
@@ -129,183 +128,6 @@ 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);
- *   }
- * };
- * ```
- */
-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.
  *
@@ -341,7 +163,7 @@ interface RelayerCallbacks {
  * };
  * ```
  */
-interface StorageCallbacks {
+export interface StorageCallbacks {
     /**
      * Upload a blob to storage
      *
@@ -388,7 +210,7 @@ interface StorageCallbacks {
  *
  * @category Configuration
  */
-interface StorageDownloadOptions {
+export interface StorageDownloadOptions {
     /** Optional HTTP headers */
     headers?: Record<string, string>;
     /** Optional abort signal for cancellation */
@@ -404,7 +226,7 @@ interface StorageDownloadOptions {
  *
  * @category Configuration
  */
-interface StorageListResult {
+export interface StorageListResult {
     /** Array of storage items */
     items: Array<{
         /** Item identifier */
@@ -426,12 +248,27 @@ interface StorageListResult {
  *
  * @category Configuration
  */
-interface BaseConfig {
+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.
@@ -472,12 +309,27 @@ interface BaseConfig {
  *
  * @category Configuration
  */
-interface BaseConfigWithStorage {
+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.
@@ -512,7 +364,7 @@ interface BaseConfigWithStorage {
  *
  * @category Configuration
  */
-interface WalletConfig extends BaseConfig {
+export interface WalletConfig extends BaseConfig {
     /** The viem WalletClient instance used for signing transactions */
     walletClient: WalletClient & {
         chain: VanaChain;
@@ -523,7 +375,7 @@ interface WalletConfig extends BaseConfig {
  *
  * @category Configuration
  */
-interface WalletConfigWithStorage extends BaseConfigWithStorage {
+export interface WalletConfigWithStorage extends BaseConfigWithStorage {
     /** The viem WalletClient instance used for signing transactions */
     walletClient: WalletClient & {
         chain: VanaChain;
@@ -534,7 +386,7 @@ interface WalletConfigWithStorage extends BaseConfigWithStorage {
  *
  * @category Configuration
  */
-interface ChainConfig extends BaseConfig {
+export interface ChainConfig extends BaseConfig {
     /**
      * The chain ID for Vana network.
      *   Supported: 14800 (Vana Mainnet), 14801 (Moksha Testnet), 31337 (Local Development).
@@ -559,7 +411,7 @@ interface ChainConfig extends BaseConfig {
  *
  * @category Configuration
  */
-interface ChainConfigWithStorage extends BaseConfigWithStorage {
+export interface ChainConfigWithStorage extends BaseConfigWithStorage {
     /** The chain ID for Vana network */
     chainId: VanaChainId;
     /** RPC URL for the chain (optional, will use default for the chain if not provided) */
@@ -567,56 +419,125 @@ 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
  * };
  * ```
  */
-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,
@@ -629,15 +550,30 @@ 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'
+ *   }
+ * };
  * ```
  */
-type VanaConfigWithStorage = WalletConfigWithStorage | ChainConfigWithStorage;
+export type VanaConfigWithStorage = VanaConfigWithWalletWithStorage | VanaConfigReadOnlyWithStorage | VanaConfigAddressOnlyWithStorage | WalletConfigWithStorage | ChainConfigWithStorage;
 /**
  * Runtime configuration information
  *
  * @category Configuration
  */
-interface RuntimeConfig {
+export interface RuntimeConfig {
     /** Current chain ID */
     chainId: VanaChainId;
     /** Current chain name */
@@ -646,24 +582,50 @@ 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 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);
  * }
  * ```
  */
-declare function isWalletConfig(config: VanaConfig): config is WalletConfig;
+export declare function isAddressOnlyConfig(config: VanaConfig): config is VanaConfigAddressOnly;
 /**
  * Validates whether a configuration object is a ChainConfig.
  *
@@ -679,7 +641,7 @@ declare function isWalletConfig(config: VanaConfig): config is WalletConfig;
  * }
  * ```
  */
-declare function isChainConfig(config: VanaConfig): config is ChainConfig;
+export declare function isChainConfig(config: VanaConfig): config is ChainConfig;
 /**
  * Validates whether a configuration has required storage providers.
  *
@@ -695,13 +657,13 @@ declare function isChainConfig(config: VanaConfig): config is ChainConfig;
  * }
  * ```
  */
-declare function hasStorageConfig(config: VanaConfig): config is VanaConfigWithStorage;
+export declare function hasStorageConfig(config: VanaConfig): config is VanaConfigWithStorage;
 /**
  * Configuration validation options
  *
  * @category Configuration
  */
-interface ConfigValidationOptions {
+export interface ConfigValidationOptions {
     /** Whether to validate storage providers */
     validateStorage?: boolean;
     /** Whether to validate relayer URL */
@@ -714,7 +676,7 @@ interface ConfigValidationOptions {
  *
  * @category Configuration
  */
-interface ConfigValidationResult {
+export interface ConfigValidationResult {
     /** Whether the configuration is valid */
     valid: boolean;
     /** List of validation errors */
@@ -722,5 +684,3 @@ interface ConfigValidationResult {
     /** List of validation warnings */
     warnings: string[];
 }
-
-export { type BaseConfig, type BaseConfigWithStorage, type ChainConfig, type ChainConfigWithStorage, type ConfigValidationOptions, type ConfigValidationResult, type DownloadRelayerCallbacks, type RelayerCallbacks, type RuntimeConfig, type StorageCallbacks, type StorageConfig, type StorageDownloadOptions, type StorageListResult, type StorageRequiredMarker, type VanaConfig, type VanaConfigWithStorage, type WalletConfig, type WalletConfigWithStorage, hasStorageConfig, isChainConfig, isWalletConfig };

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