@opendatalabs/vana-sdk 0.1.0-alpha.d7fc764 → 0.1.0-alpha.dba79a3

package/dist/types/relayer.d.ts

@@ -1,12 +1,26 @@
-import { Hash } from 'viem';
-import { GrantFile, PermissionGrantTypedData } from './permissions.js';
-
 /**
- * Response from the relayer service for grant file storage
+ * 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";
+/**
+ * Represents the response from storing grant files via relayer.
+ *
+ * @remarks
+ * Contains storage location, metadata, and error information for
+ * grant file upload operations.
  *
  * @category Advanced
  */
-interface RelayerStorageResponse {
+export interface RelayerStorageResponse {
     /** The IPFS URL where the grant file is stored */
     grantUrl: string;
     /** Success status */
@@ -24,11 +38,15 @@ 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
  */
-interface RelayerTransactionResponse {
+export interface RelayerTransactionResponse {
     /** The transaction hash of the submitted transaction */
     transactionHash: Hash;
     /** Success status */
@@ -48,11 +66,15 @@ 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
  */
-interface RelayerStoreParams {
+export interface RelayerStoreParams {
     /** The grant file to store */
     grantFile: GrantFile;
     /** Optional storage options */
@@ -66,11 +88,15 @@ 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
  */
-interface RelayerSubmitParams {
+export interface RelayerSubmitParams {
     /** The signed typed data */
     typedData: PermissionGrantTypedData;
     /** The signature */
@@ -86,11 +112,15 @@ 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
  */
-interface RelayerStatus {
+export interface RelayerStatus {
     /** Whether the relayer is online */
     online: boolean;
     /** Service version */
@@ -119,33 +149,15 @@ interface RelayerStatus {
     };
 }
 /**
- * Relayer configuration
+ * Configures behavior for relayer requests.
  *
- * @category Advanced
- */
-interface RelayerConfig {
-    /** Relayer service URL */
-    url: string;
-    /** API key for authentication */
-    apiKey?: string;
-    /** Timeout for requests in milliseconds */
-    timeout?: number;
-    /** Retry configuration */
-    retry?: {
-        /** Number of retry attempts */
-        attempts: number;
-        /** Delay between retries in milliseconds */
-        delay: number;
-    };
-    /** Whether to use HTTPS */
-    useHttps?: boolean;
-}
-/**
- * Relayer request options
+ * @remarks
+ * Controls timeout, retry logic, headers, and priority for
+ * relayer operation requests.
  *
  * @category Advanced
  */
-interface RelayerRequestOptions {
+export interface RelayerRequestOptions {
     /** Request timeout in milliseconds */
     timeout?: number;
     /** Whether to retry on failure */
@@ -156,11 +168,15 @@ 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
  */
-interface RelayerErrorResponse {
+export interface RelayerErrorResponse {
     /** Error code */
     code: string;
     /** Error message */
@@ -173,11 +189,15 @@ 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
  */
-interface RelayerQueueInfo {
+export interface RelayerQueueInfo {
     /** Current queue size */
     size: number;
     /** Estimated processing time in seconds */
@@ -195,11 +215,15 @@ 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
  */
-interface RelayerTransactionStatus {
+export interface RelayerTransactionStatus {
     /** Transaction hash */
     transactionHash: Hash;
     /** Current status */
@@ -221,11 +245,15 @@ 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
  */
-interface RelayerMetrics {
+export interface RelayerMetrics {
     /** Total transactions processed */
     totalTransactions: number;
     /** Successful transactions */
@@ -249,11 +277,15 @@ interface RelayerMetrics {
     };
 }
 /**
- * Relayer webhook configuration
+ * Configures webhook notifications for relayer events.
+ *
+ * @remarks
+ * Enables asynchronous notifications for transaction confirmations,
+ * failures, and storage completions.
  *
  * @category Advanced
  */
-interface RelayerWebhookConfig {
+export interface RelayerWebhookConfig {
     /** Webhook URL */
     url: string;
     /** Events to subscribe to */
@@ -264,11 +296,15 @@ 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
  */
-interface RelayerWebhookPayload {
+export interface RelayerWebhookPayload {
     /** Event type */
     event: string;
     /** Event data */
@@ -280,5 +316,212 @@ interface RelayerWebhookPayload {
     /** Signature for verification */
     signature: string;
 }
-
-export type { RelayerConfig, RelayerErrorResponse, RelayerMetrics, RelayerQueueInfo, RelayerRequestOptions, RelayerStatus, RelayerStorageResponse, RelayerStoreParams, RelayerSubmitParams, RelayerTransactionResponse, RelayerTransactionStatus, RelayerWebhookConfig, RelayerWebhookPayload };
+/**
+ * Handles both EIP-712 signed operations and direct server operations through a single interface.
+ *
+ * @remarks
+ * This discriminated union provides type safety through TypeScript's narrowing.
+ * The `type` field determines which operation variant is being used.
+ * Signed operations require blockchain transactions, while direct operations
+ * handle auxiliary tasks like file storage.
+ *
+ * @category Relayer
+ * @see {@link https://docs.vana.org/docs/gasless-transactions | Gasless Transactions Guide}
+ */
+export type UnifiedRelayerRequest = SignedRelayerRequest | DirectRelayerRequest | {
+    type: "status_check";
+    operationId: string;
+};
+/**
+ * Represents an EIP-712 signed operation for gasless transaction submission.
+ *
+ * @remarks
+ * Signed requests contain typed data and signatures that are verified
+ * on-chain by smart contracts. The relayer pays gas fees on behalf of users.
+ *
+ * @category Relayer
+ */
+export interface SignedRelayerRequest {
+    /** Discriminator field identifying this as a signed operation */
+    type: "signed";
+    /** Operation identifier for routing (e.g., 'submitAddPermission') */
+    operation: SignedOperationType;
+    /** EIP-712 typed data structure for the operation */
+    typedData: GenericTypedData;
+    /** User's signature of the typed data */
+    signature: Hash;
+    /** Optional address for additional signer verification */
+    expectedUserAddress?: Address;
+}
+/**
+ * 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";
+/**
+ * Represents direct server operations that don't require blockchain signatures.
+ *
+ * @remarks
+ * Direct requests handle auxiliary operations like file uploads and grant storage.
+ * These operations may still result in blockchain transactions but don't require
+ * user signatures for gasless submission.
+ *
+ * @category Relayer
+ */
+export type DirectRelayerRequest = {
+    type: "direct";
+    operation: "submitFileAddition";
+    params: {
+        url: string;
+        userAddress: Address;
+    };
+} | {
+    type: "direct";
+    operation: "submitFileAdditionWithPermissions";
+    params: {
+        url: string;
+        userAddress: Address;
+        permissions: Array<{
+            account: Address;
+            key: string;
+        }>;
+    };
+} | {
+    type: "direct";
+    operation: "submitFileAdditionComplete";
+    params: {
+        url: string;
+        userAddress: Address;
+        permissions: Array<{
+            account: Address;
+            key: string;
+        }>;
+        schemaId: number;
+        ownerAddress?: Address;
+    };
+} | {
+    type: "direct";
+    operation: "storeGrantFile";
+    params: GrantFile;
+} | {
+    type: "direct";
+    operation: "submitRegisterGrantee";
+    params: {
+        owner: Address;
+        granteeAddress: Address;
+        publicKey: string;
+    };
+};
+/**
+ * Provides type-safe responses for all relayer operations.
+ *
+ * @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;
+} | {
+    /** Non-transactional operations that complete immediately (e.g., IPFS uploads, file info) */
+    type: "direct";
+    /** The result data from the operation, structure depends on the specific operation */
+    result: unknown;
+} | {
+    type: "error";
+    error: string;
+};
+/**
+ * Simplified relayer configuration.
+ * Can be a URL string for convenience, or a callback for full control.
+ *
+ * @category Configuration
+ * @example
+ * ```typescript
+ * // Option 1: Simple URL (SDK handles the transport)
+ * const vana = Vana({
+ *   walletClient,
+ *   relayer: '/api/relay'
+ * });
+ *
+ * // Option 2: Full control with callback
+ * const vana = Vana({
+ *   walletClient,
+ *   relayer: async (request) => {
+ *     const response = await fetch('/api/relay', {
+ *       method: 'POST',
+ *       body: JSON.stringify(request)
+ *     });
+ *     return response.json();
+ *   }
+ * });
+ * ```
+ */
+export type RelayerConfig = string | ((request: UnifiedRelayerRequest) => Promise<UnifiedRelayerResponse>);
+/**
+ * Simplified relayer callbacks interface (v2).
+ * A single callback handles all relayer operations.
+ *
+ * @category Configuration
+ * @example
+ * ```typescript
+ * const relayerCallbacks: RelayerCallbacksV2 = {
+ *   submit: async (request) => {
+ *     // Send to your server endpoint
+ *     const response = await fetch('/api/relay', {
+ *       method: 'POST',
+ *       headers: { 'Content-Type': 'application/json' },
+ *       body: JSON.stringify(request)
+ *     });
+ *     return response.json();
+ *   }
+ * };
+ * ```
+ */
+export interface RelayerCallbacksV2 {
+    /**
+     * 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)
+     *
+     * On your server, pass the entire request object to the SDK's
+     * `handleRelayerOperation` helper function.
+     *
+     * @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,38 +1,26 @@
 /**
- * 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());
  *   }
  * }
  * ```
  */
-interface StorageProvider {
+export interface StorageProvider {
     /**
      * Upload a file to the storage provider
      *
@@ -69,7 +57,7 @@ interface StorageProvider {
      */
     getConfig(): StorageProviderConfig;
 }
-interface StorageUploadResult {
+export interface StorageUploadResult {
     /** Public URL to access the file */
     url: string;
     /** File size in bytes */
@@ -79,7 +67,7 @@ interface StorageUploadResult {
     /** Provider-specific metadata */
     metadata?: Record<string, unknown>;
 }
-interface StorageFile {
+export interface StorageFile {
     /** File identifier */
     id: string;
     /** File name */
@@ -95,7 +83,7 @@ interface StorageFile {
     /** Provider-specific metadata */
     metadata?: Record<string, unknown>;
 }
-interface StorageListOptions {
+export interface StorageListOptions {
     /** Maximum number of files to return */
     limit?: number;
     /** Pagination cursor/offset */
@@ -105,7 +93,7 @@ interface StorageListOptions {
     /** Filter by content type */
     contentType?: string;
 }
-interface StorageProviderConfig {
+export interface StorageProviderConfig {
     /** Provider name */
     name: string;
     /** Provider type */
@@ -120,12 +108,10 @@ interface StorageProviderConfig {
         delete: boolean;
     };
 }
-declare class StorageError extends Error {
+export declare class StorageError extends Error {
     readonly code: string;
     readonly provider: string;
     constructor(message: string, code: string, provider: string, options?: {
         cause?: Error;
     });
 }
-
-export { StorageError, type StorageFile, type StorageListOptions, type StorageProvider, type StorageProviderConfig, type StorageUploadResult };

package/dist/types/storage.js

@@ -1,12 +1,9 @@
-var __defProp = Object.defineProperty;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 class StorageError extends Error {
+  code;
+  provider;
   // The 'cause' property is now inherited from the base Error class
   constructor(message, code, provider, options) {
     super(message, options);
-    __publicField(this, "code");
-    __publicField(this, "provider");
     this.name = "StorageError";
     this.code = code;
     this.provider = provider;

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;AAAA,EAKtC,YACE,SACA,MACA,UACA,SACA;AAEA,UAAM,SAAS,OAAO;AAXxB,wBAAgB;AAChB,wBAAgB;AAWd,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":[]}

package/dist/types/transactionResults.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/transactionResults.ts"],"sourcesContent":["import type { Address } from \"viem\";\nimport type { BaseTransactionResult } from \"../utils/transactionParsing\";\n\n/**\n * Transaction result types for all SDK operations.\n * These interfaces define the structure of data returned by enhanced\n * transaction methods that parse blockchain events automatically.\n */\n\n// =============================================================================\n// PERMISSION OPERATIONS\n// =============================================================================\n\n/**\n * Result of a successful permission grant operation.\n * Contains data from the PermissionAdded blockchain event.\n */\nexport interface PermissionGrantResult extends BaseTransactionResult {\n  /** Unique permission ID for this grant */\n  permissionId: bigint;\n  /** Address of the user who granted the permission */\n  user: Address;\n  /** URL where the grant file is stored (IPFS/CDN) */\n  grant: string;\n  /** Array of file IDs covered by this permission */\n  fileIds: readonly bigint[];\n}\n\n/**\n * Result of a successful permission revocation operation.\n * Contains data from the PermissionRevoked blockchain event.\n */\nexport interface PermissionRevokeResult extends BaseTransactionResult {\n  /** ID of the permission that was revoked */\n  permissionId: bigint;\n}\n\n/**\n * Result of a successful server trust operation.\n * Contains data from the ServerTrusted blockchain event.\n */\nexport interface ServerTrustResult extends BaseTransactionResult {\n  /** Address of the user who trusted the server */\n  user: Address;\n  /** Address/ID of the trusted server */\n  serverId: Address;\n  /** URL of the trusted server */\n  serverUrl: string;\n}\n\n/**\n * Result of a successful server untrust operation.\n * Contains data from the ServerUntrusted blockchain event.\n */\nexport interface ServerUntrustResult extends BaseTransactionResult {\n  /** Address of the user who untrusted the server */\n  user: Address;\n  /** Address/ID of the untrusted server */\n  serverId: Address;\n}\n\n/**\n * Result of a successful server registration operation.\n * Contains data from the ServerRegistered blockchain event.\n */\nexport interface ServerRegisterResult extends BaseTransactionResult {\n  /** Unique server ID assigned by the registry */\n  serverId: bigint;\n  /** URL of the registered server */\n  url: string;\n  /** Owner address of the server */\n  owner: Address;\n}\n\n/**\n * Result of a successful server update operation.\n * Contains data from the ServerUpdated blockchain event.\n */\nexport interface ServerUpdateResult extends BaseTransactionResult {\n  /** ID of the server that was updated */\n  serverId: bigint;\n  /** New URL of the server */\n  url: string;\n}\n\n/**\n * Result of a successful grantee registration operation.\n * Contains data from the GranteeRegistered blockchain event.\n */\nexport interface GranteeRegisterResult extends BaseTransactionResult {\n  /** Unique grantee ID assigned by the registry */\n  granteeId: bigint;\n  /** Address of the registered grantee */\n  granteeAddress: Address;\n  /** Display name of the grantee */\n  name: string;\n}\n\n// =============================================================================\n// DATA REGISTRY OPERATIONS\n// =============================================================================\n\n/**\n * Result of a successful file addition operation.\n * Contains data from the FileAddedV2 blockchain event.\n */\nexport interface FileAddedResult extends BaseTransactionResult {\n  /** Unique file ID assigned by the registry */\n  fileId: bigint;\n  /** Address of the file owner */\n  ownerAddress: Address;\n  /** URL where the file is stored */\n  url: string;\n  /** Schema ID associated with the file (0 for no schema) */\n  schemaId: bigint;\n}\n\n/**\n * Result of a successful schema addition operation.\n * Contains data from the SchemaAdded blockchain event.\n */\nexport interface SchemaAddedResult extends BaseTransactionResult {\n  /** Unique schema ID assigned by the registry */\n  schemaId: bigint;\n  /** Human-readable name of the schema */\n  name: string;\n  /** Schema dialect (e.g., \"jsonschema\") */\n  dialect: string;\n  /** URL where the schema definition is stored */\n  definitionUrl: string;\n}\n\n/**\n * Result of a successful refiner addition operation.\n * Contains data from the RefinerAdded blockchain event.\n */\nexport interface RefinerAddedResult extends BaseTransactionResult {\n  /** Unique refiner ID assigned by the registry */\n  refinerId: bigint;\n  /** DLP ID this refiner belongs to */\n  dlpId: bigint;\n  /** Human-readable name of the refiner */\n  name: string;\n  /** Schema ID this refiner uses */\n  schemaId: bigint;\n  /** URL where the schema definition is stored */\n  schemaDefinitionUrl: string;\n  /** URL with refiner processing instructions */\n  refinementInstructionUrl: string;\n}\n\n/**\n * Result of a successful schema ID update operation.\n * Contains data from the RefinerSchemaUpdated blockchain event.\n */\nexport interface SchemaUpdateResult extends BaseTransactionResult {\n  /** ID of the refiner that was updated */\n  refinerId: bigint;\n  /** New schema ID */\n  schemaId: bigint;\n  /** URL of the new schema definition */\n  schemaDefinitionUrl: string;\n}\n\n/**\n * Result of a successful file permission addition operation.\n * Contains data from the FilePermissionAdded blockchain event.\n */\nexport interface FilePermissionResult extends BaseTransactionResult {\n  /** File ID the permission was added to */\n  fileId: bigint;\n  /** Account that was granted permission */\n  account: Address;\n  /** Encrypted key for file access */\n  encryptedKey: string;\n}\n\n// =============================================================================\n// UNION TYPES FOR GENERIC OPERATIONS\n// =============================================================================\n\n/**\n * Union type of all possible transaction result types.\n * Useful for generic functions that handle multiple operation types.\n */\nexport type AnyTransactionResult =\n  | PermissionGrantResult\n  | PermissionRevokeResult\n  | ServerTrustResult\n  | ServerUntrustResult\n  | ServerRegisterResult\n  | ServerUpdateResult\n  | GranteeRegisterResult\n  | FileAddedResult\n  | SchemaAddedResult\n  | RefinerAddedResult\n  | SchemaUpdateResult\n  | FilePermissionResult;\n\n// =============================================================================\n// TYPE UTILITIES\n// =============================================================================\n\n/**\n * Maps transaction operation names to their result types.\n * Used for type inference in generic transaction parsing functions.\n */\nexport interface TransactionResultMap {\n  grant: PermissionGrantResult;\n  revoke: PermissionRevokeResult;\n  revokePermission: PermissionRevokeResult;\n  addServerFilesAndPermissions: PermissionGrantResult;\n  trustServer: ServerTrustResult;\n  untrustServer: ServerUntrustResult;\n  registerServer: ServerRegisterResult;\n  updateServer: ServerUpdateResult;\n  addAndTrustServer: ServerTrustResult;\n  registerGrantee: GranteeRegisterResult;\n  addFile: FileAddedResult;\n  addFileWithPermissionsAndSchema: FileAddedResult;\n  addFileWithSchema: FileAddedResult;\n  addFileWithPermissions: FileAddedResult;\n  addRefinement: RefinerAddedResult;\n  addRefiner: RefinerAddedResult;\n  updateSchemaId: SchemaUpdateResult;\n  addSchema: SchemaAddedResult;\n  updateRefinement: SchemaUpdateResult;\n  addFilePermission: FilePermissionResult;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/types/transactionResults.ts"],"sourcesContent":["import type { Address } from \"viem\";\n// BaseTransactionResult will be replaced once migration is complete\ninterface BaseTransactionResult {\n  transactionHash: `0x${string}`;\n  blockNumber: bigint;\n  gasUsed: bigint;\n}\n\n/**\n * Transaction result types for all SDK operations.\n * These interfaces define the structure of data returned by enhanced\n * transaction methods that parse blockchain events automatically.\n */\n\n// =============================================================================\n// PERMISSION OPERATIONS\n// =============================================================================\n\n/**\n * Result of a successful permission grant operation.\n * Contains data from the PermissionAdded blockchain event.\n */\nexport interface PermissionGrantResult extends BaseTransactionResult {\n  /** Unique permission ID for this grant */\n  permissionId: bigint;\n  /** Address of the user who granted the permission */\n  user: Address;\n  /** URL where the grant file is stored (IPFS/CDN) */\n  grant: string;\n  /** Array of file IDs covered by this permission */\n  fileIds: readonly bigint[];\n}\n\n/**\n * Result of a successful permission revocation operation.\n * Contains data from the PermissionRevoked blockchain event.\n */\nexport interface PermissionRevokeResult extends BaseTransactionResult {\n  /** ID of the permission that was revoked */\n  permissionId: bigint;\n}\n\n/**\n * Result of a successful server trust operation.\n * Contains data from the ServerTrusted blockchain event.\n */\nexport interface ServerTrustResult extends BaseTransactionResult {\n  /** Address of the user who trusted the server (from event) */\n  user: Address;\n  /** Numeric ID of the trusted server (from event) */\n  serverId: bigint;\n  /** Address of the trusted server (from params/derived) */\n  serverAddress?: Address;\n  /** URL of the trusted server (from params/provided) */\n  serverUrl?: string;\n}\n\n/**\n * Result of a successful server untrust operation.\n * Contains data from the ServerUntrusted blockchain event.\n */\nexport interface ServerUntrustResult extends BaseTransactionResult {\n  /** Address of the user who untrusted the server */\n  user: Address;\n  /** Address/ID of the untrusted server */\n  serverId: Address;\n}\n\n/**\n * Result of a successful server registration operation.\n * Contains data from the ServerRegistered blockchain event.\n */\nexport interface ServerRegisterResult extends BaseTransactionResult {\n  /** Unique server ID assigned by the registry */\n  serverId: bigint;\n  /** URL of the registered server */\n  url: string;\n  /** Owner address of the server */\n  owner: Address;\n}\n\n/**\n * Result of a successful server update operation.\n * Contains data from the ServerUpdated blockchain event.\n */\nexport interface ServerUpdateResult extends BaseTransactionResult {\n  /** ID of the server that was updated */\n  serverId: bigint;\n  /** New URL of the server */\n  url: string;\n}\n\n/**\n * Result of a successful grantee registration operation.\n * Contains data from the GranteeRegistered blockchain event.\n */\nexport interface GranteeRegisterResult extends BaseTransactionResult {\n  /** Unique grantee ID assigned by the registry */\n  granteeId: bigint;\n  /** Address of the registered grantee */\n  granteeAddress: Address;\n  /** Display name of the grantee */\n  name: string;\n}\n\n// =============================================================================\n// DATA REGISTRY OPERATIONS\n// =============================================================================\n\n/**\n * Result of a successful file addition operation.\n * Contains data from the FileAddedV2 blockchain event.\n */\nexport interface FileAddedResult extends BaseTransactionResult {\n  /** Unique file ID assigned by the registry */\n  fileId: bigint;\n  /** Address of the file owner */\n  ownerAddress: Address;\n  /** URL where the file is stored */\n  url: string;\n  /** Schema ID associated with the file (0 for no schema) */\n  schemaId: bigint;\n}\n\n/**\n * Result of a successful schema addition operation.\n * Contains data from the SchemaAdded blockchain event.\n */\nexport interface SchemaAddedResult extends BaseTransactionResult {\n  /** Unique schema ID assigned by the registry */\n  schemaId: bigint;\n  /** Human-readable name of the schema */\n  name: string;\n  /** Schema dialect (e.g., \"jsonschema\") */\n  dialect: string;\n  /** URL where the schema definition is stored */\n  definitionUrl: string;\n}\n\n/**\n * Result of a successful refiner addition operation.\n * Contains data from the RefinerAdded blockchain event.\n */\nexport interface RefinerAddedResult extends BaseTransactionResult {\n  /** Unique refiner ID assigned by the registry */\n  refinerId: bigint;\n  /** DLP ID this refiner belongs to */\n  dlpId: bigint;\n  /** Human-readable name of the refiner */\n  name: string;\n  /** Schema ID this refiner uses */\n  schemaId: bigint;\n  /** URL where the schema definition is stored */\n  schemaDefinitionUrl: string;\n  /** URL with refiner processing instructions */\n  refinementInstructionUrl: string;\n}\n\n/**\n * Result of a successful schema ID update operation.\n * Contains data from the RefinerSchemaUpdated blockchain event.\n */\nexport interface SchemaUpdateResult extends BaseTransactionResult {\n  /** ID of the refiner that was updated */\n  refinerId: bigint;\n  /** New schema ID */\n  schemaId: bigint;\n  /** URL of the new schema definition */\n  schemaDefinitionUrl: string;\n}\n\n/**\n * Result of a successful file permission addition operation.\n * Contains data from the FilePermissionAdded blockchain event.\n */\nexport interface FilePermissionResult extends BaseTransactionResult {\n  /** File ID the permission was added to */\n  fileId: bigint;\n  /** Account that was granted permission */\n  account: Address;\n  /** Encrypted key for file access */\n  encryptedKey: string;\n}\n\n// =============================================================================\n// UNION TYPES FOR GENERIC OPERATIONS\n// =============================================================================\n\n/**\n * Union type of all possible transaction result types.\n * Useful for generic functions that handle multiple operation types.\n */\nexport type AnyTransactionResult =\n  | PermissionGrantResult\n  | PermissionRevokeResult\n  | ServerTrustResult\n  | ServerUntrustResult\n  | ServerRegisterResult\n  | ServerUpdateResult\n  | GranteeRegisterResult\n  | FileAddedResult\n  | SchemaAddedResult\n  | RefinerAddedResult\n  | SchemaUpdateResult\n  | FilePermissionResult;\n\n// =============================================================================\n// TYPE UTILITIES\n// =============================================================================\n\n/**\n * Maps transaction operation names to their result types.\n * Used for type inference in generic transaction parsing functions.\n */\nexport interface TransactionResultMap {\n  grant: PermissionGrantResult;\n  revoke: PermissionRevokeResult;\n  revokePermission: PermissionRevokeResult;\n  addServerFilesAndPermissions: PermissionGrantResult;\n  trustServer: ServerTrustResult;\n  untrustServer: ServerUntrustResult;\n  registerServer: ServerRegisterResult;\n  updateServer: ServerUpdateResult;\n  addAndTrustServer: ServerTrustResult;\n  registerGrantee: GranteeRegisterResult;\n  addFile: FileAddedResult;\n  addFileWithPermissionsAndSchema: FileAddedResult;\n  addFileWithSchema: FileAddedResult;\n  addFileWithPermissions: FileAddedResult;\n  addRefinement: RefinerAddedResult;\n  addRefiner: RefinerAddedResult;\n  updateSchemaId: SchemaUpdateResult;\n  addSchema: SchemaAddedResult;\n  updateRefinement: SchemaUpdateResult;\n  addFilePermission: FilePermissionResult;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}