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

package/dist/types/personal.d.ts

@@ -1,38 +1,155 @@
 /**
- * Parameters for the `vana.personal.postRequest` method.
+ * Defines parameters for posting data requests to personal servers.
+ *
+ * @remarks
+ * Used to initiate data access requests that require user permission.
+ * The permission ID references a previously granted permission that
+ * authorizes the requester to access specific user data.
+ *
+ * @example
+ * ```typescript
+ * const params: PostRequestParams = {
+ *   permissionId: 123
+ * };
+ *
+ * const response = await vana.personal.postRequest(params);
+ * console.log('Request posted:', response.requestId);
+ * ```
+ *
+ * @category Personal Server
  */
 export interface PostRequestParams {
-    /** The permission ID */
+    /**
+     * References a granted permission authorizing data access.
+     * Obtain via permission granting flow or query existing permissions.
+     * @throws {PermissionNotFoundError} If permission ID is invalid.
+     */
     permissionId: number;
 }
 /**
- * Parameters for the `vana.server.createOperation` method.
+ * Defines parameters for creating server-side operations.
+ *
+ * @remarks
+ * Initiates asynchronous operations on the personal server that
+ * process user data according to granted permissions. Operations
+ * run in the background and can be monitored via their operation ID.
+ *
+ * @example
+ * ```typescript
+ * const params: CreateOperationParams = {
+ *   permissionId: 456
+ * };
+ *
+ * const operation = await vana.server.createOperation(params);
+ * // Monitor operation status
+ * const status = await vana.server.getOperationStatus(operation.id);
+ * ```
+ *
+ * @category Personal Server
  */
 export interface CreateOperationParams {
-    /** The permission ID */
+    /**
+     * References the permission scope for this operation.
+     * Determines what data and actions are allowed.
+     * @throws {InsufficientPermissionsError} If permission scope is inadequate.
+     */
     permissionId: number;
 }
 /**
- * Parameters for personal server operations.
+ * Defines parameters for initializing personal server connections.
+ *
+ * @remarks
+ * Establishes secure communication channels with a user's personal
+ * data server. The server manages encrypted user data and enforces
+ * permission-based access control. Initialization includes key exchange
+ * and session establishment.
+ *
+ * @example
+ * ```typescript
+ * const params: InitPersonalServerParams = {
+ *   userAddress: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36'
+ * };
+ *
+ * const server = await vana.personal.initServer(params);
+ * console.log('Connected to server:', server.baseUrl);
+ * ```
+ *
+ * @category Personal Server
  */
 export interface InitPersonalServerParams {
-    /** The user's wallet address */
+    /**
+     * Identifies the user whose personal server to connect to.
+     * Must be a valid Ethereum address in hex format.
+     * @example '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36'
+     */
     userAddress: string;
 }
 /**
- * Extended personal server identity information including connection details.
- * This combines the base PersonalServerModel with additional metadata
- * needed for client connections.
+ * Represents comprehensive personal server identity and connection information.
+ *
+ * @remarks
+ * Combines core server identity with connection metadata required for
+ * establishing secure communication. Personal servers are user-controlled
+ * nodes that store and serve encrypted personal data according to
+ * user-defined permissions. This interface provides all necessary
+ * information to connect to and interact with a personal server.
+ *
+ * @example
+ * ```typescript
+ * const identity: PersonalServerIdentity = {
+ *   kind: 'PersonalServer',
+ *   address: '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36',
+ *   publicKey: '0x04...', // 65-byte uncompressed public key
+ *   baseUrl: 'https://ps.user.vana.com',
+ *   name: 'User Personal Server #1'
+ * };
+ *
+ * // Use identity to establish encrypted connection
+ * const encrypted = await crypto.encrypt(data, identity.publicKey);
+ * const response = await fetch(`${identity.baseUrl}/api/data`, {
+ *   method: 'POST',
+ *   body: encrypted
+ * });
+ * ```
+ *
+ * @category Personal Server
  */
 export interface PersonalServerIdentity {
-    /** Resource type identifier */
+    /**
+     * Identifies the resource type for API disambiguation.
+     * Always 'PersonalServer' for personal server instances.
+     */
     kind: string;
-    /** The server's Ethereum address */
+    /**
+     * Uniquely identifies the server on the blockchain.
+     * Used for permission verification and identity proofs.
+     * @example '0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36'
+     */
     address: string;
-    /** The server's public key for encryption */
+    /**
+     * Enables end-to-end encryption for data transmission.
+     * Must be in uncompressed format (65 bytes with 0x04 prefix).
+     * @example '0x04...' (130 hex characters)
+     */
     publicKey: string;
-    /** The base URL for connecting to this server */
+    /**
+     * Provides the HTTPS endpoint for server API requests.
+     * Should not include trailing slashes or API paths.
+     * @example 'https://ps.user.vana.com'
+     */
     baseUrl: string;
-    /** Human-readable name for this server */
+    /**
+     * Displays a user-friendly identifier for the server.
+     * Used in UI components and logging for clarity.
+     * @example 'Primary Data Server'
+     */
     name: string;
 }
+/**
+ * @remarks
+ * Additional server response types are auto-generated from the OpenAPI
+ * specification and available in the server-exports module. Import those
+ * types directly when working with server API responses.
+ *
+ * @see {@link ../types/server-exports | Server Export Types}
+ */

package/dist/types/relayer.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/relayer.ts"],"sourcesContent":["import type { Hash, Address } from \"viem\";\nimport type {\n  GrantFile,\n  PermissionGrantTypedData,\n  GenericTypedData,\n} from \"./permissions\";\n\n/**\n * Response from the relayer service for grant file storage\n *\n * @category Advanced\n */\nexport interface RelayerStorageResponse {\n  /** The IPFS URL where the grant file is stored */\n  grantUrl: string;\n  /** Success status */\n  success: boolean;\n  /** Optional error message */\n  error?: string;\n  /** Storage metadata */\n  metadata?: {\n    /** IPFS hash */\n    ipfsHash: string;\n    /** File size in bytes */\n    size: number;\n    /** Upload timestamp */\n    timestamp: number;\n  };\n}\n\n/**\n * Response from the relayer service for transaction submission\n *\n * @category Advanced\n */\nexport interface RelayerTransactionResponse {\n  /** The transaction hash of the submitted transaction */\n  transactionHash: Hash;\n  /** Success status */\n  success: boolean;\n  /** Optional error message */\n  error?: string;\n  /** Transaction metadata */\n  metadata?: {\n    /** Gas used */\n    gasUsed?: bigint;\n    /** Gas price */\n    gasPrice?: bigint;\n    /** Block number */\n    blockNumber?: bigint;\n    /** Transaction status */\n    status?: \"pending\" | \"confirmed\" | \"failed\";\n  };\n}\n\n/**\n * Parameters for storing a grant file via relayer\n *\n * @category Advanced\n */\nexport interface RelayerStoreParams {\n  /** The grant file to store */\n  grantFile: GrantFile;\n  /** Optional storage options */\n  options?: {\n    /** IPFS pin duration in seconds */\n    pinDuration?: number;\n    /** Whether to use encryption */\n    encrypt?: boolean;\n    /** Custom metadata */\n    metadata?: Record<string, unknown>;\n  };\n}\n\n/**\n * Parameters for submitting a transaction via relayer\n *\n * @category Advanced\n */\nexport interface RelayerSubmitParams {\n  /** The signed typed data */\n  typedData: PermissionGrantTypedData;\n  /** The signature */\n  signature: string;\n  /** Optional transaction options */\n  options?: {\n    /** Gas limit */\n    gasLimit?: bigint;\n    /** Priority level */\n    priority?: \"low\" | \"medium\" | \"high\";\n    /** Whether to wait for confirmation */\n    waitForConfirmation?: boolean;\n  };\n}\n\n/**\n * Relayer service status\n *\n * @category Advanced\n */\nexport interface RelayerStatus {\n  /** Whether the relayer is online */\n  online: boolean;\n  /** Service version */\n  version: string;\n  /** Supported chains */\n  supportedChains: number[];\n  /** Current chain status */\n  chainStatus: Record<\n    number,\n    {\n      /** Whether the chain is supported */\n      supported: boolean;\n      /** Current block number */\n      currentBlock: bigint;\n      /** Gas price estimation */\n      gasPrice: bigint;\n      /** Queue size */\n      queueSize: number;\n    }\n  >;\n  /** Rate limit information */\n  rateLimits: {\n    /** Requests per minute */\n    requestsPerMinute: number;\n    /** Storage requests per hour */\n    storageRequestsPerHour: number;\n    /** Transaction requests per hour */\n    transactionRequestsPerHour: number;\n  };\n}\n\n/**\n * Relayer request options\n *\n * @category Advanced\n */\nexport interface RelayerRequestOptions {\n  /** Request timeout in milliseconds */\n  timeout?: number;\n  /** Whether to retry on failure */\n  retry?: boolean;\n  /** Custom headers */\n  headers?: Record<string, string>;\n  /** Request priority */\n  priority?: \"low\" | \"medium\" | \"high\";\n}\n\n/**\n * Relayer error response\n *\n * @category Advanced\n */\nexport interface RelayerErrorResponse {\n  /** Error code */\n  code: string;\n  /** Error message */\n  message: string;\n  /** Additional error details */\n  details?: Record<string, unknown>;\n  /** Request ID for debugging */\n  requestId?: string;\n  /** Timestamp of error */\n  timestamp: number;\n}\n\n/**\n * Relayer queue information\n *\n * @category Advanced\n */\nexport interface RelayerQueueInfo {\n  /** Current queue size */\n  size: number;\n  /** Estimated processing time in seconds */\n  estimatedProcessingTime: number;\n  /** Queue position for a specific request */\n  position?: number;\n  /** Processing statistics */\n  stats: {\n    /** Average processing time in seconds */\n    averageProcessingTime: number;\n    /** Requests processed in last hour */\n    requestsProcessedHour: number;\n    /** Success rate percentage */\n    successRate: number;\n  };\n}\n\n/**\n * Relayer transaction status\n *\n * @category Advanced\n */\nexport interface RelayerTransactionStatus {\n  /** Transaction hash */\n  transactionHash: Hash;\n  /** Current status */\n  status: \"pending\" | \"confirmed\" | \"failed\";\n  /** Block number if confirmed */\n  blockNumber?: bigint;\n  /** Gas used */\n  gasUsed?: bigint;\n  /** Error message if failed */\n  error?: string;\n  /** Status checks performed */\n  checks: Array<{\n    /** Check timestamp */\n    timestamp: number;\n    /** Status at time of check */\n    status: string;\n    /** Block number at time of check */\n    blockNumber: bigint;\n  }>;\n}\n\n/**\n * Relayer metrics\n *\n * @category Advanced\n */\nexport interface RelayerMetrics {\n  /** Total transactions processed */\n  totalTransactions: number;\n  /** Successful transactions */\n  successfulTransactions: number;\n  /** Failed transactions */\n  failedTransactions: number;\n  /** Average processing time in seconds */\n  averageProcessingTime: number;\n  /** Current queue size */\n  queueSize: number;\n  /** Uptime percentage */\n  uptime: number;\n  /** Last 24 hour statistics */\n  last24Hours: {\n    /** Transactions processed */\n    transactions: number;\n    /** Success rate */\n    successRate: number;\n    /** Average response time */\n    averageResponseTime: number;\n  };\n}\n\n/**\n * Relayer webhook configuration\n *\n * @category Advanced\n */\nexport interface RelayerWebhookConfig {\n  /** Webhook URL */\n  url: string;\n  /** Events to subscribe to */\n  events: Array<\n    \"transaction_confirmed\" | \"transaction_failed\" | \"storage_complete\"\n  >;\n  /** Webhook secret for signature verification */\n  secret?: string;\n  /** Whether webhook is active */\n  active: boolean;\n}\n\n/**\n * Relayer webhook payload\n *\n * @category Advanced\n */\nexport interface RelayerWebhookPayload {\n  /** Event type */\n  event: string;\n  /** Event data */\n  data: Record<string, unknown>;\n  /** Timestamp */\n  timestamp: number;\n  /** Webhook ID */\n  webhookId: string;\n  /** Signature for verification */\n  signature: string;\n}\n\n// ===== NEW SIMPLIFIED RELAYER TYPES (v2) =====\n\n/**\n * Handles both EIP-712 signed operations and direct server operations through a single interface.\n *\n * @remarks\n * This discriminated union provides type safety through TypeScript's narrowing.\n * The `type` field determines which operation variant is being used.\n * Signed operations require blockchain transactions, while direct operations\n * handle auxiliary tasks like file storage.\n *\n * @category Relayer\n * @see {@link https://docs.vana.org/docs/gasless-transactions | Gasless Transactions Guide}\n */\nexport type UnifiedRelayerRequest = SignedRelayerRequest | DirectRelayerRequest;\n\n/**\n * Represents an EIP-712 signed operation for gasless transaction submission.\n *\n * @remarks\n * Signed requests contain typed data and signatures that are verified\n * on-chain by smart contracts. The relayer pays gas fees on behalf of users.\n *\n * @category Relayer\n */\nexport interface SignedRelayerRequest {\n  /** Discriminator field identifying this as a signed operation */\n  type: \"signed\";\n  /** Operation identifier for routing (e.g., 'submitAddPermission') */\n  operation: SignedOperationType;\n  /** EIP-712 typed data structure for the operation */\n  typedData: GenericTypedData;\n  /** User's signature of the typed data */\n  signature: Hash;\n  /** Optional address for additional signer verification */\n  expectedUserAddress?: Address;\n}\n\n/**\n * Supported signed operation types.\n * @category Relayer\n */\nexport type SignedOperationType =\n  | \"submitAddPermission\"\n  | \"submitPermissionRevoke\"\n  | \"submitTrustServer\"\n  | \"submitAddAndTrustServer\"\n  | \"submitUntrustServer\"\n  | \"submitAddServerFilesAndPermissions\"\n  | \"submitRegisterGrantee\";\n\n/**\n * Represents direct server operations that don't require blockchain signatures.\n *\n * @remarks\n * Direct requests handle auxiliary operations like file uploads and grant storage.\n * These operations may still result in blockchain transactions but don't require\n * user signatures for gasless submission.\n *\n * @category Relayer\n */\nexport type DirectRelayerRequest =\n  | {\n      type: \"direct\";\n      operation: \"submitFileAddition\";\n      params: {\n        url: string;\n        userAddress: Address;\n      };\n    }\n  | {\n      type: \"direct\";\n      operation: \"submitFileAdditionWithPermissions\";\n      params: {\n        url: string;\n        userAddress: Address;\n        permissions: Array<{ account: Address; key: string }>;\n      };\n    }\n  | {\n      type: \"direct\";\n      operation: \"submitFileAdditionComplete\";\n      params: {\n        url: string;\n        userAddress: Address;\n        permissions: Array<{ account: Address; key: string }>;\n        schemaId: number;\n        ownerAddress?: Address;\n      };\n    }\n  | {\n      type: \"direct\";\n      operation: \"storeGrantFile\";\n      params: GrantFile;\n    };\n\n/**\n * Provides type-safe responses for all relayer operations.\n *\n * @remarks\n * The discriminated union ensures proper error handling and result typing.\n * Check the `type` field to determine success or failure before accessing results.\n *\n * @category Relayer\n */\nexport type UnifiedRelayerResponse =\n  | {\n      type: \"signed\";\n      hash: Hash;\n    }\n  | {\n      type: \"direct\";\n      result: { fileId: number; transactionHash: Hash } | { url: string } | any;\n    }\n  | {\n      type: \"error\";\n      error: string;\n    };\n\n/**\n * Simplified relayer configuration.\n * Can be a URL string for convenience, or a callback for full control.\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Option 1: Simple URL (SDK handles the transport)\n * const vana = Vana({\n *   walletClient,\n *   relayer: '/api/relay'\n * });\n *\n * // Option 2: Full control with callback\n * const vana = Vana({\n *   walletClient,\n *   relayer: async (request) => {\n *     const response = await fetch('/api/relay', {\n *       method: 'POST',\n *       body: JSON.stringify(request)\n *     });\n *     return response.json();\n *   }\n * });\n * ```\n */\nexport type RelayerConfig =\n  | string\n  | ((request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>);\n\n/**\n * Simplified relayer callbacks interface (v2).\n * A single callback handles all relayer operations.\n *\n * @category Configuration\n * @example\n * ```typescript\n * const relayerCallbacks: RelayerCallbacksV2 = {\n *   submit: async (request) => {\n *     // Send to your server endpoint\n *     const response = await fetch('/api/relay', {\n *       method: 'POST',\n *       headers: { 'Content-Type': 'application/json' },\n *       body: JSON.stringify(request)\n *     });\n *     return response.json();\n *   }\n * };\n * ```\n */\nexport interface RelayerCallbacksV2 {\n  /**\n   * Submit any relayer operation.\n   *\n   * This single callback handles all operations:\n   * - EIP-712 signed operations (permissions, server trust, etc.)\n   * - Direct operations (file additions, grant storage)\n   *\n   * On your server, pass the entire request object to the SDK's\n   * `handleRelayerOperation` helper function.\n   *\n   * @param request - The unified request object\n   * @returns Promise resolving to operation-specific response\n   */\n  submit: (request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/types/relayer.ts"],"sourcesContent":["/**\n * Defines types for gasless transaction relayers and server operations.\n *\n * @remarks\n * This module provides comprehensive type definitions for interacting with\n * relayer services that enable gasless transactions and auxiliary operations.\n * It includes both legacy v1 types and the simplified v2 unified interface.\n *\n * @category Types\n * @module types/relayer\n */\n\nimport type { Hash, Address, TransactionReceipt } from \"viem\";\nimport type {\n  GrantFile,\n  PermissionGrantTypedData,\n  GenericTypedData,\n} from \"./permissions\";\n\n/**\n * Represents the response from storing grant files via relayer.\n *\n * @remarks\n * Contains storage location, metadata, and error information for\n * grant file upload operations.\n *\n * @category Advanced\n */\nexport interface RelayerStorageResponse {\n  /** The IPFS URL where the grant file is stored */\n  grantUrl: string;\n  /** Success status */\n  success: boolean;\n  /** Optional error message */\n  error?: string;\n  /** Storage metadata */\n  metadata?: {\n    /** IPFS hash */\n    ipfsHash: string;\n    /** File size in bytes */\n    size: number;\n    /** Upload timestamp */\n    timestamp: number;\n  };\n}\n\n/**\n * Represents the response from submitting transactions via relayer.\n *\n * @remarks\n * Contains transaction hash, status, and metadata for gasless\n * transaction submissions.\n *\n * @category Advanced\n */\nexport interface RelayerTransactionResponse {\n  /** The transaction hash of the submitted transaction */\n  transactionHash: Hash;\n  /** Success status */\n  success: boolean;\n  /** Optional error message */\n  error?: string;\n  /** Transaction metadata */\n  metadata?: {\n    /** Gas used */\n    gasUsed?: bigint;\n    /** Gas price */\n    gasPrice?: bigint;\n    /** Block number */\n    blockNumber?: bigint;\n    /** Transaction status */\n    status?: \"pending\" | \"confirmed\" | \"failed\";\n  };\n}\n\n/**\n * Specifies parameters for storing grant files via relayer.\n *\n * @remarks\n * Includes the grant file and optional storage configuration\n * such as encryption and pinning duration.\n *\n * @category Advanced\n */\nexport interface RelayerStoreParams {\n  /** The grant file to store */\n  grantFile: GrantFile;\n  /** Optional storage options */\n  options?: {\n    /** IPFS pin duration in seconds */\n    pinDuration?: number;\n    /** Whether to use encryption */\n    encrypt?: boolean;\n    /** Custom metadata */\n    metadata?: Record<string, unknown>;\n  };\n}\n\n/**\n * Specifies parameters for submitting gasless transactions.\n *\n * @remarks\n * Contains signed typed data and transaction configuration options\n * for relayer submission.\n *\n * @category Advanced\n */\nexport interface RelayerSubmitParams {\n  /** The signed typed data */\n  typedData: PermissionGrantTypedData;\n  /** The signature */\n  signature: string;\n  /** Optional transaction options */\n  options?: {\n    /** Gas limit */\n    gasLimit?: bigint;\n    /** Priority level */\n    priority?: \"low\" | \"medium\" | \"high\";\n    /** Whether to wait for confirmation */\n    waitForConfirmation?: boolean;\n  };\n}\n\n/**\n * Represents the current status and capabilities of a relayer service.\n *\n * @remarks\n * Provides information about supported chains, rate limits, and\n * current operational status for monitoring and decision-making.\n *\n * @category Advanced\n */\nexport interface RelayerStatus {\n  /** Whether the relayer is online */\n  online: boolean;\n  /** Service version */\n  version: string;\n  /** Supported chains */\n  supportedChains: number[];\n  /** Current chain status */\n  chainStatus: Record<\n    number,\n    {\n      /** Whether the chain is supported */\n      supported: boolean;\n      /** Current block number */\n      currentBlock: bigint;\n      /** Gas price estimation */\n      gasPrice: bigint;\n      /** Queue size */\n      queueSize: number;\n    }\n  >;\n  /** Rate limit information */\n  rateLimits: {\n    /** Requests per minute */\n    requestsPerMinute: number;\n    /** Storage requests per hour */\n    storageRequestsPerHour: number;\n    /** Transaction requests per hour */\n    transactionRequestsPerHour: number;\n  };\n}\n\n/**\n * Configures behavior for relayer requests.\n *\n * @remarks\n * Controls timeout, retry logic, headers, and priority for\n * relayer operation requests.\n *\n * @category Advanced\n */\nexport interface RelayerRequestOptions {\n  /** Request timeout in milliseconds */\n  timeout?: number;\n  /** Whether to retry on failure */\n  retry?: boolean;\n  /** Custom headers */\n  headers?: Record<string, string>;\n  /** Request priority */\n  priority?: \"low\" | \"medium\" | \"high\";\n}\n\n/**\n * Represents an error response from the relayer service.\n *\n * @remarks\n * Provides structured error information including codes, messages,\n * and debugging details for error handling and recovery.\n *\n * @category Advanced\n */\nexport interface RelayerErrorResponse {\n  /** Error code */\n  code: string;\n  /** Error message */\n  message: string;\n  /** Additional error details */\n  details?: Record<string, unknown>;\n  /** Request ID for debugging */\n  requestId?: string;\n  /** Timestamp of error */\n  timestamp: number;\n}\n\n/**\n * Provides information about the relayer's processing queue.\n *\n * @remarks\n * Includes queue size, position, estimated processing time, and\n * performance statistics for queue monitoring.\n *\n * @category Advanced\n */\nexport interface RelayerQueueInfo {\n  /** Current queue size */\n  size: number;\n  /** Estimated processing time in seconds */\n  estimatedProcessingTime: number;\n  /** Queue position for a specific request */\n  position?: number;\n  /** Processing statistics */\n  stats: {\n    /** Average processing time in seconds */\n    averageProcessingTime: number;\n    /** Requests processed in last hour */\n    requestsProcessedHour: number;\n    /** Success rate percentage */\n    successRate: number;\n  };\n}\n\n/**\n * Tracks the status of a transaction submitted via relayer.\n *\n * @remarks\n * Provides detailed tracking information including confirmation status,\n * gas usage, and historical status checks.\n *\n * @category Advanced\n */\nexport interface RelayerTransactionStatus {\n  /** Transaction hash */\n  transactionHash: Hash;\n  /** Current status */\n  status: \"pending\" | \"confirmed\" | \"failed\";\n  /** Block number if confirmed */\n  blockNumber?: bigint;\n  /** Gas used */\n  gasUsed?: bigint;\n  /** Error message if failed */\n  error?: string;\n  /** Status checks performed */\n  checks: Array<{\n    /** Check timestamp */\n    timestamp: number;\n    /** Status at time of check */\n    status: string;\n    /** Block number at time of check */\n    blockNumber: bigint;\n  }>;\n}\n\n/**\n * Provides performance metrics for the relayer service.\n *\n * @remarks\n * Includes transaction statistics, success rates, processing times,\n * and uptime information for monitoring and optimization.\n *\n * @category Advanced\n */\nexport interface RelayerMetrics {\n  /** Total transactions processed */\n  totalTransactions: number;\n  /** Successful transactions */\n  successfulTransactions: number;\n  /** Failed transactions */\n  failedTransactions: number;\n  /** Average processing time in seconds */\n  averageProcessingTime: number;\n  /** Current queue size */\n  queueSize: number;\n  /** Uptime percentage */\n  uptime: number;\n  /** Last 24 hour statistics */\n  last24Hours: {\n    /** Transactions processed */\n    transactions: number;\n    /** Success rate */\n    successRate: number;\n    /** Average response time */\n    averageResponseTime: number;\n  };\n}\n\n/**\n * Configures webhook notifications for relayer events.\n *\n * @remarks\n * Enables asynchronous notifications for transaction confirmations,\n * failures, and storage completions.\n *\n * @category Advanced\n */\nexport interface RelayerWebhookConfig {\n  /** Webhook URL */\n  url: string;\n  /** Events to subscribe to */\n  events: Array<\n    \"transaction_confirmed\" | \"transaction_failed\" | \"storage_complete\"\n  >;\n  /** Webhook secret for signature verification */\n  secret?: string;\n  /** Whether webhook is active */\n  active: boolean;\n}\n\n/**\n * Represents a webhook event payload from the relayer.\n *\n * @remarks\n * Contains event data, timestamp, and signature for verification\n * of webhook authenticity.\n *\n * @category Advanced\n */\nexport interface RelayerWebhookPayload {\n  /** Event type */\n  event: string;\n  /** Event data */\n  data: Record<string, unknown>;\n  /** Timestamp */\n  timestamp: number;\n  /** Webhook ID */\n  webhookId: string;\n  /** Signature for verification */\n  signature: string;\n}\n\n// ===== NEW SIMPLIFIED RELAYER TYPES (v2) =====\n\n/**\n * Handles both EIP-712 signed operations and direct server operations through a single interface.\n *\n * @remarks\n * This discriminated union provides type safety through TypeScript's narrowing.\n * The `type` field determines which operation variant is being used.\n * Signed operations require blockchain transactions, while direct operations\n * handle auxiliary tasks like file storage.\n *\n * @category Relayer\n * @see {@link https://docs.vana.org/docs/gasless-transactions | Gasless Transactions Guide}\n */\nexport type UnifiedRelayerRequest =\n  | SignedRelayerRequest\n  | DirectRelayerRequest\n  | {\n      type: \"status_check\";\n      operationId: string;\n    };\n\n/**\n * Represents an EIP-712 signed operation for gasless transaction submission.\n *\n * @remarks\n * Signed requests contain typed data and signatures that are verified\n * on-chain by smart contracts. The relayer pays gas fees on behalf of users.\n *\n * @category Relayer\n */\nexport interface SignedRelayerRequest {\n  /** Discriminator field identifying this as a signed operation */\n  type: \"signed\";\n  /** Operation identifier for routing (e.g., 'submitAddPermission') */\n  operation: SignedOperationType;\n  /** EIP-712 typed data structure for the operation */\n  typedData: GenericTypedData;\n  /** User's signature of the typed data */\n  signature: Hash;\n  /** Optional address for additional signer verification */\n  expectedUserAddress?: Address;\n}\n\n/**\n * Enumerates supported EIP-712 signed operation types.\n *\n * @remarks\n * Each operation type corresponds to a specific smart contract\n * function that accepts gasless transactions.\n *\n * @category Relayer\n */\nexport type SignedOperationType =\n  | \"submitAddPermission\"\n  | \"submitPermissionRevoke\"\n  | \"submitTrustServer\"\n  | \"submitAddAndTrustServer\"\n  | \"submitUntrustServer\"\n  | \"submitAddServerFilesAndPermissions\"\n  | \"submitRegisterGrantee\";\n\n/**\n * Represents direct server operations that don't require blockchain signatures.\n *\n * @remarks\n * Direct requests handle auxiliary operations like file uploads and grant storage.\n * These operations may still result in blockchain transactions but don't require\n * user signatures for gasless submission.\n *\n * @category Relayer\n */\nexport type DirectRelayerRequest =\n  | {\n      type: \"direct\";\n      operation: \"submitFileAddition\";\n      params: {\n        url: string;\n        userAddress: Address;\n      };\n    }\n  | {\n      type: \"direct\";\n      operation: \"submitFileAdditionWithPermissions\";\n      params: {\n        url: string;\n        userAddress: Address;\n        permissions: Array<{ account: Address; key: string }>;\n      };\n    }\n  | {\n      type: \"direct\";\n      operation: \"submitFileAdditionComplete\";\n      params: {\n        url: string;\n        userAddress: Address;\n        permissions: Array<{ account: Address; key: string }>;\n        schemaId: number;\n        ownerAddress?: Address;\n      };\n    }\n  | {\n      type: \"direct\";\n      operation: \"storeGrantFile\";\n      params: GrantFile;\n    };\n\n/**\n * Provides type-safe responses for all relayer operations.\n *\n * @remarks\n * The discriminated union ensures proper error handling and result typing.\n * Check the `type` field to determine success or failure before accessing results.\n * The new async pattern returns pending operations with operationIds for polling.\n *\n * @category Relayer\n */\nexport type UnifiedRelayerResponse =\n  | {\n      type: \"pending\";\n      operationId: string;\n    }\n  | {\n      type: \"submitted\";\n      hash: Hash;\n    }\n  | {\n      type: \"confirmed\";\n      hash: Hash;\n      // Receipt is optional; a performance hint for the client SDK's polling logic.\n      receipt?: TransactionReceipt;\n    }\n  | {\n      type: \"signed\";\n      hash: Hash;\n    }\n  | {\n      type: \"direct\";\n      result: { fileId: number; transactionHash: Hash } | { url: string };\n    }\n  | {\n      /** Non-transactional operations that don't require tracking (e.g., IPFS uploads) */\n      type: \"direct_result_untracked\";\n      /** The result data from the operation, structure depends on the specific operation */\n      result: unknown;\n    }\n  | {\n      type: \"error\";\n      error: string;\n    };\n\n/**\n * Simplified relayer configuration.\n * Can be a URL string for convenience, or a callback for full control.\n *\n * @category Configuration\n * @example\n * ```typescript\n * // Option 1: Simple URL (SDK handles the transport)\n * const vana = Vana({\n *   walletClient,\n *   relayer: '/api/relay'\n * });\n *\n * // Option 2: Full control with callback\n * const vana = Vana({\n *   walletClient,\n *   relayer: async (request) => {\n *     const response = await fetch('/api/relay', {\n *       method: 'POST',\n *       body: JSON.stringify(request)\n *     });\n *     return response.json();\n *   }\n * });\n * ```\n */\nexport type RelayerConfig =\n  | string\n  | ((request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>);\n\n/**\n * Simplified relayer callbacks interface (v2).\n * A single callback handles all relayer operations.\n *\n * @category Configuration\n * @example\n * ```typescript\n * const relayerCallbacks: RelayerCallbacksV2 = {\n *   submit: async (request) => {\n *     // Send to your server endpoint\n *     const response = await fetch('/api/relay', {\n *       method: 'POST',\n *       headers: { 'Content-Type': 'application/json' },\n *       body: JSON.stringify(request)\n *     });\n *     return response.json();\n *   }\n * };\n * ```\n */\nexport interface RelayerCallbacksV2 {\n  /**\n   * Submits any relayer operation to the server.\n   *\n   * @remarks\n   * This single callback handles all operations:\n   * - EIP-712 signed operations (permissions, server trust, etc.)\n   * - Direct operations (file additions, grant storage)\n   *\n   * On your server, pass the entire request object to the SDK's\n   * `handleRelayerOperation` helper function.\n   *\n   * @param request - The unified request object.\n   *   Check `type` field to determine operation variant.\n   * @returns Promise resolving to operation-specific response\n   *\n   * @example\n   * ```typescript\n   * async submit(request) {\n   *   const response = await fetch('/api/relay', {\n   *     method: 'POST',\n   *     body: JSON.stringify(request)\n   *   });\n   *   return response.json();\n   * }\n   * ```\n   */\n  submit: (request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types/relayer.d.ts

@@ -1,7 +1,22 @@
-import type { Hash, Address } from "viem";
+/**
+ * Defines types for gasless transaction relayers and server operations.
+ *
+ * @remarks
+ * This module provides comprehensive type definitions for interacting with
+ * relayer services that enable gasless transactions and auxiliary operations.
+ * It includes both legacy v1 types and the simplified v2 unified interface.
+ *
+ * @category Types
+ * @module types/relayer
+ */
+import type { Hash, Address, TransactionReceipt } from "viem";
 import type { GrantFile, PermissionGrantTypedData, GenericTypedData } from "./permissions";
 /**
- * Response from the relayer service for grant file storage
+ * Represents the response from storing grant files via relayer.
+ *
+ * @remarks
+ * Contains storage location, metadata, and error information for
+ * grant file upload operations.
  *
  * @category Advanced
  */
@@ -23,7 +38,11 @@ export interface RelayerStorageResponse {
     };
 }
 /**
- * Response from the relayer service for transaction submission
+ * Represents the response from submitting transactions via relayer.
+ *
+ * @remarks
+ * Contains transaction hash, status, and metadata for gasless
+ * transaction submissions.
  *
  * @category Advanced
  */
@@ -47,7 +66,11 @@ export interface RelayerTransactionResponse {
     };
 }
 /**
- * Parameters for storing a grant file via relayer
+ * Specifies parameters for storing grant files via relayer.
+ *
+ * @remarks
+ * Includes the grant file and optional storage configuration
+ * such as encryption and pinning duration.
  *
  * @category Advanced
  */
@@ -65,7 +88,11 @@ export interface RelayerStoreParams {
     };
 }
 /**
- * Parameters for submitting a transaction via relayer
+ * Specifies parameters for submitting gasless transactions.
+ *
+ * @remarks
+ * Contains signed typed data and transaction configuration options
+ * for relayer submission.
  *
  * @category Advanced
  */
@@ -85,7 +112,11 @@ export interface RelayerSubmitParams {
     };
 }
 /**
- * Relayer service status
+ * Represents the current status and capabilities of a relayer service.
+ *
+ * @remarks
+ * Provides information about supported chains, rate limits, and
+ * current operational status for monitoring and decision-making.
  *
  * @category Advanced
  */
@@ -118,7 +149,11 @@ export interface RelayerStatus {
     };
 }
 /**
- * Relayer request options
+ * Configures behavior for relayer requests.
+ *
+ * @remarks
+ * Controls timeout, retry logic, headers, and priority for
+ * relayer operation requests.
  *
  * @category Advanced
  */
@@ -133,7 +168,11 @@ export interface RelayerRequestOptions {
     priority?: "low" | "medium" | "high";
 }
 /**
- * Relayer error response
+ * Represents an error response from the relayer service.
+ *
+ * @remarks
+ * Provides structured error information including codes, messages,
+ * and debugging details for error handling and recovery.
  *
  * @category Advanced
  */
@@ -150,7 +189,11 @@ export interface RelayerErrorResponse {
     timestamp: number;
 }
 /**
- * Relayer queue information
+ * Provides information about the relayer's processing queue.
+ *
+ * @remarks
+ * Includes queue size, position, estimated processing time, and
+ * performance statistics for queue monitoring.
  *
  * @category Advanced
  */
@@ -172,7 +215,11 @@ export interface RelayerQueueInfo {
     };
 }
 /**
- * Relayer transaction status
+ * Tracks the status of a transaction submitted via relayer.
+ *
+ * @remarks
+ * Provides detailed tracking information including confirmation status,
+ * gas usage, and historical status checks.
  *
  * @category Advanced
  */
@@ -198,7 +245,11 @@ export interface RelayerTransactionStatus {
     }>;
 }
 /**
- * Relayer metrics
+ * Provides performance metrics for the relayer service.
+ *
+ * @remarks
+ * Includes transaction statistics, success rates, processing times,
+ * and uptime information for monitoring and optimization.
  *
  * @category Advanced
  */
@@ -226,7 +277,11 @@ export interface RelayerMetrics {
     };
 }
 /**
- * Relayer webhook configuration
+ * Configures webhook notifications for relayer events.
+ *
+ * @remarks
+ * Enables asynchronous notifications for transaction confirmations,
+ * failures, and storage completions.
  *
  * @category Advanced
  */
@@ -241,7 +296,11 @@ export interface RelayerWebhookConfig {
     active: boolean;
 }
 /**
- * Relayer webhook payload
+ * Represents a webhook event payload from the relayer.
+ *
+ * @remarks
+ * Contains event data, timestamp, and signature for verification
+ * of webhook authenticity.
  *
  * @category Advanced
  */
@@ -269,7 +328,10 @@ export interface RelayerWebhookPayload {
  * @category Relayer
  * @see {@link https://docs.vana.org/docs/gasless-transactions | Gasless Transactions Guide}
  */
-export type UnifiedRelayerRequest = SignedRelayerRequest | DirectRelayerRequest;
+export type UnifiedRelayerRequest = SignedRelayerRequest | DirectRelayerRequest | {
+    type: "status_check";
+    operationId: string;
+};
 /**
  * Represents an EIP-712 signed operation for gasless transaction submission.
  *
@@ -292,7 +354,12 @@ export interface SignedRelayerRequest {
     expectedUserAddress?: Address;
 }
 /**
- * Supported signed operation types.
+ * Enumerates supported EIP-712 signed operation types.
+ *
+ * @remarks
+ * Each operation type corresponds to a specific smart contract
+ * function that accepts gasless transactions.
+ *
  * @category Relayer
  */
 export type SignedOperationType = "submitAddPermission" | "submitPermissionRevoke" | "submitTrustServer" | "submitAddAndTrustServer" | "submitUntrustServer" | "submitAddServerFilesAndPermissions" | "submitRegisterGrantee";
@@ -348,10 +415,21 @@ export type DirectRelayerRequest = {
  * @remarks
  * The discriminated union ensures proper error handling and result typing.
  * Check the `type` field to determine success or failure before accessing results.
+ * The new async pattern returns pending operations with operationIds for polling.
  *
  * @category Relayer
  */
 export type UnifiedRelayerResponse = {
+    type: "pending";
+    operationId: string;
+} | {
+    type: "submitted";
+    hash: Hash;
+} | {
+    type: "confirmed";
+    hash: Hash;
+    receipt?: TransactionReceipt;
+} | {
     type: "signed";
     hash: Hash;
 } | {
@@ -361,7 +439,12 @@ export type UnifiedRelayerResponse = {
         transactionHash: Hash;
     } | {
         url: string;
-    } | any;
+    };
+} | {
+    /** Non-transactional operations that don't require tracking (e.g., IPFS uploads) */
+    type: "direct_result_untracked";
+    /** The result data from the operation, structure depends on the specific operation */
+    result: unknown;
 } | {
     type: "error";
     error: string;
@@ -415,8 +498,9 @@ export type RelayerConfig = string | ((request: UnifiedRelayerRequest) => Promis
  */
 export interface RelayerCallbacksV2 {
     /**
-     * Submit any relayer operation.
+     * Submits any relayer operation to the server.
      *
+     * @remarks
      * This single callback handles all operations:
      * - EIP-712 signed operations (permissions, server trust, etc.)
      * - Direct operations (file additions, grant storage)
@@ -424,8 +508,20 @@ export interface RelayerCallbacksV2 {
      * On your server, pass the entire request object to the SDK's
      * `handleRelayerOperation` helper function.
      *
-     * @param request - The unified request object
+     * @param request - The unified request object.
+     *   Check `type` field to determine operation variant.
      * @returns Promise resolving to operation-specific response
+     *
+     * @example
+     * ```typescript
+     * async submit(request) {
+     *   const response = await fetch('/api/relay', {
+     *     method: 'POST',
+     *     body: JSON.stringify(request)
+     *   });
+     *   return response.json();
+     * }
+     * ```
      */
     submit: (request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>;
 }

package/dist/types/storage.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/storage.ts"],"sourcesContent":["/**\n * Interface for storage providers that handle file upload, download, and management operations.\n *\n * Storage providers abstract different storage backends (IPFS, Google Drive, Pinata, etc.)\n * behind a common interface. The SDK uses these providers to store encrypted user data\n * and permission grants in a decentralized manner.\n *\n * @category Storage\n * @example\n * ```typescript\n * // Implement a custom storage provider\n * class MyStorageProvider implements StorageProvider {\n *   async upload(file: Blob, filename?: string): Promise<StorageUploadResult> {\n *     // Custom upload logic\n *     return { url: 'https://my-storage.com/file.dat', size: file.size };\n *   }\n *\n *   async download(url: string): Promise<Blob> {\n *     // Custom download logic\n *     const response = await fetch(url);\n *     return response.blob();\n *   }\n *\n *   async list(options?: StorageListOptions): Promise<StorageFile[]> {\n *     // Return list of files\n *     return [];\n *   }\n *\n *   async delete(url: string): Promise<void> {\n *     // Delete file implementation\n *   }\n * }\n * ```\n */\nexport interface StorageProvider {\n  /**\n   * Upload a file to the storage provider\n   *\n   * @param file - The file to upload\n   * @param filename - Optional custom filename\n   * @returns Promise with storage URL and metadata\n   */\n  upload(file: Blob, filename?: string): Promise<StorageUploadResult>;\n\n  /**\n   * Download a file from the storage provider\n   *\n   * @param url - The storage URL\n   * @returns Promise with file blob\n   */\n  download(url: string): Promise<Blob>;\n\n  /**\n   * List files from the storage provider\n   *\n   * @param options - Optional filtering and pagination\n   * @returns Promise with file list\n   */\n  list(options?: StorageListOptions): Promise<StorageFile[]>;\n\n  /**\n   * Delete a file from the storage provider\n   *\n   * @param url - The storage URL\n   * @returns Promise with success status\n   */\n  delete(url: string): Promise<boolean>;\n\n  /**\n   * Get provider-specific configuration\n   *\n   * @returns Provider configuration object\n   */\n  getConfig(): StorageProviderConfig;\n}\n\nexport interface StorageUploadResult {\n  /** Public URL to access the file */\n  url: string;\n  /** File size in bytes */\n  size: number;\n  /** Content type/MIME type */\n  contentType: string;\n  /** Provider-specific metadata */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface StorageFile {\n  /** File identifier */\n  id: string;\n  /** File name */\n  name: string;\n  /** Public URL to access the file */\n  url: string;\n  /** File size in bytes */\n  size: number;\n  /** Content type/MIME type */\n  contentType: string;\n  /** Upload timestamp */\n  createdAt: Date;\n  /** Provider-specific metadata */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface StorageListOptions {\n  /** Maximum number of files to return */\n  limit?: number;\n  /** Pagination cursor/offset */\n  offset?: string | number;\n  /** Filter by file name pattern */\n  namePattern?: string;\n  /** Filter by content type */\n  contentType?: string;\n}\n\nexport interface StorageProviderConfig {\n  /** Provider name */\n  name: string;\n  /** Provider type */\n  type: string;\n  /** Whether authentication is required */\n  requiresAuth: boolean;\n  /** Supported features */\n  features: {\n    upload: boolean;\n    download: boolean;\n    list: boolean;\n    delete: boolean;\n  };\n}\n\nexport class StorageError extends Error {\n  public readonly code: string;\n  public readonly provider: string;\n  // The 'cause' property is now inherited from the base Error class\n\n  constructor(\n    message: string,\n    code: string,\n    provider: string,\n    options?: { cause?: Error },\n  ) {\n    // Pass the options object with 'cause' to the super constructor\n    super(message, options);\n    this.name = \"StorageError\";\n    this.code = code;\n    this.provider = provider;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAmIO,MAAM,qBAAqB,MAAM;AAAA,EACtB;AAAA,EACA;AAAA;AAAA,EAGhB,YACE,SACA,MACA,UACA,SACA;AAEA,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,WAAW;AAAA,EAClB;AACF;","names":[]}
+{"version":3,"sources":["../../src/types/storage.ts"],"sourcesContent":["/**\n * Defines interface for storage provider implementations.\n *\n * @remarks\n * Abstracts storage backends (IPFS, Google Drive, Pinata) behind\n * common interface for encrypted file operations.\n *\n * @category Storage\n * @example\n * ```typescript\n * class MyStorage implements StorageProvider {\n *   async upload(file: Blob): Promise<StorageUploadResult> {\n *     const url = await uploadToService(file);\n *     return { url, size: file.size, contentType: file.type };\n *   }\n *\n *   async download(url: string): Promise<Blob> {\n *     return fetch(url).then(r => r.blob());\n *   }\n * }\n * ```\n */\nexport interface StorageProvider {\n  /**\n   * Upload a file to the storage provider\n   *\n   * @param file - The file to upload\n   * @param filename - Optional custom filename\n   * @returns Promise with storage URL and metadata\n   */\n  upload(file: Blob, filename?: string): Promise<StorageUploadResult>;\n\n  /**\n   * Download a file from the storage provider\n   *\n   * @param url - The storage URL\n   * @returns Promise with file blob\n   */\n  download(url: string): Promise<Blob>;\n\n  /**\n   * List files from the storage provider\n   *\n   * @param options - Optional filtering and pagination\n   * @returns Promise with file list\n   */\n  list(options?: StorageListOptions): Promise<StorageFile[]>;\n\n  /**\n   * Delete a file from the storage provider\n   *\n   * @param url - The storage URL\n   * @returns Promise with success status\n   */\n  delete(url: string): Promise<boolean>;\n\n  /**\n   * Get provider-specific configuration\n   *\n   * @returns Provider configuration object\n   */\n  getConfig(): StorageProviderConfig;\n}\n\nexport interface StorageUploadResult {\n  /** Public URL to access the file */\n  url: string;\n  /** File size in bytes */\n  size: number;\n  /** Content type/MIME type */\n  contentType: string;\n  /** Provider-specific metadata */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface StorageFile {\n  /** File identifier */\n  id: string;\n  /** File name */\n  name: string;\n  /** Public URL to access the file */\n  url: string;\n  /** File size in bytes */\n  size: number;\n  /** Content type/MIME type */\n  contentType: string;\n  /** Upload timestamp */\n  createdAt: Date;\n  /** Provider-specific metadata */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface StorageListOptions {\n  /** Maximum number of files to return */\n  limit?: number;\n  /** Pagination cursor/offset */\n  offset?: string | number;\n  /** Filter by file name pattern */\n  namePattern?: string;\n  /** Filter by content type */\n  contentType?: string;\n}\n\nexport interface StorageProviderConfig {\n  /** Provider name */\n  name: string;\n  /** Provider type */\n  type: string;\n  /** Whether authentication is required */\n  requiresAuth: boolean;\n  /** Supported features */\n  features: {\n    upload: boolean;\n    download: boolean;\n    list: boolean;\n    delete: boolean;\n  };\n}\n\nexport class StorageError extends Error {\n  public readonly code: string;\n  public readonly provider: string;\n  // The 'cause' property is now inherited from the base Error class\n\n  constructor(\n    message: string,\n    code: string,\n    provider: string,\n    options?: { cause?: Error },\n  ) {\n    // Pass the options object with 'cause' to the super constructor\n    super(message, options);\n    this.name = \"StorageError\";\n    this.code = code;\n    this.provider = provider;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAuHO,MAAM,qBAAqB,MAAM;AAAA,EACtB;AAAA,EACA;AAAA;AAAA,EAGhB,YACE,SACA,MACA,UACA,SACA;AAEA,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,WAAW;AAAA,EAClB;AACF;","names":[]}

package/dist/types/storage.d.ts

@@ -1,33 +1,21 @@
 /**
- * Interface for storage providers that handle file upload, download, and management operations.
+ * Defines interface for storage provider implementations.
  *
- * Storage providers abstract different storage backends (IPFS, Google Drive, Pinata, etc.)
- * behind a common interface. The SDK uses these providers to store encrypted user data
- * and permission grants in a decentralized manner.
+ * @remarks
+ * Abstracts storage backends (IPFS, Google Drive, Pinata) behind
+ * common interface for encrypted file operations.
  *
  * @category Storage
  * @example
  * ```typescript
- * // Implement a custom storage provider
- * class MyStorageProvider implements StorageProvider {
- *   async upload(file: Blob, filename?: string): Promise<StorageUploadResult> {
- *     // Custom upload logic
- *     return { url: 'https://my-storage.com/file.dat', size: file.size };
+ * class MyStorage implements StorageProvider {
+ *   async upload(file: Blob): Promise<StorageUploadResult> {
+ *     const url = await uploadToService(file);
+ *     return { url, size: file.size, contentType: file.type };
  *   }
  *
  *   async download(url: string): Promise<Blob> {
- *     // Custom download logic
- *     const response = await fetch(url);
- *     return response.blob();
- *   }
- *
- *   async list(options?: StorageListOptions): Promise<StorageFile[]> {
- *     // Return list of files
- *     return [];
- *   }
- *
- *   async delete(url: string): Promise<void> {
- *     // Delete file implementation
+ *     return fetch(url).then(r => r.blob());
  *   }
  * }
  * ```

package/dist/types/storage.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/storage.ts"],"sourcesContent":["/**\n * Interface for storage providers that handle file upload, download, and management operations.\n *\n * Storage providers abstract different storage backends (IPFS, Google Drive, Pinata, etc.)\n * behind a common interface. The SDK uses these providers to store encrypted user data\n * and permission grants in a decentralized manner.\n *\n * @category Storage\n * @example\n * ```typescript\n * // Implement a custom storage provider\n * class MyStorageProvider implements StorageProvider {\n *   async upload(file: Blob, filename?: string): Promise<StorageUploadResult> {\n *     // Custom upload logic\n *     return { url: 'https://my-storage.com/file.dat', size: file.size };\n *   }\n *\n *   async download(url: string): Promise<Blob> {\n *     // Custom download logic\n *     const response = await fetch(url);\n *     return response.blob();\n *   }\n *\n *   async list(options?: StorageListOptions): Promise<StorageFile[]> {\n *     // Return list of files\n *     return [];\n *   }\n *\n *   async delete(url: string): Promise<void> {\n *     // Delete file implementation\n *   }\n * }\n * ```\n */\nexport interface StorageProvider {\n  /**\n   * Upload a file to the storage provider\n   *\n   * @param file - The file to upload\n   * @param filename - Optional custom filename\n   * @returns Promise with storage URL and metadata\n   */\n  upload(file: Blob, filename?: string): Promise<StorageUploadResult>;\n\n  /**\n   * Download a file from the storage provider\n   *\n   * @param url - The storage URL\n   * @returns Promise with file blob\n   */\n  download(url: string): Promise<Blob>;\n\n  /**\n   * List files from the storage provider\n   *\n   * @param options - Optional filtering and pagination\n   * @returns Promise with file list\n   */\n  list(options?: StorageListOptions): Promise<StorageFile[]>;\n\n  /**\n   * Delete a file from the storage provider\n   *\n   * @param url - The storage URL\n   * @returns Promise with success status\n   */\n  delete(url: string): Promise<boolean>;\n\n  /**\n   * Get provider-specific configuration\n   *\n   * @returns Provider configuration object\n   */\n  getConfig(): StorageProviderConfig;\n}\n\nexport interface StorageUploadResult {\n  /** Public URL to access the file */\n  url: string;\n  /** File size in bytes */\n  size: number;\n  /** Content type/MIME type */\n  contentType: string;\n  /** Provider-specific metadata */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface StorageFile {\n  /** File identifier */\n  id: string;\n  /** File name */\n  name: string;\n  /** Public URL to access the file */\n  url: string;\n  /** File size in bytes */\n  size: number;\n  /** Content type/MIME type */\n  contentType: string;\n  /** Upload timestamp */\n  createdAt: Date;\n  /** Provider-specific metadata */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface StorageListOptions {\n  /** Maximum number of files to return */\n  limit?: number;\n  /** Pagination cursor/offset */\n  offset?: string | number;\n  /** Filter by file name pattern */\n  namePattern?: string;\n  /** Filter by content type */\n  contentType?: string;\n}\n\nexport interface StorageProviderConfig {\n  /** Provider name */\n  name: string;\n  /** Provider type */\n  type: string;\n  /** Whether authentication is required */\n  requiresAuth: boolean;\n  /** Supported features */\n  features: {\n    upload: boolean;\n    download: boolean;\n    list: boolean;\n    delete: boolean;\n  };\n}\n\nexport class StorageError extends Error {\n  public readonly code: string;\n  public readonly provider: string;\n  // The 'cause' property is now inherited from the base Error class\n\n  constructor(\n    message: string,\n    code: string,\n    provider: string,\n    options?: { cause?: Error },\n  ) {\n    // Pass the options object with 'cause' to the super constructor\n    super(message, options);\n    this.name = \"StorageError\";\n    this.code = code;\n    this.provider = provider;\n  }\n}\n"],"mappings":"AAmIO,MAAM,qBAAqB,MAAM;AAAA,EACtB;AAAA,EACA;AAAA;AAAA,EAGhB,YACE,SACA,MACA,UACA,SACA;AAEA,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,WAAW;AAAA,EAClB;AACF;","names":[]}
+{"version":3,"sources":["../../src/types/storage.ts"],"sourcesContent":["/**\n * Defines interface for storage provider implementations.\n *\n * @remarks\n * Abstracts storage backends (IPFS, Google Drive, Pinata) behind\n * common interface for encrypted file operations.\n *\n * @category Storage\n * @example\n * ```typescript\n * class MyStorage implements StorageProvider {\n *   async upload(file: Blob): Promise<StorageUploadResult> {\n *     const url = await uploadToService(file);\n *     return { url, size: file.size, contentType: file.type };\n *   }\n *\n *   async download(url: string): Promise<Blob> {\n *     return fetch(url).then(r => r.blob());\n *   }\n * }\n * ```\n */\nexport interface StorageProvider {\n  /**\n   * Upload a file to the storage provider\n   *\n   * @param file - The file to upload\n   * @param filename - Optional custom filename\n   * @returns Promise with storage URL and metadata\n   */\n  upload(file: Blob, filename?: string): Promise<StorageUploadResult>;\n\n  /**\n   * Download a file from the storage provider\n   *\n   * @param url - The storage URL\n   * @returns Promise with file blob\n   */\n  download(url: string): Promise<Blob>;\n\n  /**\n   * List files from the storage provider\n   *\n   * @param options - Optional filtering and pagination\n   * @returns Promise with file list\n   */\n  list(options?: StorageListOptions): Promise<StorageFile[]>;\n\n  /**\n   * Delete a file from the storage provider\n   *\n   * @param url - The storage URL\n   * @returns Promise with success status\n   */\n  delete(url: string): Promise<boolean>;\n\n  /**\n   * Get provider-specific configuration\n   *\n   * @returns Provider configuration object\n   */\n  getConfig(): StorageProviderConfig;\n}\n\nexport interface StorageUploadResult {\n  /** Public URL to access the file */\n  url: string;\n  /** File size in bytes */\n  size: number;\n  /** Content type/MIME type */\n  contentType: string;\n  /** Provider-specific metadata */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface StorageFile {\n  /** File identifier */\n  id: string;\n  /** File name */\n  name: string;\n  /** Public URL to access the file */\n  url: string;\n  /** File size in bytes */\n  size: number;\n  /** Content type/MIME type */\n  contentType: string;\n  /** Upload timestamp */\n  createdAt: Date;\n  /** Provider-specific metadata */\n  metadata?: Record<string, unknown>;\n}\n\nexport interface StorageListOptions {\n  /** Maximum number of files to return */\n  limit?: number;\n  /** Pagination cursor/offset */\n  offset?: string | number;\n  /** Filter by file name pattern */\n  namePattern?: string;\n  /** Filter by content type */\n  contentType?: string;\n}\n\nexport interface StorageProviderConfig {\n  /** Provider name */\n  name: string;\n  /** Provider type */\n  type: string;\n  /** Whether authentication is required */\n  requiresAuth: boolean;\n  /** Supported features */\n  features: {\n    upload: boolean;\n    download: boolean;\n    list: boolean;\n    delete: boolean;\n  };\n}\n\nexport class StorageError extends Error {\n  public readonly code: string;\n  public readonly provider: string;\n  // The 'cause' property is now inherited from the base Error class\n\n  constructor(\n    message: string,\n    code: string,\n    provider: string,\n    options?: { cause?: Error },\n  ) {\n    // Pass the options object with 'cause' to the super constructor\n    super(message, options);\n    this.name = \"StorageError\";\n    this.code = code;\n    this.provider = provider;\n  }\n}\n"],"mappings":"AAuHO,MAAM,qBAAqB,MAAM;AAAA,EACtB;AAAA,EACA;AAAA;AAAA,EAGhB,YACE,SACA,MACA,UACA,SACA;AAEA,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,WAAW;AAAA,EAClB;AACF;","names":[]}