@opendatalabs/vana-sdk 0.1.0-alpha.cb72de2 → 0.1.0-alpha.d44f792

package/dist/index.node.cjs

@@ -34254,6 +34254,19 @@ var SignatureCache = class {
   static DEFAULT_TTL_HOURS = 2;
   /**
    * Get a cached signature if it exists and hasn't expired
+   *
+   * @param cache - Platform cache adapter instance
+   * @param walletAddress - Wallet address that created the signature
+   * @param messageHash - Hash of the message that was signed
+   * @returns The cached signature if valid, null if expired or not found
+   * @example
+   * ```typescript
+   * const messageHash = SignatureCache.hashMessage(typedData);
+   * const cached = SignatureCache.get(cache, '0x123...', messageHash);
+   * if (cached) {
+   *   console.log('Using cached signature:', cached);
+   * }
+   * ```
    */
   static get(cache, walletAddress, messageHash) {
     const key = this.getCacheKey(walletAddress, messageHash);
@@ -34275,7 +34288,24 @@ var SignatureCache = class {
     }
   }
   /**
-   * Store a signature in the cache
+   * Store a signature in the cache with configurable TTL
+   *
+   * @param cache - Platform cache adapter instance
+   * @param walletAddress - Wallet address that created the signature
+   * @param messageHash - Hash of the message that was signed
+   * @param signature - The signature to cache
+   * @param ttlHours - Time to live in hours (default: 2)
+   * @example
+   * ```typescript
+   * const signature = await wallet.signTypedData(typedData);
+   * const messageHash = SignatureCache.hashMessage(typedData);
+   *
+   * // Cache for default 2 hours
+   * SignatureCache.set(cache, walletAddress, messageHash, signature);
+   *
+   * // Cache for 24 hours
+   * SignatureCache.set(cache, walletAddress, messageHash, signature, 24);
+   * ```
    */
   static set(cache, walletAddress, messageHash, signature, ttlHours = this.DEFAULT_TTL_HOURS) {
     const key = this.getCacheKey(walletAddress, messageHash);
@@ -34291,6 +34321,18 @@ var SignatureCache = class {
   }
   /**
    * Clear all cached signatures (useful for testing or explicit cleanup)
+   *
+   * @param cache - Platform cache adapter instance
+   * @example
+   * ```typescript
+   * // Clear all signatures when user logs out
+   * SignatureCache.clear(cache);
+   *
+   * // Clear before running tests
+   * beforeEach(() => {
+   *   SignatureCache.clear(cache);
+   * });
+   * ```
    */
   static clear(cache) {
     try {
@@ -34301,6 +34343,27 @@ var SignatureCache = class {
   static getCacheKey(walletAddress, messageHash) {
     return `${this.PREFIX}${walletAddress.toLowerCase()}:${messageHash}`;
   }
+  /**
+   * Generate a deterministic hash of a message object for cache key generation
+   *
+   * @remarks
+   * Creates a consistent hash from complex objects including EIP-712 typed data.
+   * Handles BigInt serialization and produces a 32-character hash that balances
+   * uniqueness with key length constraints.
+   *
+   * @param message - The message object to hash (typically EIP-712 typed data)
+   * @returns A 32-character hash string suitable for cache keys
+   * @example
+   * ```typescript
+   * const typedData = {
+   *   domain: { name: 'Vana', version: '1' },
+   *   message: { nonce: 123n, grant: '...' }
+   * };
+   *
+   * const hash = SignatureCache.hashMessage(typedData);
+   * // Returns something like: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
+   * ```
+   */
   static hashMessage(message) {
     const jsonString = JSON.stringify(message, this.bigIntReplacer);
     const base64Hash = toBase64(jsonString);
@@ -34313,8 +34376,12 @@ var SignatureCache = class {
   /**
    * Custom JSON replacer that converts BigInt values to strings for serialization
    * This ensures deterministic cache key generation for EIP-712 typed data
+   *
+   * @param _key - The object key being serialized (unused)
+   * @param value - The value to serialize
+   * @returns The serialized value
    */
-  static bigIntReplacer(key, value) {
+  static bigIntReplacer(_key, value) {
     if (typeof value === "bigint") {
       return `__BIGINT__${value.toString()}`;
     }
@@ -34339,7 +34406,7 @@ var PermissionsController = class {
   }
   /**
    * Grants permission for an application to access user data with gasless transactions.
-   * 
+   *
    * This method provides a complete end-to-end permission grant flow that returns
    * the permission ID and other relevant data immediately after successful submission.
    * For advanced users who need more control over the transaction lifecycle, use
@@ -34366,7 +34433,7 @@ var PermissionsController = class {
    *
    * console.log(`Permission ${result.permissionId} granted to ${result.user}`);
    * console.log(`Transaction: ${result.transactionHash}`);
-   * 
+   *
    * // Can immediately use the permission ID for other operations
    * await vana.permissions.revoke({ permissionId: result.permissionId });
    * ```
@@ -34377,12 +34444,12 @@ var PermissionsController = class {
   }
   /**
    * Submits a permission grant transaction and returns the transaction hash immediately.
-   * 
+   *
    * This is the lower-level method that provides maximum control over transaction timing.
    * Use this when you want to handle transaction confirmation and event parsing separately,
    * or when submitting multiple transactions in batch.
    *
-   * @param params - The permission grant configuration object  
+   * @param params - The permission grant configuration object
    * @returns Promise that resolves to the transaction hash when successfully submitted
    * @throws {RelayerError} When gasless transaction submission fails
    * @throws {SignatureError} When user rejects the signature request
@@ -34393,7 +34460,7 @@ var PermissionsController = class {
    * // Submit transaction and handle confirmation later
    * const txHash = await vana.permissions.submitPermissionGrant(params);
    * console.log(`Transaction submitted: ${txHash}`);
-   * 
+   *
    * // Later, when you need the permission data:
    * const result = await parseTransactionResult(context, txHash, 'grant');
    * console.log(`Permission ID: ${result.permissionId}`);
@@ -34413,6 +34480,8 @@ var PermissionsController = class {
    * until the returned `confirm()` function is called.
    * @param params - The permission grant parameters
    * @returns A promise resolving to a preview object and confirm function
+   * @throws {SerializationError} When grant parameters are invalid or cannot be serialized
+   * @throws {BlockchainError} When grant validation fails or preparation encounters an error
    * @example
    * ```typescript
    * const { preview, confirm } = await vana.permissions.prepareGrant({
@@ -34816,13 +34885,13 @@ var PermissionsController = class {
   }
   /**
    * Revokes a previously granted permission.
-   * 
+   *
    * This method provides complete revocation with automatic event parsing to confirm
    * the permission was successfully revoked. For advanced users who need more control,
    * use `submitPermissionRevoke()` instead.
    *
    * @param params - Parameters for revoking the permission
-   * @param params.permissionId - Permission identifier as bigint for contract compatibility.
+   * @param params.permissionId - Permission identifier (accepts bigint, number, or string).
    *   Obtain from permission grants via `getUserPermissionGrantsOnChain()`.
    * @returns Promise resolving to revocation data from PermissionRevoked event
    * @throws {BlockchainError} When revocation fails or event parsing fails
@@ -34844,7 +34913,7 @@ var PermissionsController = class {
   }
   /**
    * Submits a permission revocation transaction and returns the transaction hash immediately.
-   * 
+   *
    * This is the lower-level method that provides maximum control over transaction timing.
    * Use this when you want to handle transaction confirmation and event parsing separately.
    *
@@ -34899,6 +34968,11 @@ var PermissionsController = class {
    *
    * @param params - Parameters for revoking the permission
    * @returns Promise resolving to transaction hash
+   * @throws {BlockchainError} When chain ID is not available
+   * @throws {NonceError} When retrieving user nonce fails
+   * @throws {SignatureError} When user rejects the signature request
+   * @throws {RelayerError} When gasless submission fails
+   * @throws {PermissionError} When revocation fails for any other reason
    */
   async revokeWithSignature(params) {
     try {
@@ -34941,6 +35015,9 @@ var PermissionsController = class {
    * Retrieves the user's current nonce from the DataPermissions contract.
    *
    * @returns Promise resolving to the user's current nonce value
+   * @throws {Error} When wallet account is not available
+   * @throws {Error} When chain ID is not available
+   * @throws {NonceError} When reading nonce from contract fails
    */
   async getUserNonce() {
     try {
@@ -35187,6 +35264,7 @@ var PermissionsController = class {
    *
    * @param fileId - The file ID to query permissions for
    * @returns Promise resolving to array of permission IDs
+   * @throws {BlockchainError} When reading from contract fails or chain is unavailable
    */
   async getFilePermissionIds(fileId) {
     try {
@@ -35215,6 +35293,7 @@ var PermissionsController = class {
    *
    * @param permissionId - The permission ID to query files for
    * @returns Promise resolving to array of file IDs
+   * @throws {BlockchainError} When reading from contract fails or chain is unavailable
    */
   async getPermissionFileIds(permissionId) {
     try {
@@ -35243,6 +35322,7 @@ var PermissionsController = class {
    *
    * @param permissionId - The permission ID to check
    * @returns Promise resolving to boolean indicating if permission is active
+   * @throws {BlockchainError} When reading from contract fails or chain is unavailable
    */
   async isActivePermission(permissionId) {
     try {
@@ -35271,6 +35351,7 @@ var PermissionsController = class {
    *
    * @param permissionId - The permission ID to query
    * @returns Promise resolving to permission info
+   * @throws {BlockchainError} When reading from contract fails or chain is unavailable
    */
   async getPermissionInfo(permissionId) {
     try {
@@ -35318,7 +35399,12 @@ var PermissionsController = class {
    * Trusts a server for data processing.
    *
    * @param params - Parameters for trusting the server
+   * @param params.serverId - The server's Ethereum address
+   * @param params.serverUrl - The server's URL endpoint
    * @returns Promise resolving to transaction hash
+   * @throws {UserRejectedRequestError} When user rejects the transaction
+   * @throws {BlockchainError} When chain ID is unavailable or transaction fails
+   * @throws {Error} When wallet account is not available
    * @example
    * ```typescript
    * // Trust a server by providing its ID and URL
@@ -35365,6 +35451,12 @@ var PermissionsController = class {
    *
    * @param params - Parameters for trusting the server
    * @returns Promise resolving to transaction hash
+   * @throws {BlockchainError} When chain ID is not available
+   * @throws {NonceError} When retrieving user nonce fails
+   * @throws {SignatureError} When user rejects the signature request
+   * @throws {RelayerError} When gasless submission fails
+   * @throws {ServerUrlMismatchError} When server URL doesn't match existing registration
+   * @throws {BlockchainError} When trust operation fails for any other reason
    */
   async trustServerWithSignature(params) {
     try {
@@ -35439,7 +35531,12 @@ var PermissionsController = class {
    * Untrusts a server.
    *
    * @param params - Parameters for untrusting the server
+   * @param params.serverId - The server's Ethereum address to untrust
    * @returns Promise resolving to transaction hash
+   * @throws {Error} When wallet account is not available
+   * @throws {NonceError} When retrieving user nonce fails
+   * @throws {UserRejectedRequestError} When user rejects the transaction
+   * @throws {BlockchainError} When untrust transaction fails
    */
   async untrustServer(params) {
     const nonce = await this.getUserNonce();
@@ -35453,7 +35550,13 @@ var PermissionsController = class {
    * Untrusts a server using a signature (gasless transaction).
    *
    * @param params - Parameters for untrusting the server
+   * @param params.serverId - The server's Ethereum address to untrust
    * @returns Promise resolving to transaction hash
+   * @throws {Error} When wallet account is not available
+   * @throws {NonceError} When retrieving user nonce fails
+   * @throws {SignatureError} When user rejects the signature request
+   * @throws {RelayerError} When gasless submission fails
+   * @throws {BlockchainError} When untrust transaction fails
    */
   async untrustServerWithSignature(params) {
     try {
@@ -35495,6 +35598,7 @@ var PermissionsController = class {
    *
    * @param userAddress - Optional user address (defaults to current user)
    * @returns Promise resolving to array of trusted server addresses
+   * @throws {BlockchainError} When reading from contract fails or chain is unavailable
    */
   async getTrustedServers(userAddress) {
     try {
@@ -35524,6 +35628,7 @@ var PermissionsController = class {
    *
    * @param serverId - Server address
    * @returns Promise resolving to server information
+   * @throws {BlockchainError} When reading from contract fails or chain is unavailable
    */
   async getServerInfo(serverId) {
     try {
@@ -35552,6 +35657,7 @@ var PermissionsController = class {
    *
    * @param userAddress - Optional user address (defaults to current user)
    * @returns Promise resolving to the number of trusted servers
+   * @throws {BlockchainError} When reading from contract fails or chain is unavailable
    */
   async getTrustedServersCount(userAddress) {
     try {
@@ -35581,6 +35687,7 @@ var PermissionsController = class {
    *
    * @param options - Query options including pagination parameters
    * @returns Promise resolving to paginated trusted servers
+   * @throws {BlockchainError} When reading from contract fails or chain is unavailable
    */
   async getTrustedServersPaginated(options = {}) {
     try {
@@ -35640,6 +35747,7 @@ var PermissionsController = class {
    *
    * @param options - Query options
    * @returns Promise resolving to array of trusted server info
+   * @throws {BlockchainError} When reading from contract fails or chain is unavailable
    */
   async getTrustedServersWithInfo(options = {}) {
     try {
@@ -35677,6 +35785,7 @@ var PermissionsController = class {
    *
    * @param serverIds - Array of server IDs to query
    * @returns Promise resolving to batch result with successes and failures
+   * @throws {BlockchainError} When reading from contract fails or chain is unavailable
    */
   async getServerInfoBatch(serverIds) {
     if (serverIds.length === 0) {
@@ -36170,9 +36279,14 @@ var DataController = class {
    * @param file - The user file to decrypt (typically from getUserFiles)
    * @param encryptionSeed - Optional custom encryption seed (defaults to Vana standard)
    * @returns Promise resolving to the decrypted file content as a Blob
-   * @throws {Error} When the wallet is not connected
-   * @throws {Error} When fetching the encrypted content fails
-   * @throws {Error} When decryption fails (wrong key or corrupted data)
+   * @throws {Error} "No addresses available in wallet client" - When wallet is not connected
+   * @throws {Error} "Network error: Cannot access the file URL" - When file URL is inaccessible (CORS, server down)
+   * @throws {Error} "File not found: The encrypted file is no longer available" - When file returns 404
+   * @throws {Error} "Access denied" - When file returns 403 (no permission)
+   * @throws {Error} "File is empty or could not be retrieved" - When file has no content
+   * @throws {Error} "Invalid file format: This file doesn't appear to be encrypted with the Vana protocol" - When file is not properly encrypted
+   * @throws {Error} "Wrong encryption key" - When decryption fails due to incorrect key/seed
+   * @throws {Error} "Failed to decrypt file: {error}" - General decryption failures
    * @example
    * ```typescript
    * // Basic file decryption
@@ -36292,11 +36406,20 @@ var DataController = class {
    * This method queries the Vana subgraph to find files directly owned by the user.
    * It efficiently handles large datasets by using the File entity's owner field
    * and returns complete file metadata without additional contract calls.
+   *
+   * **Deduplication Behavior:**
+   * The method automatically deduplicates files by ID, keeping only the latest version
+   * (highest timestamp) when duplicate file IDs are found. This handles cases where
+   * the subgraph may contain multiple entries for the same file due to re-indexing
+   * or blockchain reorganizations.
    * @param params - The query parameters object
    * @param params.owner - The wallet address of the file owner to query
    * @param params.subgraphUrl - Optional subgraph URL to override the default endpoint
-   * @returns A Promise that resolves to an array of UserFile objects with metadata
-   * @throws {Error} When the subgraph is unavailable or returns invalid data
+   * @returns A Promise that resolves to an array of UserFile objects with metadata, sorted by latest timestamp first
+   * @throws {Error} When subgraphUrl is not provided and not configured - "subgraphUrl is required"
+   * @throws {Error} When subgraph request fails - "Subgraph request failed: {status} {statusText}"
+   * @throws {Error} When subgraph returns errors - "Subgraph errors: {error messages}"
+   * @throws {Error} When JSON parsing fails - "Failed to fetch user files from subgraph: {error}"
    * @example
    * ```typescript
    * // Query files for a specific user
@@ -36799,6 +36922,9 @@ var DataController = class {
    *
    * @param fileId - The file ID to look up
    * @returns Promise resolving to UserFile object
+   * @throws {Error} "Chain ID not available" - When wallet chain is not configured
+   * @throws {Error} "File not found" - When file ID doesn't exist or returns empty data
+   * @throws {Error} "Failed to fetch file {fileId}: {error}" - General contract read failures
    * @example
    * ```typescript
    * try {
@@ -36868,7 +36994,21 @@ var DataController = class {
   /**
    * Uploads an encrypted file to storage and registers it on the blockchain.
    *
-   * @deprecated Use vana.data.upload() instead for the high-level API with automatic encryption
+   * @deprecated Since v2.0.0 - Use vana.data.upload() instead for the high-level API with automatic encryption
+   *
+   * Migration guide:
+   * ```typescript
+   * // Old way (deprecated):
+   * const encrypted = await encryptBlob(data, key);
+   * const result = await vana.data.uploadEncryptedFile(encrypted, filename);
+   *
+   * // New way:
+   * const result = await vana.data.upload({
+   *   content: data,
+   *   filename: filename,
+   *   encrypt: true  // Handles encryption automatically
+   * });
+   * ```
    * @param encryptedFile - The encrypted file blob to upload
    * @param filename - Optional filename for the upload
    * @param providerName - Optional storage provider to use
@@ -36956,7 +37096,22 @@ var DataController = class {
   /**
    * Uploads an encrypted file to storage and registers it on the blockchain with a schema.
    *
-   * @deprecated Use vana.data.upload() instead for the high-level API with automatic encryption and schema validation
+   * @deprecated Since v2.0.0 - Use vana.data.upload() instead for the high-level API with automatic encryption and schema validation
+   *
+   * Migration guide:
+   * ```typescript
+   * // Old way (deprecated):
+   * const encrypted = await encryptBlob(data, key);
+   * const result = await vana.data.uploadEncryptedFileWithSchema(encrypted, schemaId, filename);
+   *
+   * // New way:
+   * const result = await vana.data.upload({
+   *   content: data,
+   *   filename: filename,
+   *   schemaId: schemaId,  // Automatic validation
+   *   encrypt: true
+   * });
+   * ```
    * @param encryptedFile - The encrypted file blob to upload
    * @param schemaId - The schema ID to associate with the file
    * @param filename - Optional filename for the upload
@@ -37232,7 +37387,24 @@ var DataController = class {
   /**
    * Adds a new schema to the DataRefinerRegistry.
    *
-   * @deprecated Use vana.schemas.create() instead for the high-level API with automatic IPFS upload
+   * @deprecated Since v2.0.0 - Use vana.schemas.create() instead for the high-level API with automatic IPFS upload
+   *
+   * Migration guide:
+   * ```typescript
+   * // Old way (deprecated):
+   * const result = await vana.data.addSchema({
+   *   name: "UserProfile",
+   *   type: "JSON",
+   *   definitionUrl: "ipfs://..."
+   * });
+   *
+   * // New way:
+   * const result = await vana.schemas.create({
+   *   name: "UserProfile",
+   *   type: "JSON",
+   *   definition: schemaObject  // Automatically uploads to IPFS
+   * });
+   * ```
    * @param params - Schema parameters including name, type, and definition URL
    * @returns Promise resolving to the new schema ID and transaction hash
    */
@@ -37291,7 +37463,16 @@ var DataController = class {
   /**
    * Retrieves a schema by its ID.
    *
-   * @deprecated Use vana.schemas.get() instead
+   * @deprecated Since v2.0.0 - Use vana.schemas.get() instead
+   *
+   * Migration guide:
+   * ```typescript
+   * // Old way (deprecated):
+   * const schema = await vana.data.getSchema(schemaId);
+   *
+   * // New way:
+   * const schema = await vana.schemas.get(schemaId);
+   * ```
    * @param schemaId - The schema ID to retrieve
    * @returns Promise resolving to the schema information
    */
@@ -37337,7 +37518,16 @@ var DataController = class {
   /**
    * Gets the total number of schemas in the registry.
    *
-   * @deprecated Use vana.schemas.count() instead
+   * @deprecated Since v2.0.0 - Use vana.schemas.count() instead
+   *
+   * Migration guide:
+   * ```typescript
+   * // Old way (deprecated):
+   * const count = await vana.data.getSchemasCount();
+   *
+   * // New way:
+   * const count = await vana.schemas.count();
+   * ```
    * @returns Promise resolving to the total schema count
    */
   async getSchemasCount() {
@@ -37659,8 +37849,11 @@ var DataController = class {
    *
    * @param fileId - The ID of the file to add permissions for
    * @param account - The address of the account to grant permission to
-   * @param publicKey - The public key to encrypt the user's encryption key with
+   * @param publicKey - The public key to encrypt the user's encryption key with (hex string with 0x prefix)
    * @returns Promise resolving to permission data from PermissionGranted event
+   * @throws {Error} "No addresses available in wallet client" - When wallet is not connected
+   * @throws {Error} "Chain ID not available" - When wallet chain is not configured
+   * @throws {Error} "Failed to add permission to file: {error}" - When transaction fails or user doesn't own file
    * @example
    * ```typescript
    * const result = await vana.data.addPermissionToFile(fileId, account, publicKey);
@@ -37813,7 +38006,9 @@ var DataController = class {
    *
    * @param url - The URL to fetch content from
    * @returns Promise resolving to the fetched content as a Blob
-   * @throws {Error} When the fetch fails or returns a non-ok response
+   * @throws {Error} "HTTP error! status: {status} {statusText}" - When server returns error status
+   * @throws {Error} "Empty response" - When server returns no content
+   * @throws {Error} "Network error: Failed to fetch from {url}" - When network request fails
    *
    * @example
    * ```typescript
@@ -37865,7 +38060,10 @@ var DataController = class {
    * @param options - Optional configuration
    * @param options.gateways - Array of IPFS gateway URLs to try (must end with /)
    * @returns Promise resolving to the fetched content as a Blob
-   * @throws {Error} When all gateways fail to fetch the content
+   * @throws {Error} "Invalid IPFS URL format" - When URL is not ipfs:// or valid CID
+   * @throws {Error} "Empty response" - When gateway returns no content
+   * @throws {Error} "HTTP error! status: {status}" - When gateway returns error status
+   * @throws {Error} "Failed to fetch IPFS content {cid} from all gateways" - When all gateways fail
    *
    * @example
    * ```typescript
@@ -38427,11 +38625,11 @@ var ServerController = class {
    * const identity = await vana.server.getIdentity({
    *   userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
    * });
-   * 
+   *
    * console.log(`Server: ${identity.name}`);
    * console.log(`Address: ${identity.address}`);
    * console.log(`Public Key: ${identity.public_key}`);
-   * 
+   *
    * // Use the public key for encrypting data to share with this server
    * const encryptedData = await encryptWithWalletPublicKey(
    *   userData,
@@ -38595,7 +38793,7 @@ var ServerController = class {
    * @remarks
    * This method attempts to cancel an operation that is currently processing
    * on the personal server. The operation must be in a cancellable state
-   * (typically `starting` or `processing`). Not all operations support 
+   * (typically `starting` or `processing`). Not all operations support
    * cancellation, and cancellation may not be immediate. The server will
    * attempt to stop the operation and update its status to `canceled`.
    *
@@ -38622,7 +38820,7 @@ var ServerController = class {
    * try {
    *   await vana.server.cancelOperation(operation.id);
    *   console.log("Cancellation requested");
-   *   
+   *
    *   // Verify cancellation
    *   const status = await vana.server.getOperation(operation.id);
    *   if (status.status === "canceled") {
@@ -39040,6 +39238,7 @@ var ProtocolController = class {
    * Gets the current chain ID from the wallet client.
    *
    * @returns The chain ID
+   * @throws {Error} When chain ID is not available from wallet client
    */
   getChainId() {
     const chainId = this.context.walletClient.chain?.id;
@@ -39052,6 +39251,7 @@ var ProtocolController = class {
    * Gets the current chain name from the wallet client.
    *
    * @returns The chain name
+   * @throws {Error} When chain name is not available from wallet client
    */
   getChainName() {
     const chainName = this.context.walletClient.chain?.name;