@opendatalabs/vana-sdk 0.1.0-alpha.7ee7635 → 0.1.0-alpha.80df35f

package/dist/types/config.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/config.ts"],"sourcesContent":["import type { WalletClient, Account, Hash, Address } from \"viem\";\nimport type { VanaChainId, VanaChain } from \"./chains\";\nimport type {\n  StorageProvider,\n  StorageUploadResult,\n  StorageListOptions,\n} from \"./storage\";\nimport type {\n  PermissionGrantTypedData,\n  TrustServerTypedData,\n  UntrustServerTypedData,\n  AddAndTrustServerTypedData,\n  GenericTypedData,\n  GrantFile,\n  ServerFilesAndPermissionTypedData,\n} from \"./permissions\";\n\n/**\n * Marker interface to indicate that a Vana instance has storage configured.\n * Used for compile-time type safety to ensure storage-dependent methods\n * are only called on properly configured instances.\n *\n * @category Configuration\n */\nexport interface StorageRequiredMarker {\n  readonly __storageRequired: true;\n}\n\n/**\n * Configuration for storage providers used by the SDK.\n *\n * Allows you to configure multiple storage backends (IPFS, Pinata, Google Drive, etc.)\n * and specify which one to use by default for file operations.\n *\n * **Provider Selection:**\n * - IPFS: Decentralized, permanent storage ideal for production\n * - Pinata: Managed IPFS with guaranteed availability\n * - Google Drive: Centralized, suitable for development/testing\n * - Custom providers: Implement StorageProvider interface\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storage: StorageConfig = {\n *   providers: {\n *     ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' }),\n *     pinata: new PinataStorage({ apiKey: 'your-key', secretKey: 'your-secret' })\n *   },\n *   defaultProvider: 'ipfs'\n * };\n * ```\n */\nexport interface StorageConfig {\n  /**\n   * Map of provider name to storage provider instance.\n   *   Common provider names: \"ipfs\", \"pinata\", \"googledrive\", \"s3\".\n   *   Custom names allowed for custom provider implementations.\n   */\n  providers: Record<string, StorageProvider>;\n  /**\n   * Default provider name to use when none specified.\n   *   Must match a key in the providers map. Falls back to first provider if not specified.\n   */\n  defaultProvider?: string;\n}\n\n/**\n * Download relayer callbacks for proxying CORS-restricted downloads.\n *\n * Provides a callback to proxy download requests through your application server\n * when direct browser access fails due to CORS restrictions (e.g., Google Drive).\n *\n * IMPORTANT SECURITY REQUIREMENTS for your proxy endpoint:\n * 1. MUST block requests to private/internal IPs (SSRF protection)\n * 2. SHOULD NOT restrict domains (files can be hosted anywhere)\n *\n * @category Configuration\n * @example Client-side implementation:\n * ```typescript\n * const downloadRelayer: DownloadRelayerCallbacks = {\n *   async proxyDownload(url) {\n *     const response = await fetch('/api/proxy', {\n *       method: 'POST',\n *       headers: { 'Content-Type': 'application/json' },\n *       body: JSON.stringify({ url })\n *     });\n *     return response.blob();\n *   }\n * };\n * ```\n *\n * @example Server-side proxy endpoint (Next.js):\n * ```typescript\n * // /api/proxy/route.ts\n * import { promises as dns } from 'dns';\n * import { isIPv4 } from 'net';\n *\n * async function handleProxy(url: string) {\n *   const { hostname } = new URL(url);\n *\n *   // Resolve hostname to IP (handle localhost specially)\n *   const ip = hostname === 'localhost' ? '127.0.0.1' :\n *              isIPv4(hostname) ? hostname :\n *              await dns.lookup(hostname).then(r => r.address);\n *\n *   // SSRF Protection: Block private/internal IPs\n *   if (isIPv4(ip)) {\n *     const [a, b] = ip.split('.').map(Number);\n *     if (a === 10 || a === 127 || a === 0 ||\n *         (a === 172 && b >= 16 && b <= 31) ||\n *         (a === 192 && b === 168) ||\n *         (a === 169 && b === 254) ||\n *         a >= 224) { // Also block multicast/reserved\n *       return new Response('Private/internal addresses not allowed', { status: 403 });\n *     }\n *   }\n *\n *   // Proxy the request\n *   const response = await fetch(url, { redirect: 'manual' });\n *\n *   // Handle redirects (with recursion limit)\n *   if (response.status >= 301 && response.status <= 308) {\n *     const location = response.headers.get('location');\n *     if (location) return handleProxy(new URL(location, url).href);\n *   }\n *\n *   const data = await response.arrayBuffer();\n *   return new Response(data, {\n *     headers: {\n *       'Content-Type': response.headers.get('content-type') || 'application/octet-stream',\n *       'Access-Control-Allow-Origin': '*'\n *     }\n *   });\n * }\n * ```\n */\nexport interface DownloadRelayerCallbacks {\n  /**\n   * Proxy a download request through your application server\n   *\n   * @param url - The URL to download from\n   * @returns Promise resolving to the downloaded content as a Blob\n   */\n  proxyDownload: (url: string) => Promise<Blob>;\n}\n\n/**\n * Relayer callback functions for handling gasless transactions.\n *\n * Instead of hardcoding HTTP/REST API calls, users can provide custom callback\n * functions to handle transaction relay in any way they choose (HTTP, WebSocket,\n * direct blockchain submission, etc.).\n *\n * @category Configuration\n * @example\n * ```typescript\n * const relayerCallbacks: RelayerCallbacks = {\n *   async submitPermissionGrant(typedData, signature) {\n *     // Custom implementation - could be HTTP, WebSocket, etc.\n *     const response = await fetch('https://my-relayer.com/api/grant', {\n *       method: 'POST',\n *       headers: { 'Content-Type': 'application/json' },\n *       body: JSON.stringify({ typedData, signature })\n *     });\n *     const result = await response.json();\n *     return result.transactionHash;\n *   },\n *\n *   async submitFileAddition(url, userAddress) {\n *     // Custom relay implementation\n *     return await myCustomRelayer.addFile(url, userAddress);\n *   }\n * };\n * ```\n */\nexport interface RelayerCallbacks {\n  /**\n   * Submit a signed permission grant transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitPermissionGrant?: (\n    typedData: PermissionGrantTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a signed permission revocation transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitPermissionRevoke?: (\n    typedData: GenericTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a signed trust server transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitTrustServer?: (\n    typedData: TrustServerTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a signed untrust server transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitUntrustServer?: (\n    typedData: UntrustServerTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a signed add and trust server transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitAddAndTrustServer?: (\n    typedData: AddAndTrustServerTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a signed permission addition transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitAddPermission?: (\n    typedData: GenericTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a signed server files and permissions transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitAddServerFilesAndPermissions?: (\n    typedData: ServerFilesAndPermissionTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a file addition for relay\n   *\n   * @deprecated Since v2.0.0 - Use submitFileAdditionComplete() instead for full support.\n   * Will be removed in v3.0.0.\n   *\n   * Migration guide:\n   * ```typescript\n   * // Old:\n   * await submitFileAddition(url, userAddress);\n   *\n   * // New:\n   * await submitFileAdditionComplete({\n   *   url,\n   *   userAddress,\n   *   permissions: [] // Optional\n   * });\n   * ```\n   * @param url - The file URL to register\n   * @param userAddress - The user's address\n   * @returns Promise resolving to object with fileId and transactionHash\n   */\n  submitFileAddition?: (\n    url: string,\n    userAddress: string,\n  ) => Promise<{ fileId: number; transactionHash: Hash }>;\n\n  /**\n   * Submit a file addition with permissions for relay\n   *\n   * @deprecated Since v2.0.0 - Use submitFileAdditionComplete() instead for full support.\n   * Will be removed in v3.0.0.\n   *\n   * Migration guide:\n   * ```typescript\n   * // Old:\n   * await submitFileAdditionWithPermissions(url, userAddress, permissions);\n   *\n   * // New:\n   * await submitFileAdditionComplete({\n   *   url,\n   *   userAddress,\n   *   permissions\n   * });\n   * ```\n   * @param url - The file URL to register\n   * @param userAddress - The user's address\n   * @param permissions - Array of encrypted permissions\n   * @returns Promise resolving to object with fileId and transactionHash\n   */\n  submitFileAdditionWithPermissions?: (\n    url: string,\n    userAddress: string,\n    permissions: Array<{ account: string; key: string }>,\n  ) => Promise<{ fileId: number; transactionHash: Hash }>;\n\n  /**\n   * Submit a comprehensive file addition with optional schema and permissions for relay\n   *\n   * This is the preferred callback that supports all file addition scenarios.\n   * It can handle files with schemas, permissions, or both.\n   *\n   * @param params - Complete parameters for file addition\n   * @param params.url - The file URL to register\n   * @param params.userAddress - The user's address (defaults to connected wallet if not specified)\n   * @param params.permissions - Array of encrypted permissions (empty array if none)\n   * @param params.schemaId - Schema ID for validation (0 if none)\n   * @param params.ownerAddress - Optional owner address (defaults to userAddress if not specified)\n   * @returns Promise resolving to object with fileId and transactionHash\n   */\n  submitFileAdditionComplete?: (params: {\n    url: string;\n    userAddress: Address;\n    permissions: Array<{ account: Address; key: string }>;\n    schemaId: number;\n    ownerAddress?: Address;\n  }) => Promise<{ fileId: number; transactionHash: Hash }>;\n\n  /**\n   * Store a grant file for relay (e.g., upload to IPFS)\n   *\n   * @param grantData - The grant file data\n   * @returns Promise resolving to the storage URL\n   */\n  storeGrantFile?: (grantData: GrantFile) => Promise<string>;\n}\n\n/**\n * Storage callback functions for flexible storage operations.\n *\n * Instead of hardcoding storage behavior (HTTP endpoints, etc.), users can provide\n * custom callback functions to handle storage operations in any way they choose.\n * This pattern matches the relayer callbacks approach, providing maximum flexibility.\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storageCallbacks: StorageCallbacks = {\n *   async upload(blob, filename, metadata) {\n *     // Custom implementation - could be HTTP, S3, local filesystem, etc.\n *     const formData = new FormData();\n *     formData.append('file', blob, filename);\n *     const response = await fetch('/api/storage/upload', {\n *       method: 'POST',\n *       body: formData\n *     });\n *     const data = await response.json();\n *     return {\n *       url: data.url,\n *       size: blob.size,\n *       contentType: blob.type,\n *       metadata: data.metadata\n *     };\n *   },\n *\n *   async download(identifier) {\n *     const response = await fetch(`/api/storage/download/${identifier}`);\n *     return response.blob();\n *   }\n * };\n * ```\n */\nexport interface StorageCallbacks {\n  /**\n   * Upload a blob to storage\n   *\n   * @param blob - The data to upload\n   * @param filename - Optional filename hint\n   * @param metadata - Optional metadata for the upload\n   * @returns Upload result with identifier and metadata\n   */\n  upload: (\n    blob: Blob,\n    filename?: string,\n    metadata?: Record<string, unknown>,\n  ) => Promise<StorageUploadResult>;\n\n  /**\n   * Download data from storage\n   *\n   * @param identifier - The storage identifier (could be URL, hash, path, or any unique ID)\n   * @param options - Optional download options\n   * @returns The downloaded data as a Blob\n   */\n  download: (\n    identifier: string,\n    options?: StorageDownloadOptions,\n  ) => Promise<Blob>;\n\n  /**\n   * List stored items (optional)\n   *\n   * @param prefix - Optional prefix to filter results\n   * @param options - Optional listing options\n   * @returns Array of storage items with metadata\n   */\n  list?: (\n    prefix?: string,\n    options?: StorageListOptions,\n  ) => Promise<StorageListResult>;\n\n  /**\n   * Delete a stored item (optional)\n   *\n   * @param identifier - The storage identifier to delete\n   * @returns Promise that resolves to true if deletion succeeded\n   */\n  delete?: (identifier: string) => Promise<boolean>;\n\n  /**\n   * Extract identifier from a URL or return as-is (optional)\n   * Used for backward compatibility with URL-based systems\n   *\n   * @param url - The URL to extract from\n   * @returns The extracted identifier\n   */\n  extractIdentifier?: (url: string) => string;\n}\n\n/**\n * Options for storage download operations\n *\n * @category Configuration\n */\nexport interface StorageDownloadOptions {\n  /** Optional HTTP headers */\n  headers?: Record<string, string>;\n  /** Optional abort signal for cancellation */\n  signal?: AbortSignal;\n  /** Optional byte range for partial downloads */\n  range?: { start?: number; end?: number };\n}\n\n/**\n * Result from storage list operations\n *\n * @category Configuration\n */\nexport interface StorageListResult {\n  /** Array of storage items */\n  items: Array<{\n    /** Item identifier */\n    identifier: string;\n    /** Item size in bytes */\n    size?: number;\n    /** Last modified timestamp */\n    lastModified?: Date;\n    /** Item metadata */\n    metadata?: Record<string, unknown>;\n  }>;\n  /** Continuation token for pagination */\n  continuationToken?: string;\n  /** Whether more results are available */\n  hasMore?: boolean;\n}\n\n/**\n * Base configuration interface without storage requirements\n *\n * @category Configuration\n */\nexport interface BaseConfig {\n  /**\n   * Optional relayer callback functions for handling gasless transactions.\n   * Provides flexible relay mechanism - can use HTTP, WebSocket, or any custom implementation.\n   */\n  relayerCallbacks?: RelayerCallbacks;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /**\n   * Optional storage providers configuration for file upload/download.\n   *   Required for: upload(), grant() without pre-stored URLs, schema operations.\n   *   See StorageConfig for provider selection guidance.\n   */\n  storage?: StorageConfig;\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   * Obtain chain-specific URLs from Vana documentation or deployment info.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   * Order matters: first successful gateway is used.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n}\n\n/**\n * Base configuration interface that requires storage for storage-dependent operations\n *\n * @category Configuration\n */\nexport interface BaseConfigWithStorage {\n  /**\n   * Optional relayer callback functions for handling gasless transactions.\n   * Provides flexible relay mechanism - can use HTTP, WebSocket, or any custom implementation.\n   */\n  relayerCallbacks?: RelayerCallbacks;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /** Required storage providers configuration for file upload/download */\n  storage: StorageConfig;\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n}\n\n/**\n * Configuration with wallet client\n *\n * @category Configuration\n */\nexport interface WalletConfig extends BaseConfig {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with wallet client that requires storage\n *\n * @category Configuration\n */\nexport interface WalletConfigWithStorage extends BaseConfigWithStorage {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with chain and account details\n *\n * @category Configuration\n */\nexport interface ChainConfig extends BaseConfig {\n  /**\n   * The chain ID for Vana network.\n   *   Supported: 14800 (Vana Mainnet), 14801 (Moksha Testnet), 31337 (Local Development).\n   *   Use chain constants from '@vana/sdk' for type safety.\n   */\n  chainId: VanaChainId;\n  /**\n   * RPC URL for the chain (optional, will use default for the chain if not provided).\n   *   Default URLs: mainnet (https://rpc.vana.org), testnet (https://rpc.moksha.vana.org).\n   *   Override for custom nodes or local development.\n   */\n  rpcUrl?: string;\n  /**\n   * Optional account for signing transactions.\n   *   Can be: privateKeyToAccount(), mnemonicToAccount(), or custom Account implementation.\n   *   Required for write operations; read-only operations work without account.\n   */\n  account?: Account;\n}\n\n/**\n * Configuration with chain and account details that requires storage\n *\n * @category Configuration\n */\nexport interface ChainConfigWithStorage extends BaseConfigWithStorage {\n  /** The chain ID for Vana network */\n  chainId: VanaChainId;\n  /** RPC URL for the chain (optional, will use default for the chain if not provided) */\n  rpcUrl?: string;\n  /** Optional account for signing transactions */\n  account?: Account;\n}\n\n/**\n * Main configuration interface for initializing the Vana SDK.\n *\n * You can configure the SDK using either a pre-configured wallet client\n * (WalletConfig) or by providing chain and account details (ChainConfig).\n * Both approaches support optional storage providers and relayer configuration.\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Using WalletConfig with pre-configured client\n * const config: VanaConfig = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   relayerCallbacks: {\n *     submitPermissionGrant: async (typedData, signature) => {\n *       // Custom relay implementation\n *       return await myRelayer.submit(typedData, signature);\n *     }\n *   }\n * };\n *\n * // Using ChainConfig with chain ID and account\n * const config: VanaConfig = {\n *   chainId: 14800,\n *   account: privateKeyToAccount('0x...'),\n *   relayerCallbacks: {\n *     submitPermissionGrant: async (typedData, signature) => {\n *       // Custom relay implementation\n *       return await myRelayer.submit(typedData, signature);\n *     }\n *   }\n * };\n * ```\n */\nexport type VanaConfig = WalletConfig | ChainConfig;\n\n/**\n * Configuration interface for Vana SDK that requires storage providers.\n *\n * Use this type when you need to ensure storage is configured for operations\n * like file uploads, permission grants without pre-stored URLs, or schema creation.\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Configuration that guarantees storage availability\n * const config: VanaConfigWithStorage = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   storage: {\n *     providers: {\n *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })\n *     },\n *     defaultProvider: 'ipfs'\n *   }\n * };\n * ```\n */\nexport type VanaConfigWithStorage =\n  | WalletConfigWithStorage\n  | ChainConfigWithStorage;\n\n/**\n * Runtime configuration information\n *\n * @category Configuration\n */\nexport interface RuntimeConfig {\n  /** Current chain ID */\n  chainId: VanaChainId;\n  /** Current chain name */\n  chainName: string;\n  /** Available storage providers */\n  storageProviders: string[];\n  /** Default storage provider */\n  defaultStorageProvider?: string;\n  /** Current relayer callbacks configuration */\n  relayerCallbacks?: RelayerCallbacks;\n}\n\n/**\n * Validates whether a configuration object is a WalletConfig.\n *\n * @param config - The configuration object to check\n * @returns True if the config is a WalletConfig (contains walletClient)\n * @example\n * ```typescript\n * if (isWalletConfig(config)) {\n *   console.log('Using wallet client:', config.walletClient.account?.address);\n * } else {\n *   console.log('Using chain config with chain ID:', config.chainId);\n * }\n * ```\n */\nexport function isWalletConfig(config: VanaConfig): config is WalletConfig {\n  return \"walletClient\" in config;\n}\n\n/**\n * Validates whether a configuration object is a ChainConfig.\n *\n * @param config - The configuration object to check\n * @returns True if the config is a ChainConfig (contains chainId but not walletClient)\n * @example\n * ```typescript\n * if (isChainConfig(config)) {\n *   console.log('Chain ID:', config.chainId);\n *   console.log('RPC URL:', config.rpcUrl);\n * } else {\n *   console.log('Using pre-configured wallet client');\n * }\n * ```\n */\nexport function isChainConfig(config: VanaConfig): config is ChainConfig {\n  return \"chainId\" in config && !(\"walletClient\" in config);\n}\n\n/**\n * Validates whether a configuration has required storage providers.\n *\n * @param config - The configuration object to check\n * @returns True if the config has storage providers configured\n * @example\n * ```typescript\n * if (hasStorageConfig(config)) {\n *   // Safe to use storage-dependent operations\n *   await vana.data.uploadFile(file);\n * } else {\n *   console.log('Storage not configured - some operations may fail');\n * }\n * ```\n */\nexport function hasStorageConfig(\n  config: VanaConfig,\n): config is VanaConfigWithStorage {\n  return (\n    config.storage?.providers !== undefined &&\n    Object.keys(config.storage.providers).length > 0\n  );\n}\n\n/**\n * Configuration validation options\n *\n * @category Configuration\n */\nexport interface ConfigValidationOptions {\n  /** Whether to validate storage providers */\n  validateStorage?: boolean;\n  /** Whether to validate relayer URL */\n  validateRelayer?: boolean;\n  /** Whether to validate chain configuration */\n  validateChain?: boolean;\n}\n\n/**\n * Configuration validation result\n *\n * @category Configuration\n */\nexport interface ConfigValidationResult {\n  /** Whether the configuration is valid */\n  valid: boolean;\n  /** List of validation errors */\n  errors: string[];\n  /** List of validation warnings */\n  warnings: string[];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA6tBO,SAAS,eAAe,QAA4C;AACzE,SAAO,kBAAkB;AAC3B;AAiBO,SAAS,cAAc,QAA2C;AACvE,SAAO,aAAa,UAAU,EAAE,kBAAkB;AACpD;AAiBO,SAAS,iBACd,QACiC;AACjC,SACE,OAAO,SAAS,cAAc,UAC9B,OAAO,KAAK,OAAO,QAAQ,SAAS,EAAE,SAAS;AAEnD;","names":[]}
+{"version":3,"sources":["../../src/types/config.ts"],"sourcesContent":["import type {\n  WalletClient,\n  PublicClient,\n  Account,\n  Hash,\n  Address,\n  Chain,\n} from \"viem\";\nimport type { VanaChainId, VanaChain } from \"./chains\";\nimport type {\n  StorageProvider,\n  StorageUploadResult,\n  StorageListOptions,\n} from \"./storage\";\nimport type {\n  PermissionGrantTypedData,\n  TrustServerTypedData,\n  UntrustServerTypedData,\n  AddAndTrustServerTypedData,\n  GenericTypedData,\n  GrantFile,\n  ServerFilesAndPermissionTypedData,\n} from \"./permissions\";\n\n/**\n * Marker interface to indicate that a Vana instance has storage configured.\n * Used for compile-time type safety to ensure storage-dependent methods\n * are only called on properly configured instances.\n *\n * @category Configuration\n */\nexport interface StorageRequiredMarker {\n  readonly __storageRequired: true;\n}\n\n/**\n * Configuration for storage providers used by the SDK.\n *\n * Allows you to configure multiple storage backends (IPFS, Pinata, Google Drive, etc.)\n * and specify which one to use by default for file operations.\n *\n * **Provider Selection:**\n * - IPFS: Decentralized, permanent storage ideal for production\n * - Pinata: Managed IPFS with guaranteed availability\n * - Google Drive: Centralized, suitable for development/testing\n * - Custom providers: Implement StorageProvider interface\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storage: StorageConfig = {\n *   providers: {\n *     ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' }),\n *     pinata: new PinataStorage({ apiKey: 'your-key', secretKey: 'your-secret' })\n *   },\n *   defaultProvider: 'ipfs'\n * };\n * ```\n */\nexport interface StorageConfig {\n  /**\n   * Map of provider name to storage provider instance.\n   *   Common provider names: \"ipfs\", \"pinata\", \"googledrive\", \"s3\".\n   *   Custom names allowed for custom provider implementations.\n   */\n  providers: Record<string, StorageProvider>;\n  /**\n   * Default provider name to use when none specified.\n   *   Must match a key in the providers map. Falls back to first provider if not specified.\n   */\n  defaultProvider?: string;\n}\n\n/**\n * Download relayer callbacks for proxying CORS-restricted downloads.\n *\n * Provides a callback to proxy download requests through your application server\n * when direct browser access fails due to CORS restrictions (e.g., Google Drive).\n *\n * IMPORTANT SECURITY REQUIREMENTS for your proxy endpoint:\n * 1. MUST block requests to private/internal IPs (SSRF protection)\n * 2. SHOULD NOT restrict domains (files can be hosted anywhere)\n *\n * @category Configuration\n * @example Client-side implementation:\n * ```typescript\n * const downloadRelayer: DownloadRelayerCallbacks = {\n *   async proxyDownload(url) {\n *     const response = await fetch('/api/proxy', {\n *       method: 'POST',\n *       headers: { 'Content-Type': 'application/json' },\n *       body: JSON.stringify({ url })\n *     });\n *     return response.blob();\n *   }\n * };\n * ```\n *\n * @example Server-side proxy endpoint (Next.js):\n * ```typescript\n * // /api/proxy/route.ts\n * import { promises as dns } from 'dns';\n * import { isIPv4 } from 'net';\n *\n * async function handleProxy(url: string) {\n *   const { hostname } = new URL(url);\n *\n *   // Resolve hostname to IP (handle localhost specially)\n *   const ip = hostname === 'localhost' ? '127.0.0.1' :\n *              isIPv4(hostname) ? hostname :\n *              await dns.lookup(hostname).then(r => r.address);\n *\n *   // SSRF Protection: Block private/internal IPs\n *   if (isIPv4(ip)) {\n *     const [a, b] = ip.split('.').map(Number);\n *     if (a === 10 || a === 127 || a === 0 ||\n *         (a === 172 && b >= 16 && b <= 31) ||\n *         (a === 192 && b === 168) ||\n *         (a === 169 && b === 254) ||\n *         a >= 224) { // Also block multicast/reserved\n *       return new Response('Private/internal addresses not allowed', { status: 403 });\n *     }\n *   }\n *\n *   // Proxy the request\n *   const response = await fetch(url, { redirect: 'manual' });\n *\n *   // Handle redirects (with recursion limit)\n *   if (response.status >= 301 && response.status <= 308) {\n *     const location = response.headers.get('location');\n *     if (location) return handleProxy(new URL(location, url).href);\n *   }\n *\n *   const data = await response.arrayBuffer();\n *   return new Response(data, {\n *     headers: {\n *       'Content-Type': response.headers.get('content-type') || 'application/octet-stream',\n *       'Access-Control-Allow-Origin': '*'\n *     }\n *   });\n * }\n * ```\n */\nexport interface DownloadRelayerCallbacks {\n  /**\n   * Proxy a download request through your application server\n   *\n   * @param url - The URL to download from\n   * @returns Promise resolving to the downloaded content as a Blob\n   */\n  proxyDownload: (url: string) => Promise<Blob>;\n}\n\n/**\n * Relayer callback functions for handling gasless transactions.\n *\n * Instead of hardcoding HTTP/REST API calls, users can provide custom callback\n * functions to handle transaction relay in any way they choose (HTTP, WebSocket,\n * direct blockchain submission, etc.).\n *\n * @category Configuration\n * @example\n * ```typescript\n * const relayerCallbacks: RelayerCallbacks = {\n *   async submitPermissionGrant(typedData, signature) {\n *     // Custom implementation - could be HTTP, WebSocket, etc.\n *     const response = await fetch('https://my-relayer.com/api/grant', {\n *       method: 'POST',\n *       headers: { 'Content-Type': 'application/json' },\n *       body: JSON.stringify({ typedData, signature })\n *     });\n *     const result = await response.json();\n *     return result.transactionHash;\n *   },\n *\n *   async submitFileAddition(url, userAddress) {\n *     // Custom relay implementation\n *     return await myCustomRelayer.addFile(url, userAddress);\n *   }\n * };\n * ```\n */\nexport interface RelayerCallbacks {\n  /**\n   * Submit a signed permission grant transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitPermissionGrant?: (\n    typedData: PermissionGrantTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a signed permission revocation transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitPermissionRevoke?: (\n    typedData: GenericTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a signed trust server transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitTrustServer?: (\n    typedData: TrustServerTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a signed untrust server transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitUntrustServer?: (\n    typedData: UntrustServerTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a signed add and trust server transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitAddAndTrustServer?: (\n    typedData: AddAndTrustServerTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a signed permission addition transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitAddPermission?: (\n    typedData: GenericTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a signed server files and permissions transaction for relay\n   *\n   * @param typedData - The EIP-712 typed data that was signed\n   * @param signature - The user's signature\n   * @returns Promise resolving to the transaction hash\n   */\n  submitAddServerFilesAndPermissions?: (\n    typedData: ServerFilesAndPermissionTypedData,\n    signature: Hash,\n  ) => Promise<Hash>;\n\n  /**\n   * Submit a file addition for relay\n   *\n   * @deprecated Since v2.0.0 - Use submitFileAdditionComplete() instead for full support.\n   * Will be removed in v3.0.0.\n   *\n   * Migration guide:\n   * ```typescript\n   * // Old:\n   * await submitFileAddition(url, userAddress);\n   *\n   * // New:\n   * await submitFileAdditionComplete({\n   *   url,\n   *   userAddress,\n   *   permissions: [] // Optional\n   * });\n   * ```\n   * @param url - The file URL to register\n   * @param userAddress - The user's address\n   * @returns Promise resolving to object with fileId and transactionHash\n   */\n  submitFileAddition?: (\n    url: string,\n    userAddress: string,\n  ) => Promise<{ fileId: number; transactionHash: Hash }>;\n\n  /**\n   * Submit a file addition with permissions for relay\n   *\n   * @deprecated Since v2.0.0 - Use submitFileAdditionComplete() instead for full support.\n   * Will be removed in v3.0.0.\n   *\n   * Migration guide:\n   * ```typescript\n   * // Old:\n   * await submitFileAdditionWithPermissions(url, userAddress, permissions);\n   *\n   * // New:\n   * await submitFileAdditionComplete({\n   *   url,\n   *   userAddress,\n   *   permissions\n   * });\n   * ```\n   * @param url - The file URL to register\n   * @param userAddress - The user's address\n   * @param permissions - Array of encrypted permissions\n   * @returns Promise resolving to object with fileId and transactionHash\n   */\n  submitFileAdditionWithPermissions?: (\n    url: string,\n    userAddress: string,\n    permissions: Array<{ account: string; key: string }>,\n  ) => Promise<{ fileId: number; transactionHash: Hash }>;\n\n  /**\n   * Submit a comprehensive file addition with optional schema and permissions for relay\n   *\n   * This is the preferred callback that supports all file addition scenarios.\n   * It can handle files with schemas, permissions, or both.\n   *\n   * @param params - Complete parameters for file addition\n   * @param params.url - The file URL to register\n   * @param params.userAddress - The user's address (defaults to connected wallet if not specified)\n   * @param params.permissions - Array of encrypted permissions (empty array if none)\n   * @param params.schemaId - Schema ID for validation (0 if none)\n   * @param params.ownerAddress - Optional owner address (defaults to userAddress if not specified)\n   * @returns Promise resolving to object with fileId and transactionHash\n   */\n  submitFileAdditionComplete?: (params: {\n    url: string;\n    userAddress: Address;\n    permissions: Array<{ account: Address; key: string }>;\n    schemaId: number;\n    ownerAddress?: Address;\n  }) => Promise<{ fileId: number; transactionHash: Hash }>;\n\n  /**\n   * Store a grant file for relay (e.g., upload to IPFS)\n   *\n   * @param grantData - The grant file data\n   * @returns Promise resolving to the storage URL\n   */\n  storeGrantFile?: (grantData: GrantFile) => Promise<string>;\n}\n\n/**\n * Storage callback functions for flexible storage operations.\n *\n * Instead of hardcoding storage behavior (HTTP endpoints, etc.), users can provide\n * custom callback functions to handle storage operations in any way they choose.\n * This pattern matches the relayer callbacks approach, providing maximum flexibility.\n *\n * @category Configuration\n * @example\n * ```typescript\n * const storageCallbacks: StorageCallbacks = {\n *   async upload(blob, filename, metadata) {\n *     // Custom implementation - could be HTTP, S3, local filesystem, etc.\n *     const formData = new FormData();\n *     formData.append('file', blob, filename);\n *     const response = await fetch('/api/storage/upload', {\n *       method: 'POST',\n *       body: formData\n *     });\n *     const data = await response.json();\n *     return {\n *       url: data.url,\n *       size: blob.size,\n *       contentType: blob.type,\n *       metadata: data.metadata\n *     };\n *   },\n *\n *   async download(identifier) {\n *     const response = await fetch(`/api/storage/download/${identifier}`);\n *     return response.blob();\n *   }\n * };\n * ```\n */\nexport interface StorageCallbacks {\n  /**\n   * Upload a blob to storage\n   *\n   * @param blob - The data to upload\n   * @param filename - Optional filename hint\n   * @param metadata - Optional metadata for the upload\n   * @returns Upload result with identifier and metadata\n   */\n  upload: (\n    blob: Blob,\n    filename?: string,\n    metadata?: Record<string, unknown>,\n  ) => Promise<StorageUploadResult>;\n\n  /**\n   * Download data from storage\n   *\n   * @param identifier - The storage identifier (could be URL, hash, path, or any unique ID)\n   * @param options - Optional download options\n   * @returns The downloaded data as a Blob\n   */\n  download: (\n    identifier: string,\n    options?: StorageDownloadOptions,\n  ) => Promise<Blob>;\n\n  /**\n   * List stored items (optional)\n   *\n   * @param prefix - Optional prefix to filter results\n   * @param options - Optional listing options\n   * @returns Array of storage items with metadata\n   */\n  list?: (\n    prefix?: string,\n    options?: StorageListOptions,\n  ) => Promise<StorageListResult>;\n\n  /**\n   * Delete a stored item (optional)\n   *\n   * @param identifier - The storage identifier to delete\n   * @returns Promise that resolves to true if deletion succeeded\n   */\n  delete?: (identifier: string) => Promise<boolean>;\n\n  /**\n   * Extract identifier from a URL or return as-is (optional)\n   * Used for backward compatibility with URL-based systems\n   *\n   * @param url - The URL to extract from\n   * @returns The extracted identifier\n   */\n  extractIdentifier?: (url: string) => string;\n}\n\n/**\n * Options for storage download operations\n *\n * @category Configuration\n */\nexport interface StorageDownloadOptions {\n  /** Optional HTTP headers */\n  headers?: Record<string, string>;\n  /** Optional abort signal for cancellation */\n  signal?: AbortSignal;\n  /** Optional byte range for partial downloads */\n  range?: { start?: number; end?: number };\n}\n\n/**\n * Result from storage list operations\n *\n * @category Configuration\n */\nexport interface StorageListResult {\n  /** Array of storage items */\n  items: Array<{\n    /** Item identifier */\n    identifier: string;\n    /** Item size in bytes */\n    size?: number;\n    /** Last modified timestamp */\n    lastModified?: Date;\n    /** Item metadata */\n    metadata?: Record<string, unknown>;\n  }>;\n  /** Continuation token for pagination */\n  continuationToken?: string;\n  /** Whether more results are available */\n  hasMore?: boolean;\n}\n\n/**\n * Base configuration interface without storage requirements\n *\n * @category Configuration\n */\nexport interface BaseConfig {\n  /**\n   * Optional relayer callback functions for handling gasless transactions.\n   * Provides flexible relay mechanism - can use HTTP, WebSocket, or any custom implementation.\n   */\n  relayerCallbacks?: RelayerCallbacks;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /**\n   * Optional storage providers configuration for file upload/download.\n   *   Required for: upload(), grant() without pre-stored URLs, schema operations.\n   *   See StorageConfig for provider selection guidance.\n   */\n  storage?: StorageConfig;\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   * Obtain chain-specific URLs from Vana documentation or deployment info.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   * Order matters: first successful gateway is used.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n}\n\n/**\n * Base configuration interface that requires storage for storage-dependent operations\n *\n * @category Configuration\n */\nexport interface BaseConfigWithStorage {\n  /**\n   * Optional relayer callback functions for handling gasless transactions.\n   * Provides flexible relay mechanism - can use HTTP, WebSocket, or any custom implementation.\n   */\n  relayerCallbacks?: RelayerCallbacks;\n\n  /**\n   * Optional download relayer for proxying CORS-restricted downloads.\n   * Provides a proxy mechanism for files stored on servers with CORS restrictions.\n   */\n  downloadRelayer?: DownloadRelayerCallbacks;\n\n  /** Required storage providers configuration for file upload/download */\n  storage: StorageConfig;\n  /**\n   * Optional subgraph URL for querying user files and permissions.\n   * If not provided, defaults to the built-in subgraph URL for the current chain.\n   * Can be overridden per method call if needed.\n   */\n  subgraphUrl?: string;\n  /**\n   * Optional default IPFS gateways to use for fetching files.\n   * These gateways will be used by default in fetchFromIPFS unless overridden per-call.\n   * If not provided, the SDK will use public gateways.\n   *\n   * @example ['https://gateway.pinata.cloud', 'https://ipfs.io']\n   */\n  ipfsGateways?: string[];\n  /**\n   * Default personal server base URL for server operations.\n   * Required for ServerController methods like getIdentity(), createOperation(), etc.\n   *\n   * @example 'https://my-personal-server.example.com'\n   */\n  defaultPersonalServerUrl?: string;\n}\n\n/**\n * Configuration with wallet client\n *\n * @category Configuration\n */\nexport interface WalletConfig extends BaseConfig {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with wallet client that requires storage\n *\n * @category Configuration\n */\nexport interface WalletConfigWithStorage extends BaseConfigWithStorage {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient & {\n    chain: VanaChain;\n  };\n}\n\n/**\n * Configuration with chain and account details\n *\n * @category Configuration\n */\nexport interface ChainConfig extends BaseConfig {\n  /**\n   * The chain ID for Vana network.\n   *   Supported: 14800 (Vana Mainnet), 14801 (Moksha Testnet), 31337 (Local Development).\n   *   Use chain constants from '@vana/sdk' for type safety.\n   */\n  chainId: VanaChainId;\n  /**\n   * RPC URL for the chain (optional, will use default for the chain if not provided).\n   *   Default URLs: mainnet (https://rpc.vana.org), testnet (https://rpc.moksha.vana.org).\n   *   Override for custom nodes or local development.\n   */\n  rpcUrl?: string;\n  /**\n   * Optional account for signing transactions.\n   *   Can be: privateKeyToAccount(), mnemonicToAccount(), or custom Account implementation.\n   *   Required for write operations; read-only operations work without account.\n   */\n  account?: Account;\n}\n\n/**\n * Configuration with chain and account details that requires storage\n *\n * @category Configuration\n */\nexport interface ChainConfigWithStorage extends BaseConfigWithStorage {\n  /** The chain ID for Vana network */\n  chainId: VanaChainId;\n  /** RPC URL for the chain (optional, will use default for the chain if not provided) */\n  rpcUrl?: string;\n  /** Optional account for signing transactions */\n  account?: Account;\n}\n\n/**\n * Configuration with wallet client and optional public client\n *\n * @category Configuration\n */\nexport interface VanaConfigWithWallet extends BaseConfig {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient;\n  /** Optional PublicClient for read operations (derived from wallet if not provided) */\n  publicClient?: PublicClient;\n}\n\n/**\n * Configuration for read-only operations with public client and address\n *\n * @category Configuration\n */\nexport interface VanaConfigReadOnly extends BaseConfig {\n  /** The viem PublicClient instance for read operations */\n  publicClient: PublicClient;\n  /** The user's address for read operations */\n  address: Address;\n}\n\n/**\n * Configuration for minimal read-only operations with just an address\n *\n * @category Configuration\n */\nexport interface VanaConfigAddressOnly extends BaseConfig {\n  /** The user's address for read operations */\n  address: Address;\n  /** Optional chain configuration (will use default if not provided) */\n  chain?: Chain;\n}\n\n/**\n * Configuration with wallet client and optional public client that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigWithWalletWithStorage extends BaseConfigWithStorage {\n  /** The viem WalletClient instance used for signing transactions */\n  walletClient: WalletClient;\n  /** Optional PublicClient for read operations (derived from wallet if not provided) */\n  publicClient?: PublicClient;\n}\n\n/**\n * Configuration for read-only operations with public client and address that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigReadOnlyWithStorage extends BaseConfigWithStorage {\n  /** The viem PublicClient instance for read operations */\n  publicClient: PublicClient;\n  /** The user's address for read operations */\n  address: Address;\n}\n\n/**\n * Configuration for minimal read-only operations with just an address that requires storage\n *\n * @category Configuration\n */\nexport interface VanaConfigAddressOnlyWithStorage\n  extends BaseConfigWithStorage {\n  /** The user's address for read operations */\n  address: Address;\n  /** Optional chain configuration (will use default if not provided) */\n  chain?: Chain;\n}\n\n/**\n * Main configuration interface for initializing the Vana SDK.\n *\n * The SDK supports three initialization modes:\n * 1. Full mode with wallet client for signing transactions\n * 2. Read-only mode with public client and address for read operations\n * 3. Minimal mode with just an address and optional chain\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Mode 1: Full configuration with wallet client\n * const configWithWallet: VanaConfig = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   })\n * };\n *\n * // Mode 2: Read-only with public client and address\n * const configReadOnly: VanaConfig = {\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   address: '0x1234...'\n * };\n *\n * // Mode 3: Minimal with just address\n * const configMinimal: VanaConfig = {\n *   address: '0x1234...',\n *   chain: moksha // optional\n * };\n * ```\n */\nexport type VanaConfig =\n  | VanaConfigWithWallet\n  | VanaConfigReadOnly\n  | VanaConfigAddressOnly\n  | WalletConfig\n  | ChainConfig;\n\n/**\n * Configuration interface for Vana SDK that requires storage providers.\n *\n * Use this type when you need to ensure storage is configured for operations\n * like file uploads, permission grants without pre-stored URLs, or schema creation.\n * Supports all three initialization modes with required storage.\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Full configuration with wallet client and storage\n * const configWithWallet: VanaConfigWithStorage = {\n *   walletClient: createWalletClient({\n *     account: privateKeyToAccount('0x...'),\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   storage: {\n *     providers: {\n *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })\n *     },\n *     defaultProvider: 'ipfs'\n *   }\n * };\n *\n * // Read-only configuration with storage\n * const configReadOnly: VanaConfigWithStorage = {\n *   publicClient: createPublicClient({\n *     chain: moksha,\n *     transport: http()\n *   }),\n *   address: '0x1234...',\n *   storage: {\n *     providers: {\n *       ipfs: new IPFSStorage({ gateway: 'https://gateway.pinata.cloud' })\n *     },\n *     defaultProvider: 'ipfs'\n *   }\n * };\n * ```\n */\nexport type VanaConfigWithStorage =\n  | VanaConfigWithWalletWithStorage\n  | VanaConfigReadOnlyWithStorage\n  | VanaConfigAddressOnlyWithStorage\n  | WalletConfigWithStorage\n  | ChainConfigWithStorage;\n\n/**\n * Runtime configuration information\n *\n * @category Configuration\n */\nexport interface RuntimeConfig {\n  /** Current chain ID */\n  chainId: VanaChainId;\n  /** Current chain name */\n  chainName: string;\n  /** Available storage providers */\n  storageProviders: string[];\n  /** Default storage provider */\n  defaultStorageProvider?: string;\n  /** Current relayer callbacks configuration */\n  relayerCallbacks?: RelayerCallbacks;\n}\n\n/**\n * Validates whether a configuration object has a wallet client (any wallet-based config).\n *\n * @param config - The configuration object to check\n * @returns True if the config contains a walletClient\n * @example\n * ```typescript\n * if (isWalletConfig(config)) {\n *   console.log('Using wallet client:', config.walletClient.account?.address);\n * } else {\n *   console.log('Read-only or chain config');\n * }\n * ```\n */\nexport function isWalletConfig(\n  config: VanaConfig,\n): config is VanaConfigWithWallet | WalletConfig {\n  return \"walletClient\" in config;\n}\n\n/**\n * Validates whether a configuration object is a read-only config with public client.\n *\n * @param config - The configuration object to check\n * @returns True if the config has publicClient and address but no walletClient\n * @example\n * ```typescript\n * if (isReadOnlyConfig(config)) {\n *   console.log('Read-only mode with address:', config.address);\n * }\n * ```\n */\nexport function isReadOnlyConfig(\n  config: VanaConfig,\n): config is VanaConfigReadOnly {\n  return (\n    \"publicClient\" in config &&\n    \"address\" in config &&\n    !(\"walletClient\" in config)\n  );\n}\n\n/**\n * Validates whether a configuration object is an address-only config.\n *\n * @param config - The configuration object to check\n * @returns True if the config has only address (and optionally chain) but no clients\n * @example\n * ```typescript\n * if (isAddressOnlyConfig(config)) {\n *   console.log('Address-only mode:', config.address);\n * }\n * ```\n */\nexport function isAddressOnlyConfig(\n  config: VanaConfig,\n): config is VanaConfigAddressOnly {\n  return (\n    \"address\" in config &&\n    !(\"publicClient\" in config) &&\n    !(\"walletClient\" in config) &&\n    !(\"chainId\" in config)\n  );\n}\n\n/**\n * Validates whether a configuration object is a ChainConfig.\n *\n * @param config - The configuration object to check\n * @returns True if the config is a ChainConfig (contains chainId but not walletClient)\n * @example\n * ```typescript\n * if (isChainConfig(config)) {\n *   console.log('Chain ID:', config.chainId);\n *   console.log('RPC URL:', config.rpcUrl);\n * } else {\n *   console.log('Using pre-configured wallet client');\n * }\n * ```\n */\nexport function isChainConfig(config: VanaConfig): config is ChainConfig {\n  return \"chainId\" in config && !(\"walletClient\" in config);\n}\n\n/**\n * Validates whether a configuration has required storage providers.\n *\n * @param config - The configuration object to check\n * @returns True if the config has storage providers configured\n * @example\n * ```typescript\n * if (hasStorageConfig(config)) {\n *   // Safe to use storage-dependent operations\n *   await vana.data.uploadFile(file);\n * } else {\n *   console.log('Storage not configured - some operations may fail');\n * }\n * ```\n */\nexport function hasStorageConfig(\n  config: VanaConfig,\n): config is VanaConfigWithStorage {\n  return (\n    config.storage?.providers !== undefined &&\n    Object.keys(config.storage.providers).length > 0\n  );\n}\n\n/**\n * Configuration validation options\n *\n * @category Configuration\n */\nexport interface ConfigValidationOptions {\n  /** Whether to validate storage providers */\n  validateStorage?: boolean;\n  /** Whether to validate relayer URL */\n  validateRelayer?: boolean;\n  /** Whether to validate chain configuration */\n  validateChain?: boolean;\n}\n\n/**\n * Configuration validation result\n *\n * @category Configuration\n */\nexport interface ConfigValidationResult {\n  /** Whether the configuration is valid */\n  valid: boolean;\n  /** List of validation errors */\n  errors: string[];\n  /** List of validation warnings */\n  warnings: string[];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAu0BO,SAAS,eACd,QAC+C;AAC/C,SAAO,kBAAkB;AAC3B;AAcO,SAAS,iBACd,QAC8B;AAC9B,SACE,kBAAkB,UAClB,aAAa,UACb,EAAE,kBAAkB;AAExB;AAcO,SAAS,oBACd,QACiC;AACjC,SACE,aAAa,UACb,EAAE,kBAAkB,WACpB,EAAE,kBAAkB,WACpB,EAAE,aAAa;AAEnB;AAiBO,SAAS,cAAc,QAA2C;AACvE,SAAO,aAAa,UAAU,EAAE,kBAAkB;AACpD;AAiBO,SAAS,iBACd,QACiC;AACjC,SACE,OAAO,SAAS,cAAc,UAC9B,OAAO,KAAK,OAAO,QAAQ,SAAS,EAAE,SAAS;AAEnD;","names":[]}

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, Hash, 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";
 /**
  * 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
      *
@@ -158,7 +157,7 @@ interface DownloadRelayerCallbacks {
  * };
  * ```
  */
-interface RelayerCallbacks {
+export interface RelayerCallbacks {
     /**
      * Submit a signed permission grant transaction for relay
      *
@@ -341,7 +340,7 @@ interface RelayerCallbacks {
  * };
  * ```
  */
-interface StorageCallbacks {
+export interface StorageCallbacks {
     /**
      * Upload a blob to storage
      *
@@ -388,7 +387,7 @@ interface StorageCallbacks {
  *
  * @category Configuration
  */
-interface StorageDownloadOptions {
+export interface StorageDownloadOptions {
     /** Optional HTTP headers */
     headers?: Record<string, string>;
     /** Optional abort signal for cancellation */
@@ -404,7 +403,7 @@ interface StorageDownloadOptions {
  *
  * @category Configuration
  */
-interface StorageListResult {
+export interface StorageListResult {
     /** Array of storage items */
     items: Array<{
         /** Item identifier */
@@ -426,7 +425,7 @@ 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.
@@ -472,7 +471,7 @@ 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.
@@ -512,7 +511,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 +522,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 +533,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 +558,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 +566,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 +697,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 */
@@ -650,20 +733,46 @@ interface RuntimeConfig {
     relayerCallbacks?: RelayerCallbacks;
 }
 /**
- * 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 +788,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 +804,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 +823,7 @@ interface ConfigValidationOptions {
  *
  * @category Configuration
  */
-interface ConfigValidationResult {
+export interface ConfigValidationResult {
     /** Whether the configuration is valid */
     valid: boolean;
     /** List of validation errors */
@@ -722,5 +831,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