@opendatalabs/vana-sdk 0.1.0-alpha.eebb656 → 0.1.0-alpha.ef15099

package/dist/storage/providers/pinata.d.ts

@@ -28,30 +28,28 @@ export interface PinataFile {
     metadata?: object;
 }
 /**
- * Provides managed IPFS storage with full-featured API via Pinata
+ * Manages IPFS storage through Pinata's enhanced API.
  *
  * @remarks
- * This provider uses Pinata's enhanced IPFS service, which extends standard IPFS
- * with additional features like file listing, deletion (unpinning), and rich metadata.
- * It's the "it just works" solution for developers who want full CRUD operations
- * on IPFS without managing infrastructure.
+ * Extends standard IPFS with additional features like file listing,
+ * deletion (unpinning), and rich metadata. Production-ready managed
+ * service with guaranteed availability. The "it just works" solution
+ * for developers who want full CRUD operations on IPFS without
+ * managing infrastructure.
  *
  * @category Storage
- *
  * @example
  * ```typescript
- * const pinataStorage = new PinataStorage({
- *   jwt: "your-pinata-jwt-token"
+ * const storage = new PinataStorage({
+ *   jwt: "your-jwt-token"
  * });
  *
  * // Upload with metadata
- * const cid = await pinataStorage.upload(fileBlob, {
- *   name: "user-avatar.png",
- *   metadata: { userId: "123", category: "avatar" }
- * });
+ * const result = await storage.upload(blob, "file.json");
+ * console.log(`Pinned at: ${result.url}`);
  *
- * // List files with query
- * const files = await pinataStorage.list({ limit: 10 });
+ * // List and manage files
+ * const files = await storage.list({ limit: 10 });
  *
  * // Delete file
  * await pinataStorage.delete(cid);

package/dist/storage/providers/pinata.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/storage/providers/pinata.ts"],"sourcesContent":["import {\n  StorageError,\n  type StorageProvider,\n  type StorageUploadResult,\n  type StorageFile,\n  type StorageListOptions,\n  type StorageProviderConfig,\n} from \"../index\";\n\nexport interface PinataConfig {\n  /** Pinata JWT token for authentication */\n  jwt: string;\n  /** Optional custom gateway URL (defaults to https://gateway.pinata.cloud) */\n  gatewayUrl?: string;\n}\n\nexport interface PinataListQuery {\n  /** Maximum number of results to return */\n  limit?: number;\n  /** Offset for pagination */\n  offset?: number;\n  /** Filter by name pattern */\n  namePattern?: string;\n}\n\nexport interface PinataFile {\n  /** Pin identifier */\n  id: string;\n  /** File name */\n  name: string;\n  /** IPFS CID */\n  cid: string;\n  /** File size in bytes */\n  size: number;\n  /** Creation timestamp */\n  createdAt: Date;\n  /** Optional metadata */\n  metadata?: object;\n}\n\ninterface PinataUploadResponse {\n  /** IPFS hash of the uploaded content */\n  IpfsHash: string;\n  /** Size of the uploaded content in bytes */\n  PinSize: number;\n  /** Upload timestamp (ISO string) */\n  Timestamp: string;\n}\n\ninterface PinataListResponse {\n  /** Total number of pins matching the query */\n  count: number;\n  /** Array of pin objects */\n  rows: Array<{\n    /** Unique pin identifier */\n    id: string;\n    /** IPFS hash of the pinned content */\n    ipfs_pin_hash: string;\n    /** Size in bytes */\n    size: number;\n    /** User ID that owns the pin */\n    user_id: string;\n    /** Date when content was pinned */\n    date_pinned: string;\n    /** Date when content was unpinned (if applicable) */\n    date_unpinned?: string;\n    /** Pin metadata */\n    metadata: {\n      /** Optional name for the pin */\n      name?: string;\n      /** Additional key-value metadata */\n      keyvalues?: Record<string, unknown>;\n    };\n  }>;\n}\n\n/**\n * Provides managed IPFS storage with full-featured API via Pinata\n *\n * @remarks\n * This provider uses Pinata's enhanced IPFS service, which extends standard IPFS\n * with additional features like file listing, deletion (unpinning), and rich metadata.\n * It's the \"it just works\" solution for developers who want full CRUD operations\n * on IPFS without managing infrastructure.\n *\n * @category Storage\n *\n * @example\n * ```typescript\n * const pinataStorage = new PinataStorage({\n *   jwt: \"your-pinata-jwt-token\"\n * });\n *\n * // Upload with metadata\n * const cid = await pinataStorage.upload(fileBlob, {\n *   name: \"user-avatar.png\",\n *   metadata: { userId: \"123\", category: \"avatar\" }\n * });\n *\n * // List files with query\n * const files = await pinataStorage.list({ limit: 10 });\n *\n * // Delete file\n * await pinataStorage.delete(cid);\n * ```\n */\nexport class PinataStorage implements StorageProvider {\n  private readonly apiUrl = \"https://api.pinata.cloud\";\n  private readonly gatewayUrl: string;\n\n  constructor(private config: PinataConfig) {\n    this.gatewayUrl = config.gatewayUrl ?? \"https://gateway.pinata.cloud\";\n    if (!config.jwt) {\n      throw new StorageError(\n        \"Pinata JWT token is required\",\n        \"MISSING_JWT\",\n        \"pinata\",\n      );\n    }\n  }\n\n  /**\n   * Uploads a file to IPFS via Pinata and returns the CID\n   *\n   * @remarks\n   * This method uploads the file to Pinata's IPFS service with enhanced metadata support.\n   * The file is pinned to ensure availability and can include custom metadata for\n   * organization and querying. The metadata is stored alongside the file for later retrieval.\n   *\n   * @param file - The file to upload to IPFS\n   * @param filename - Optional custom filename\n   * @returns Promise that resolves to the IPFS CID (content identifier)\n   * @throws {StorageError} When the upload fails or no CID is returned\n   *\n   * @example\n   * ```typescript\n   * const cid = await pinataStorage.upload(fileBlob, {\n   *   name: \"user-document.pdf\",\n   *   metadata: {\n   *     userId: \"user-123\",\n   *     category: \"documents\",\n   *     uploadDate: new Date().toISOString()\n   *   }\n   * });\n   * console.log(\"File pinned to IPFS:\", cid);\n   * ```\n   */\n  async upload(file: Blob, filename?: string): Promise<StorageUploadResult> {\n    try {\n      const fileName = filename ?? `vana-file-${Date.now()}.dat`;\n\n      // Create form data for Pinata upload\n      const formData = new FormData();\n      formData.append(\"file\", file, fileName);\n\n      // Add metadata\n      const metadata = {\n        name: fileName,\n        keyvalues: {\n          uploadedBy: \"vana-sdk\",\n          timestamp: new Date().toISOString(),\n        },\n      };\n      formData.append(\"pinataMetadata\", JSON.stringify(metadata));\n\n      // Upload to Pinata\n      const response = await fetch(`${this.apiUrl}/pinning/pinFileToIPFS`, {\n        method: \"POST\",\n        headers: {\n          Authorization: `Bearer ${this.config.jwt}`,\n        },\n        body: formData,\n      });\n\n      if (!response.ok) {\n        const errorText = await response.text();\n        throw new StorageError(\n          `Pinata upload failed: ${errorText}`,\n          \"UPLOAD_FAILED\",\n          \"pinata\",\n        );\n      }\n\n      const result = (await response.json()) as PinataUploadResponse;\n      const ipfsHash = result.IpfsHash;\n\n      if (!ipfsHash) {\n        throw new StorageError(\n          \"Pinata upload succeeded but no IPFS hash returned\",\n          \"NO_HASH_RETURNED\",\n          \"pinata\",\n        );\n      }\n\n      return {\n        url: `ipfs://${ipfsHash}`,\n        size: file.size,\n        contentType: file.type ?? \"application/octet-stream\",\n      };\n    } catch (error) {\n      if (error instanceof StorageError) {\n        throw error;\n      }\n      throw new StorageError(\n        `Pinata upload error: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        \"UPLOAD_ERROR\",\n        \"pinata\",\n      );\n    }\n  }\n\n  async download(cid: string): Promise<Blob> {\n    try {\n      // Validate CID format\n      if (!this.isValidCID(cid)) {\n        throw new StorageError(\n          \"Invalid IPFS CID format\",\n          \"INVALID_CID\",\n          \"pinata\",\n        );\n      }\n\n      // Download from gateway\n      const downloadUrl = `${this.gatewayUrl}/ipfs/${cid}`;\n      const response = await fetch(downloadUrl);\n\n      if (!response.ok) {\n        throw new StorageError(\n          `Failed to download from IPFS: ${response.statusText}`,\n          \"DOWNLOAD_FAILED\",\n          \"pinata\",\n        );\n      }\n\n      return await response.blob();\n    } catch (error) {\n      if (error instanceof StorageError) {\n        throw error;\n      }\n      throw new StorageError(\n        `Pinata download error: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        \"DOWNLOAD_ERROR\",\n        \"pinata\",\n      );\n    }\n  }\n\n  /**\n   * Lists files uploaded to Pinata with optional filtering\n   *\n   * @remarks\n   * This method retrieves a list of files that have been uploaded to Pinata,\n   * filtered to only include files uploaded by the Vana SDK. You can further\n   * filter results by name pattern, limit results, or paginate through them.\n   *\n   * @param options - Optional query parameters for filtering and pagination\n   * @param options.limit - Maximum number of results to return (default: 10)\n   * @param options.offset - Number of results to skip for pagination\n   * @param options.namePattern - Filter files by name pattern\n   * @returns Promise that resolves to an array of PinataFile objects\n   * @throws {StorageError} When the list operation fails\n   *\n   * @example\n   * ```typescript\n   * // List all files\n   * const allFiles = await pinataStorage.list();\n   *\n   * // List with pagination and filtering\n   * const filteredFiles = await pinataStorage.list({\n   *   limit: 20,\n   *   offset: 10,\n   *   namePattern: \"document\"\n   * });\n   *\n   * filteredFiles.forEach(file => {\n   *   console.log(`${file.name} (${file.size} bytes): ${file.cid}`);\n   * });\n   * ```\n   */\n  async list(options?: StorageListOptions): Promise<StorageFile[]> {\n    try {\n      const params = new URLSearchParams({\n        status: \"pinned\",\n        pageLimit: (options?.limit ?? 10).toString(),\n        metadata: JSON.stringify({\n          keyvalues: {\n            uploadedBy: \"vana-sdk\",\n          },\n        }),\n      });\n\n      if (options?.offset) {\n        params.set(\"pageOffset\", options.offset.toString());\n      }\n\n      if (options?.namePattern) {\n        params.set(\"metadata[name]\", options.namePattern);\n      }\n\n      const response = await fetch(`${this.apiUrl}/data/pinList?${params}`, {\n        headers: {\n          Authorization: `Bearer ${this.config.jwt}`,\n        },\n      });\n\n      if (!response.ok) {\n        const errorText = await response.text();\n        throw new StorageError(\n          `Failed to list Pinata files: ${errorText}`,\n          \"LIST_FAILED\",\n          \"pinata\",\n        );\n      }\n\n      const result = (await response.json()) as PinataListResponse;\n\n      return result.rows.map((pin) => ({\n        id: pin.id,\n        name: pin.metadata?.name ?? \"Unnamed\",\n        url: `ipfs://${pin.ipfs_pin_hash}`,\n        size: parseInt(String(pin.size), 10) || 0,\n        contentType: \"application/octet-stream\", // Pinata doesn't store content type\n        createdAt: new Date(pin.date_pinned),\n        metadata: pin.metadata?.keyvalues ?? {},\n      }));\n    } catch (error) {\n      if (error instanceof StorageError) {\n        throw error;\n      }\n      throw new StorageError(\n        `Pinata list error: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        \"LIST_ERROR\",\n        \"pinata\",\n      );\n    }\n  }\n\n  /**\n   * Deletes a file from Pinata by unpinning it from IPFS\n   *\n   * @remarks\n   * This method removes the file from your Pinata account by unpinning it,\n   * which means it will no longer be guaranteed to be available on the IPFS network.\n   * Note that if the file is pinned elsewhere or cached by other nodes, it may still\n   * be accessible for some time.\n   *\n   * @param url - The IPFS URL or content identifier of the file to delete\n   * @returns Promise that resolves when the file is successfully unpinned\n   * @throws {StorageError} When the deletion fails or CID format is invalid\n   *\n   * @example\n   * ```typescript\n   * // Delete a file by CID\n   * await pinataStorage.delete(\"QmTzQ1JRkWErjk39mryYw2WVrgBMe2B36gRq8GCL8qCACj\");\n   * console.log(\"File unpinned from Pinata\");\n   *\n   * // Delete after listing\n   * const files = await pinataStorage.list();\n   * for (const file of files) {\n   *   if (file.name.includes(\"temp\")) {\n   *     await pinataStorage.delete(file.cid);\n   *   }\n   * }\n   * ```\n   */\n  async delete(url: string): Promise<boolean> {\n    try {\n      // Extract CID from URL or use as-is\n      const cid = this.extractCidFromUrl(url);\n\n      // Validate CID format\n      if (!this.isValidCID(cid)) {\n        throw new StorageError(\n          \"Invalid IPFS CID format\",\n          \"INVALID_CID\",\n          \"pinata\",\n        );\n      }\n\n      const response = await fetch(`${this.apiUrl}/pinning/unpin/${cid}`, {\n        method: \"DELETE\",\n        headers: {\n          Authorization: `Bearer ${this.config.jwt}`,\n        },\n      });\n\n      if (!response.ok) {\n        const errorText = await response.text();\n        throw new StorageError(\n          `Failed to delete from Pinata: ${errorText}`,\n          \"DELETE_FAILED\",\n          \"pinata\",\n        );\n      }\n\n      return true;\n    } catch (error) {\n      if (error instanceof StorageError) {\n        throw error;\n      }\n      throw new StorageError(\n        `Pinata delete error: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        \"DELETE_ERROR\",\n        \"pinata\",\n      );\n    }\n  }\n\n  getConfig(): StorageProviderConfig {\n    return {\n      name: \"Pinata IPFS\",\n      type: \"pinata\",\n      requiresAuth: true,\n      features: {\n        upload: true,\n        download: true,\n        list: true,\n        delete: true,\n      },\n    };\n  }\n\n  /**\n   * Extract CID from URL or return as-is\n   *\n   * @param url - URL or CID string\n   * @returns CID string\n   */\n  private extractCidFromUrl(url: string): string {\n    // If it's already a CID (not a URL), return as-is\n    if (!url.includes(\"/\")) {\n      return url;\n    }\n\n    // Extract CID from gateway URL\n    const cidMatch = url.match(/\\/ipfs\\/([a-zA-Z0-9]+)/);\n    if (cidMatch) {\n      return cidMatch[1];\n    }\n\n    // If no match, assume it's a CID\n    return url;\n  }\n\n  /**\n   * Basic CID validation\n   *\n   * @param cid - Content identifier to validate\n   * @returns True if CID appears valid\n   */\n  private isValidCID(cid: string): boolean {\n    // Basic validation: CIDs typically start with 'Qm' or 'ba' and contain alphanumeric characters\n    return (\n      /^[a-zA-Z0-9]{10,}$/.test(cid) &&\n      (cid.startsWith(\"Qm\") || cid.startsWith(\"ba\") || cid.includes(\"Test\"))\n    );\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../../src/storage/providers/pinata.ts"],"sourcesContent":["import {\n  StorageError,\n  type StorageProvider,\n  type StorageUploadResult,\n  type StorageFile,\n  type StorageListOptions,\n  type StorageProviderConfig,\n} from \"../index\";\n\nexport interface PinataConfig {\n  /** Pinata JWT token for authentication */\n  jwt: string;\n  /** Optional custom gateway URL (defaults to https://gateway.pinata.cloud) */\n  gatewayUrl?: string;\n}\n\nexport interface PinataListQuery {\n  /** Maximum number of results to return */\n  limit?: number;\n  /** Offset for pagination */\n  offset?: number;\n  /** Filter by name pattern */\n  namePattern?: string;\n}\n\nexport interface PinataFile {\n  /** Pin identifier */\n  id: string;\n  /** File name */\n  name: string;\n  /** IPFS CID */\n  cid: string;\n  /** File size in bytes */\n  size: number;\n  /** Creation timestamp */\n  createdAt: Date;\n  /** Optional metadata */\n  metadata?: object;\n}\n\ninterface PinataUploadResponse {\n  /** IPFS hash of the uploaded content */\n  IpfsHash: string;\n  /** Size of the uploaded content in bytes */\n  PinSize: number;\n  /** Upload timestamp (ISO string) */\n  Timestamp: string;\n}\n\ninterface PinataListResponse {\n  /** Total number of pins matching the query */\n  count: number;\n  /** Array of pin objects */\n  rows: Array<{\n    /** Unique pin identifier */\n    id: string;\n    /** IPFS hash of the pinned content */\n    ipfs_pin_hash: string;\n    /** Size in bytes */\n    size: number;\n    /** User ID that owns the pin */\n    user_id: string;\n    /** Date when content was pinned */\n    date_pinned: string;\n    /** Date when content was unpinned (if applicable) */\n    date_unpinned?: string;\n    /** Pin metadata */\n    metadata: {\n      /** Optional name for the pin */\n      name?: string;\n      /** Additional key-value metadata */\n      keyvalues?: Record<string, unknown>;\n    };\n  }>;\n}\n\n/**\n * Manages IPFS storage through Pinata's enhanced API.\n *\n * @remarks\n * Extends standard IPFS with additional features like file listing,\n * deletion (unpinning), and rich metadata. Production-ready managed\n * service with guaranteed availability. The \"it just works\" solution\n * for developers who want full CRUD operations on IPFS without\n * managing infrastructure.\n *\n * @category Storage\n * @example\n * ```typescript\n * const storage = new PinataStorage({\n *   jwt: \"your-jwt-token\"\n * });\n *\n * // Upload with metadata\n * const result = await storage.upload(blob, \"file.json\");\n * console.log(`Pinned at: ${result.url}`);\n *\n * // List and manage files\n * const files = await storage.list({ limit: 10 });\n *\n * // Delete file\n * await pinataStorage.delete(cid);\n * ```\n */\nexport class PinataStorage implements StorageProvider {\n  private readonly apiUrl = \"https://api.pinata.cloud\";\n  private readonly gatewayUrl: string;\n\n  constructor(private config: PinataConfig) {\n    this.gatewayUrl = config.gatewayUrl ?? \"https://gateway.pinata.cloud\";\n    if (!config.jwt) {\n      throw new StorageError(\n        \"Pinata JWT token is required\",\n        \"MISSING_JWT\",\n        \"pinata\",\n      );\n    }\n  }\n\n  /**\n   * Uploads a file to IPFS via Pinata and returns the CID\n   *\n   * @remarks\n   * This method uploads the file to Pinata's IPFS service with enhanced metadata support.\n   * The file is pinned to ensure availability and can include custom metadata for\n   * organization and querying. The metadata is stored alongside the file for later retrieval.\n   *\n   * @param file - The file to upload to IPFS\n   * @param filename - Optional custom filename\n   * @returns Promise that resolves to the IPFS CID (content identifier)\n   * @throws {StorageError} When the upload fails or no CID is returned\n   *\n   * @example\n   * ```typescript\n   * const cid = await pinataStorage.upload(fileBlob, {\n   *   name: \"user-document.pdf\",\n   *   metadata: {\n   *     userId: \"user-123\",\n   *     category: \"documents\",\n   *     uploadDate: new Date().toISOString()\n   *   }\n   * });\n   * console.log(\"File pinned to IPFS:\", cid);\n   * ```\n   */\n  async upload(file: Blob, filename?: string): Promise<StorageUploadResult> {\n    try {\n      const fileName = filename ?? `vana-file-${Date.now()}.dat`;\n\n      // Create form data for Pinata upload\n      const formData = new FormData();\n      formData.append(\"file\", file, fileName);\n\n      // Add metadata\n      const metadata = {\n        name: fileName,\n        keyvalues: {\n          uploadedBy: \"vana-sdk\",\n          timestamp: new Date().toISOString(),\n        },\n      };\n      formData.append(\"pinataMetadata\", JSON.stringify(metadata));\n\n      // Upload to Pinata\n      const response = await fetch(`${this.apiUrl}/pinning/pinFileToIPFS`, {\n        method: \"POST\",\n        headers: {\n          Authorization: `Bearer ${this.config.jwt}`,\n        },\n        body: formData,\n      });\n\n      if (!response.ok) {\n        const errorText = await response.text();\n        throw new StorageError(\n          `Pinata upload failed: ${errorText}`,\n          \"UPLOAD_FAILED\",\n          \"pinata\",\n        );\n      }\n\n      const result = (await response.json()) as PinataUploadResponse;\n      const ipfsHash = result.IpfsHash;\n\n      if (!ipfsHash) {\n        throw new StorageError(\n          \"Pinata upload succeeded but no IPFS hash returned\",\n          \"NO_HASH_RETURNED\",\n          \"pinata\",\n        );\n      }\n\n      return {\n        url: `ipfs://${ipfsHash}`,\n        size: file.size,\n        contentType: file.type ?? \"application/octet-stream\",\n      };\n    } catch (error) {\n      if (error instanceof StorageError) {\n        throw error;\n      }\n      throw new StorageError(\n        `Pinata upload error: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        \"UPLOAD_ERROR\",\n        \"pinata\",\n      );\n    }\n  }\n\n  async download(cid: string): Promise<Blob> {\n    try {\n      // Validate CID format\n      if (!this.isValidCID(cid)) {\n        throw new StorageError(\n          \"Invalid IPFS CID format\",\n          \"INVALID_CID\",\n          \"pinata\",\n        );\n      }\n\n      // Download from gateway\n      const downloadUrl = `${this.gatewayUrl}/ipfs/${cid}`;\n      const response = await fetch(downloadUrl);\n\n      if (!response.ok) {\n        throw new StorageError(\n          `Failed to download from IPFS: ${response.statusText}`,\n          \"DOWNLOAD_FAILED\",\n          \"pinata\",\n        );\n      }\n\n      return await response.blob();\n    } catch (error) {\n      if (error instanceof StorageError) {\n        throw error;\n      }\n      throw new StorageError(\n        `Pinata download error: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        \"DOWNLOAD_ERROR\",\n        \"pinata\",\n      );\n    }\n  }\n\n  /**\n   * Lists files uploaded to Pinata with optional filtering\n   *\n   * @remarks\n   * This method retrieves a list of files that have been uploaded to Pinata,\n   * filtered to only include files uploaded by the Vana SDK. You can further\n   * filter results by name pattern, limit results, or paginate through them.\n   *\n   * @param options - Optional query parameters for filtering and pagination\n   * @param options.limit - Maximum number of results to return (default: 10)\n   * @param options.offset - Number of results to skip for pagination\n   * @param options.namePattern - Filter files by name pattern\n   * @returns Promise that resolves to an array of PinataFile objects\n   * @throws {StorageError} When the list operation fails\n   *\n   * @example\n   * ```typescript\n   * // List all files\n   * const allFiles = await pinataStorage.list();\n   *\n   * // List with pagination and filtering\n   * const filteredFiles = await pinataStorage.list({\n   *   limit: 20,\n   *   offset: 10,\n   *   namePattern: \"document\"\n   * });\n   *\n   * filteredFiles.forEach(file => {\n   *   console.log(`${file.name} (${file.size} bytes): ${file.cid}`);\n   * });\n   * ```\n   */\n  async list(options?: StorageListOptions): Promise<StorageFile[]> {\n    try {\n      const params = new URLSearchParams({\n        status: \"pinned\",\n        pageLimit: (options?.limit ?? 10).toString(),\n        metadata: JSON.stringify({\n          keyvalues: {\n            uploadedBy: \"vana-sdk\",\n          },\n        }),\n      });\n\n      if (options?.offset) {\n        params.set(\"pageOffset\", options.offset.toString());\n      }\n\n      if (options?.namePattern) {\n        params.set(\"metadata[name]\", options.namePattern);\n      }\n\n      const response = await fetch(`${this.apiUrl}/data/pinList?${params}`, {\n        headers: {\n          Authorization: `Bearer ${this.config.jwt}`,\n        },\n      });\n\n      if (!response.ok) {\n        const errorText = await response.text();\n        throw new StorageError(\n          `Failed to list Pinata files: ${errorText}`,\n          \"LIST_FAILED\",\n          \"pinata\",\n        );\n      }\n\n      const result = (await response.json()) as PinataListResponse;\n\n      return result.rows.map((pin) => ({\n        id: pin.id,\n        name: pin.metadata?.name ?? \"Unnamed\",\n        url: `ipfs://${pin.ipfs_pin_hash}`,\n        size: parseInt(String(pin.size), 10) || 0,\n        contentType: \"application/octet-stream\", // Pinata doesn't store content type\n        createdAt: new Date(pin.date_pinned),\n        metadata: pin.metadata?.keyvalues ?? {},\n      }));\n    } catch (error) {\n      if (error instanceof StorageError) {\n        throw error;\n      }\n      throw new StorageError(\n        `Pinata list error: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        \"LIST_ERROR\",\n        \"pinata\",\n      );\n    }\n  }\n\n  /**\n   * Deletes a file from Pinata by unpinning it from IPFS\n   *\n   * @remarks\n   * This method removes the file from your Pinata account by unpinning it,\n   * which means it will no longer be guaranteed to be available on the IPFS network.\n   * Note that if the file is pinned elsewhere or cached by other nodes, it may still\n   * be accessible for some time.\n   *\n   * @param url - The IPFS URL or content identifier of the file to delete\n   * @returns Promise that resolves when the file is successfully unpinned\n   * @throws {StorageError} When the deletion fails or CID format is invalid\n   *\n   * @example\n   * ```typescript\n   * // Delete a file by CID\n   * await pinataStorage.delete(\"QmTzQ1JRkWErjk39mryYw2WVrgBMe2B36gRq8GCL8qCACj\");\n   * console.log(\"File unpinned from Pinata\");\n   *\n   * // Delete after listing\n   * const files = await pinataStorage.list();\n   * for (const file of files) {\n   *   if (file.name.includes(\"temp\")) {\n   *     await pinataStorage.delete(file.cid);\n   *   }\n   * }\n   * ```\n   */\n  async delete(url: string): Promise<boolean> {\n    try {\n      // Extract CID from URL or use as-is\n      const cid = this.extractCidFromUrl(url);\n\n      // Validate CID format\n      if (!this.isValidCID(cid)) {\n        throw new StorageError(\n          \"Invalid IPFS CID format\",\n          \"INVALID_CID\",\n          \"pinata\",\n        );\n      }\n\n      const response = await fetch(`${this.apiUrl}/pinning/unpin/${cid}`, {\n        method: \"DELETE\",\n        headers: {\n          Authorization: `Bearer ${this.config.jwt}`,\n        },\n      });\n\n      if (!response.ok) {\n        const errorText = await response.text();\n        throw new StorageError(\n          `Failed to delete from Pinata: ${errorText}`,\n          \"DELETE_FAILED\",\n          \"pinata\",\n        );\n      }\n\n      return true;\n    } catch (error) {\n      if (error instanceof StorageError) {\n        throw error;\n      }\n      throw new StorageError(\n        `Pinata delete error: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n        \"DELETE_ERROR\",\n        \"pinata\",\n      );\n    }\n  }\n\n  getConfig(): StorageProviderConfig {\n    return {\n      name: \"Pinata IPFS\",\n      type: \"pinata\",\n      requiresAuth: true,\n      features: {\n        upload: true,\n        download: true,\n        list: true,\n        delete: true,\n      },\n    };\n  }\n\n  /**\n   * Extract CID from URL or return as-is\n   *\n   * @param url - URL or CID string\n   * @returns CID string\n   */\n  private extractCidFromUrl(url: string): string {\n    // If it's already a CID (not a URL), return as-is\n    if (!url.includes(\"/\")) {\n      return url;\n    }\n\n    // Extract CID from gateway URL\n    const cidMatch = url.match(/\\/ipfs\\/([a-zA-Z0-9]+)/);\n    if (cidMatch) {\n      return cidMatch[1];\n    }\n\n    // If no match, assume it's a CID\n    return url;\n  }\n\n  /**\n   * Basic CID validation\n   *\n   * @param cid - Content identifier to validate\n   * @returns True if CID appears valid\n   */\n  private isValidCID(cid: string): boolean {\n    // Basic validation: CIDs typically start with 'Qm' or 'ba' and contain alphanumeric characters\n    return (\n      /^[a-zA-Z0-9]{10,}$/.test(cid) &&\n      (cid.startsWith(\"Qm\") || cid.startsWith(\"ba\") || cid.includes(\"Test\"))\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/tests/data-upload-owner-validation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/factories/mockFactory.d.ts

@@ -58,7 +58,7 @@ export type DeepPartial<T> = {
  * @example
  * ```typescript
  * const account = createMockAccount({
- *   address: "0xCustomAddress" as Address
+ *   address: "0xCustomAddress"
  * });
  * ```
  */
@@ -92,7 +92,7 @@ export declare function createMockChain(overrides?: Partial<Chain>): Chain;
  * @example
  * ```typescript
  * const wallet = createTypedMockWalletClient({
- *   account: { address: "0xCustom" as Address },
+ *   account: { address: "0xCustom" },
  *   chain: { id: 1480 }
  * });
  * ```
@@ -154,7 +154,7 @@ export declare function createTypedMockStorageManager(overrides?: Partial<Storag
  * @example
  * ```typescript
  * const context = createMockControllerContext({
- *   walletClient: { account: { address: "0xCustom" as Address } }
+ *   walletClient: { account: { address: "0xCustom" } }
  * });
  * const controller = new DataController(context);
  * ```
@@ -218,7 +218,7 @@ export declare function safeCast<T>(value: DeepPartial<T>): T;
  * ```typescript
  * const mockLog = createMockLog("PermissionGranted", {
  *   permissionId: 123n,
- *   user: "0xUserAddress" as Address,
+ *   user: "0xUserAddress",
  *   grant: "grant-data"
  * });
  * ```
@@ -262,7 +262,7 @@ export declare function createPartialMock<T>(partial: Partial<T>): T;
  *
  * @remarks
  * This factory variant is optimized for testing direct blockchain transactions
- * without gasless relayer support. It sets both `relayerCallbacks` and
+ * without gasless relayer support. It sets both `relayer` and
  * `storageManager` to `undefined`, forcing the controller to use direct transactions.
  *
  * @example
@@ -290,7 +290,7 @@ export declare function createMockControllerContextForDirectTransaction(override
  * const context = createMockControllerContextWithRelayer();
  * const controller = new PermissionsController(context);
  * const result = await controller.grant(params);
- * expect(context.relayerCallbacks?.storeGrantFile).toHaveBeenCalled();
+ * expect(context.relayer?.storeGrantFile).toHaveBeenCalled();
  * ```
  */
 export declare function createMockControllerContextWithRelayer(overrides?: DeepPartial<ControllerContext>): ControllerContext & Required<Pick<ControllerContext, "waitForTransactionEvents">>;

package/dist/tests/fakes/FakeWaitForTransactionEvents.d.ts

@@ -57,7 +57,7 @@ export declare class FakeWaitForTransactionEvents {
      * const fake = new FakeWaitForTransactionEvents();
      * fake.setResponse("0xabc123", {
      *   hash: "0xabc123" as Hash,
-     *   from: "0xuser" as Address,
+     *   from: "0xuser",
      *   contract: "DataRegistry",
      *   fn: "addFile",
      *   expectedEvents: { FileAdded: { fileId: 1n } },
@@ -90,7 +90,7 @@ export declare class FakeWaitForTransactionEvents {
      * const fake = new FakeWaitForTransactionEvents();
      * fake.setDefaultResponse({
      *   hash: "0xdefault" as Hash,
-     *   from: "0xdefault" as Address,
+     *   from: "0xdefault",
      *   contract: "TestContract",
      *   fn: "testFunction",
      *   expectedEvents: {},

package/dist/tests/permissions-revoke-relayer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/permissions-transaction-options.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/read-only-mode.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/relayer-integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/relayer-unified.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/server-relayer-handler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/accessSettlement.cjs

@@ -0,0 +1,17 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var accessSettlement_exports = {};
+module.exports = __toCommonJS(accessSettlement_exports);
+//# sourceMappingURL=accessSettlement.cjs.map

package/dist/types/accessSettlement.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/accessSettlement.ts"],"sourcesContent":["import type { Address, Hash } from \"viem\";\n\n/**\n * Operation invoice structure returned by the AccessSettlement contract\n *\n * @remarks\n * Represents the payment details for a runtime operation.\n * Created by the runtime after an operation completes with a finalPrice.\n *\n * @category Access Settlement\n * @example\n * ```typescript\n * const invoice = await sdk.accessSettlement.getOperationInvoice(\"op_123\");\n * console.log(`Price: ${invoice.price} wei`);\n * console.log(`Settled: ${invoice.isSettled}`);\n * ```\n */\nexport interface OperationInvoice {\n  /** Address of the issuer (runtime) who created the invoice */\n  issuer: Address;\n\n  /** Address of the grantee (consumer) who must pay */\n  grantee: Address;\n\n  /** Final price in wei for the operation */\n  price: bigint;\n\n  /** Token address for payment (0x0 for native VANA) */\n  tokenAddress: Address;\n\n  /** Whether the payment has been settled */\n  isSettled: boolean;\n}\n\n/**\n * Result from settling a payment\n *\n * @remarks\n * Contains the transaction hash for tracking payment confirmation.\n *\n * @category Access Settlement\n */\nexport interface PaymentSettlementResult {\n  /** Transaction hash of the settlement */\n  hash: Hash;\n\n  /** Operation ID that was settled */\n  operationId: string;\n}\n\n/**\n * Parameters for settling a payment with native VANA\n *\n * @category Access Settlement\n */\nexport interface SettleWithNativeParams {\n  /** Operation ID to settle payment for */\n  operationId: string;\n\n  /** Amount to pay in wei (must match invoice price) */\n  value: bigint;\n}\n\n/**\n * Parameters for settling a payment with an ERC20 token\n *\n * @category Access Settlement\n */\nexport interface SettleWithTokenParams {\n  /** Operation ID to settle payment for */\n  operationId: string;\n\n  /** ERC20 token contract address */\n  tokenAddress: Address;\n\n  /** Amount to pay (must match invoice price and have approval) */\n  amount: bigint;\n}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types/accessSettlement.d.ts

@@ -0,0 +1,66 @@
+import type { Address, Hash } from "viem";
+/**
+ * Operation invoice structure returned by the AccessSettlement contract
+ *
+ * @remarks
+ * Represents the payment details for a runtime operation.
+ * Created by the runtime after an operation completes with a finalPrice.
+ *
+ * @category Access Settlement
+ * @example
+ * ```typescript
+ * const invoice = await sdk.accessSettlement.getOperationInvoice("op_123");
+ * console.log(`Price: ${invoice.price} wei`);
+ * console.log(`Settled: ${invoice.isSettled}`);
+ * ```
+ */
+export interface OperationInvoice {
+    /** Address of the issuer (runtime) who created the invoice */
+    issuer: Address;
+    /** Address of the grantee (consumer) who must pay */
+    grantee: Address;
+    /** Final price in wei for the operation */
+    price: bigint;
+    /** Token address for payment (0x0 for native VANA) */
+    tokenAddress: Address;
+    /** Whether the payment has been settled */
+    isSettled: boolean;
+}
+/**
+ * Result from settling a payment
+ *
+ * @remarks
+ * Contains the transaction hash for tracking payment confirmation.
+ *
+ * @category Access Settlement
+ */
+export interface PaymentSettlementResult {
+    /** Transaction hash of the settlement */
+    hash: Hash;
+    /** Operation ID that was settled */
+    operationId: string;
+}
+/**
+ * Parameters for settling a payment with native VANA
+ *
+ * @category Access Settlement
+ */
+export interface SettleWithNativeParams {
+    /** Operation ID to settle payment for */
+    operationId: string;
+    /** Amount to pay in wei (must match invoice price) */
+    value: bigint;
+}
+/**
+ * Parameters for settling a payment with an ERC20 token
+ *
+ * @category Access Settlement
+ */
+export interface SettleWithTokenParams {
+    /** Operation ID to settle payment for */
+    operationId: string;
+    /** ERC20 token contract address */
+    tokenAddress: Address;
+    /** Amount to pay (must match invoice price and have approval) */
+    amount: bigint;
+}

package/dist/types/accessSettlement.js

@@ -0,0 +1 @@
+//# sourceMappingURL=accessSettlement.js.map

package/dist/types/accessSettlement.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types/atomicStore.cjs

@@ -0,0 +1,31 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var atomicStore_exports = {};
+__export(atomicStore_exports, {
+  hasNonceSupport: () => hasNonceSupport
+});
+module.exports = __toCommonJS(atomicStore_exports);
+function hasNonceSupport(store) {
+  return "atomicAssignNonce" in store && typeof store.atomicAssignNonce === "function";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  hasNonceSupport
+});
+//# sourceMappingURL=atomicStore.cjs.map

package/dist/types/atomicStore.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/atomicStore.ts"],"sourcesContent":["/**\n * Atomic storage primitives for distributed state management.\n *\n * @module\n */\n\n/**\n * Interface for atomic storage operations required by the SDK's distributed components.\n *\n * @remarks\n * Implementations of this interface MUST guarantee atomicity for all operations.\n * These primitives are used by the SDK's internal components to coordinate\n * distributed state in multi-instance deployments (e.g., serverless functions).\n *\n * The SDK provides a reference Redis implementation, but you can implement\n * this interface using any storage backend that supports atomic operations:\n * - PostgreSQL with advisory locks\n * - DynamoDB with conditional writes\n * - MongoDB with findAndModify\n * - Zookeeper or etcd for coordination\n *\n * @example\n * ```typescript\n * // Using the Redis reference implementation\n * import { RedisAtomicStore } from './lib/redisAtomicStore';\n *\n * const atomicStore = new RedisAtomicStore({\n *   redis: process.env.REDIS_URL\n * });\n *\n * const vana = Vana({\n *   privateKey: process.env.RELAYER_PRIVATE_KEY,\n *   atomicStore\n * });\n * ```\n *\n * @category Storage\n */\nexport interface IAtomicStore {\n  /**\n   * Atomically increments a counter and returns the new value.\n   *\n   * @remarks\n   * This operation MUST be atomic. If the key doesn't exist, it should be\n   * initialized to 0 before incrementing. The operation must return the\n   * value after incrementing.\n   *\n   * This is used primarily for nonce assignment where atomicity is critical\n   * to prevent conflicts under concurrent load.\n   *\n   * @param key - The key to increment\n   * @returns The new value after incrementing\n   *\n   * @example\n   * ```typescript\n   * // First call returns 1\n   * const nonce1 = await store.incr('nonce:0x123:1480');\n   * // Second call returns 2\n   * const nonce2 = await store.incr('nonce:0x123:1480');\n   * ```\n   */\n  incr(key: string): Promise<number>;\n\n  /**\n   * Attempts to acquire a distributed lock with automatic expiration.\n   *\n   * @remarks\n   * This operation MUST be atomic and follow the \"SET NX EX\" semantics:\n   * - Only succeeds if the lock doesn't exist (NX - \"Not eXists\")\n   * - Automatically expires after the specified TTL (EX - \"EXpire\")\n   * - Returns a unique lock ID on success for safe release\n   *\n   * The lock ID should be a unique value (e.g., UUID or timestamp+random)\n   * that prevents accidental release by other processes.\n   *\n   * @param key - The lock key\n   * @param ttlSeconds - Time-to-live in seconds (automatic expiration)\n   * @returns A unique lock ID if acquired, null if lock is already held\n   *\n   * @example\n   * ```typescript\n   * const lockId = await store.acquireLock('nonce:lock:0x123', 5);\n   * if (lockId) {\n   *   try {\n   *     // Critical section - only one process can be here\n   *     await performCriticalOperation();\n   *   } finally {\n   *     await store.releaseLock('nonce:lock:0x123', lockId);\n   *   }\n   * }\n   * ```\n   */\n  acquireLock(key: string, ttlSeconds: number): Promise<string | null>;\n\n  /**\n   * Releases a previously acquired lock.\n   *\n   * @remarks\n   * This operation MUST be atomic and safe. It should only succeed if the\n   * provided lockId matches the current lock value. This prevents accidental\n   * release of locks acquired by other processes.\n   *\n   * Implementations should use compare-and-delete semantics or a Lua script\n   * (in Redis) to ensure atomicity.\n   *\n   * @param key - The lock key\n   * @param lockId - The unique ID returned by acquireLock\n   *\n   * @example\n   * ```typescript\n   * const lockId = await store.acquireLock('lock:key', 5);\n   * if (lockId) {\n   *   // ... do work ...\n   *   await store.releaseLock('lock:key', lockId);\n   * }\n   * ```\n   */\n  releaseLock(key: string, lockId: string): Promise<void>;\n\n  /**\n   * Gets the value associated with a key.\n   *\n   * @remarks\n   * This is a simple read operation. It should return null if the key\n   * doesn't exist.\n   *\n   * @param key - The key to retrieve\n   * @returns The stored value, or null if not found\n   *\n   * @example\n   * ```typescript\n   * const lastUsedNonce = await store.get('lastNonce:0x123:1480');\n   * ```\n   */\n  get(key: string): Promise<string | null>;\n\n  /**\n   * Sets a key-value pair.\n   *\n   * @remarks\n   * This is a simple write operation. It should overwrite any existing value.\n   *\n   * @param key - The key to set\n   * @param value - The value to store\n   *\n   * @example\n   * ```typescript\n   * await store.set('lastNonce:0x123:1480', '42');\n   * ```\n   */\n  set(key: string, value: string): Promise<void>;\n\n  /**\n   * Sets a key-value pair with expiration.\n   *\n   * @remarks\n   * This operation sets a value with automatic expiration after the specified TTL.\n   * Useful for temporary state that should be automatically cleaned up.\n   *\n   * @param key - The key to set\n   * @param value - The value to store\n   * @param ttlSeconds - Time-to-live in seconds\n   *\n   * @example\n   * ```typescript\n   * // Store operation state for 24 hours\n   * await store.setWithTTL('operation:123', JSON.stringify(state), 86400);\n   * ```\n   */\n  setWithTTL?(key: string, value: string, ttlSeconds: number): Promise<void>;\n\n  /**\n   * Deletes a key.\n   *\n   * @remarks\n   * This operation removes a key from storage. Should be idempotent\n   * (no error if key doesn't exist).\n   *\n   * @param key - The key to delete\n   *\n   * @example\n   * ```typescript\n   * await store.delete('temp:data:123');\n   * ```\n   */\n  delete?(key: string): Promise<void>;\n\n  /**\n   * Executes an atomic script (e.g., Lua in Redis, stored procedure in SQL).\n   *\n   * @remarks\n   * This is an optional method that allows execution of atomic scripts\n   * for complex operations that require multiple steps to be atomic.\n   * Not all stores support this - simple stores may omit it.\n   *\n   * For Redis: executes a Lua script\n   * For PostgreSQL: executes a stored procedure or CTE\n   * For DynamoDB: might use TransactWrite\n   *\n   * @param script - The script to execute\n   * @param keys - Array of keys the script will operate on\n   * @param args - Array of arguments to pass to the script\n   * @returns The script's return value\n   *\n   * @example\n   * ```typescript\n   * const result = await store.eval(\n   *   'return redis.call(\"INCR\", KEYS[1])',\n   *   ['counter:users'],\n   *   []\n   * );\n   * ```\n   */\n  eval?(script: string, keys: string[], args: string[]): Promise<any>;\n}\n\n/**\n * Extended atomic store interface with nonce support.\n *\n * @remarks\n * Some atomic stores (like Redis) provide optimized atomic nonce assignment\n * through native scripting capabilities. This interface extends the base\n * IAtomicStore with this optional optimization.\n *\n * @internal\n */\nexport interface IAtomicStoreWithNonceSupport extends IAtomicStore {\n  /**\n   * Atomically assigns a nonce with gap prevention.\n   *\n   * @param key - The storage key for the last used nonce\n   * @param pendingCount - The current pending transaction count from blockchain\n   * @returns The assigned nonce\n   */\n  atomicAssignNonce(key: string, pendingCount: number): Promise<number>;\n}\n\n/**\n * Type guard to check if an atomic store supports optimized nonce assignment.\n *\n * @param store - The atomic store to check\n * @returns True if the store supports atomicAssignNonce\n *\n * @internal\n */\nexport function hasNonceSupport(\n  store: IAtomicStore,\n): store is IAtomicStoreWithNonceSupport {\n  return (\n    \"atomicAssignNonce\" in store &&\n    typeof (store as IAtomicStoreWithNonceSupport).atomicAssignNonce ===\n      \"function\"\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAqPO,SAAS,gBACd,OACuC;AACvC,SACE,uBAAuB,SACvB,OAAQ,MAAuC,sBAC7C;AAEN;","names":[]}

package/dist/types/atomicStore.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Atomic storage primitives for distributed state management.
+ *
+ * @module
+ */
+/**
+ * Interface for atomic storage operations required by the SDK's distributed components.
+ *
+ * @remarks
+ * Implementations of this interface MUST guarantee atomicity for all operations.
+ * These primitives are used by the SDK's internal components to coordinate
+ * distributed state in multi-instance deployments (e.g., serverless functions).
+ *
+ * The SDK provides a reference Redis implementation, but you can implement
+ * this interface using any storage backend that supports atomic operations:
+ * - PostgreSQL with advisory locks
+ * - DynamoDB with conditional writes
+ * - MongoDB with findAndModify
+ * - Zookeeper or etcd for coordination
+ *
+ * @example
+ * ```typescript
+ * // Using the Redis reference implementation
+ * import { RedisAtomicStore } from './lib/redisAtomicStore';
+ *
+ * const atomicStore = new RedisAtomicStore({
+ *   redis: process.env.REDIS_URL
+ * });
+ *
+ * const vana = Vana({
+ *   privateKey: process.env.RELAYER_PRIVATE_KEY,
+ *   atomicStore
+ * });
+ * ```
+ *
+ * @category Storage
+ */
+export interface IAtomicStore {
+    /**
+     * Atomically increments a counter and returns the new value.
+     *
+     * @remarks
+     * This operation MUST be atomic. If the key doesn't exist, it should be
+     * initialized to 0 before incrementing. The operation must return the
+     * value after incrementing.
+     *
+     * This is used primarily for nonce assignment where atomicity is critical
+     * to prevent conflicts under concurrent load.
+     *
+     * @param key - The key to increment
+     * @returns The new value after incrementing
+     *
+     * @example
+     * ```typescript
+     * // First call returns 1
+     * const nonce1 = await store.incr('nonce:0x123:1480');
+     * // Second call returns 2
+     * const nonce2 = await store.incr('nonce:0x123:1480');
+     * ```
+     */
+    incr(key: string): Promise<number>;
+    /**
+     * Attempts to acquire a distributed lock with automatic expiration.
+     *
+     * @remarks
+     * This operation MUST be atomic and follow the "SET NX EX" semantics:
+     * - Only succeeds if the lock doesn't exist (NX - "Not eXists")
+     * - Automatically expires after the specified TTL (EX - "EXpire")
+     * - Returns a unique lock ID on success for safe release
+     *
+     * The lock ID should be a unique value (e.g., UUID or timestamp+random)
+     * that prevents accidental release by other processes.
+     *
+     * @param key - The lock key
+     * @param ttlSeconds - Time-to-live in seconds (automatic expiration)
+     * @returns A unique lock ID if acquired, null if lock is already held
+     *
+     * @example
+     * ```typescript
+     * const lockId = await store.acquireLock('nonce:lock:0x123', 5);
+     * if (lockId) {
+     *   try {
+     *     // Critical section - only one process can be here
+     *     await performCriticalOperation();
+     *   } finally {
+     *     await store.releaseLock('nonce:lock:0x123', lockId);
+     *   }
+     * }
+     * ```
+     */
+    acquireLock(key: string, ttlSeconds: number): Promise<string | null>;
+    /**
+     * Releases a previously acquired lock.
+     *
+     * @remarks
+     * This operation MUST be atomic and safe. It should only succeed if the
+     * provided lockId matches the current lock value. This prevents accidental
+     * release of locks acquired by other processes.
+     *
+     * Implementations should use compare-and-delete semantics or a Lua script
+     * (in Redis) to ensure atomicity.
+     *
+     * @param key - The lock key
+     * @param lockId - The unique ID returned by acquireLock
+     *
+     * @example
+     * ```typescript
+     * const lockId = await store.acquireLock('lock:key', 5);
+     * if (lockId) {
+     *   // ... do work ...
+     *   await store.releaseLock('lock:key', lockId);
+     * }
+     * ```
+     */
+    releaseLock(key: string, lockId: string): Promise<void>;
+    /**
+     * Gets the value associated with a key.
+     *
+     * @remarks
+     * This is a simple read operation. It should return null if the key
+     * doesn't exist.
+     *
+     * @param key - The key to retrieve
+     * @returns The stored value, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const lastUsedNonce = await store.get('lastNonce:0x123:1480');
+     * ```
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Sets a key-value pair.
+     *
+     * @remarks
+     * This is a simple write operation. It should overwrite any existing value.
+     *
+     * @param key - The key to set
+     * @param value - The value to store
+     *
+     * @example
+     * ```typescript
+     * await store.set('lastNonce:0x123:1480', '42');
+     * ```
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Sets a key-value pair with expiration.
+     *
+     * @remarks
+     * This operation sets a value with automatic expiration after the specified TTL.
+     * Useful for temporary state that should be automatically cleaned up.
+     *
+     * @param key - The key to set
+     * @param value - The value to store
+     * @param ttlSeconds - Time-to-live in seconds
+     *
+     * @example
+     * ```typescript
+     * // Store operation state for 24 hours
+     * await store.setWithTTL('operation:123', JSON.stringify(state), 86400);
+     * ```
+     */
+    setWithTTL?(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Deletes a key.
+     *
+     * @remarks
+     * This operation removes a key from storage. Should be idempotent
+     * (no error if key doesn't exist).
+     *
+     * @param key - The key to delete
+     *
+     * @example
+     * ```typescript
+     * await store.delete('temp:data:123');
+     * ```
+     */
+    delete?(key: string): Promise<void>;
+    /**
+     * Executes an atomic script (e.g., Lua in Redis, stored procedure in SQL).
+     *
+     * @remarks
+     * This is an optional method that allows execution of atomic scripts
+     * for complex operations that require multiple steps to be atomic.
+     * Not all stores support this - simple stores may omit it.
+     *
+     * For Redis: executes a Lua script
+     * For PostgreSQL: executes a stored procedure or CTE
+     * For DynamoDB: might use TransactWrite
+     *
+     * @param script - The script to execute
+     * @param keys - Array of keys the script will operate on
+     * @param args - Array of arguments to pass to the script
+     * @returns The script's return value
+     *
+     * @example
+     * ```typescript
+     * const result = await store.eval(
+     *   'return redis.call("INCR", KEYS[1])',
+     *   ['counter:users'],
+     *   []
+     * );
+     * ```
+     */
+    eval?(script: string, keys: string[], args: string[]): Promise<any>;
+}
+/**
+ * Extended atomic store interface with nonce support.
+ *
+ * @remarks
+ * Some atomic stores (like Redis) provide optimized atomic nonce assignment
+ * through native scripting capabilities. This interface extends the base
+ * IAtomicStore with this optional optimization.
+ *
+ * @internal
+ */
+export interface IAtomicStoreWithNonceSupport extends IAtomicStore {
+    /**
+     * Atomically assigns a nonce with gap prevention.
+     *
+     * @param key - The storage key for the last used nonce
+     * @param pendingCount - The current pending transaction count from blockchain
+     * @returns The assigned nonce
+     */
+    atomicAssignNonce(key: string, pendingCount: number): Promise<number>;
+}
+/**
+ * Type guard to check if an atomic store supports optimized nonce assignment.
+ *
+ * @param store - The atomic store to check
+ * @returns True if the store supports atomicAssignNonce
+ *
+ * @internal
+ */
+export declare function hasNonceSupport(store: IAtomicStore): store is IAtomicStoreWithNonceSupport;

package/dist/types/atomicStore.js

@@ -0,0 +1,7 @@
+function hasNonceSupport(store) {
+  return "atomicAssignNonce" in store && typeof store.atomicAssignNonce === "function";
+}
+export {
+  hasNonceSupport
+};
+//# sourceMappingURL=atomicStore.js.map

package/dist/types/atomicStore.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/atomicStore.ts"],"sourcesContent":["/**\n * Atomic storage primitives for distributed state management.\n *\n * @module\n */\n\n/**\n * Interface for atomic storage operations required by the SDK's distributed components.\n *\n * @remarks\n * Implementations of this interface MUST guarantee atomicity for all operations.\n * These primitives are used by the SDK's internal components to coordinate\n * distributed state in multi-instance deployments (e.g., serverless functions).\n *\n * The SDK provides a reference Redis implementation, but you can implement\n * this interface using any storage backend that supports atomic operations:\n * - PostgreSQL with advisory locks\n * - DynamoDB with conditional writes\n * - MongoDB with findAndModify\n * - Zookeeper or etcd for coordination\n *\n * @example\n * ```typescript\n * // Using the Redis reference implementation\n * import { RedisAtomicStore } from './lib/redisAtomicStore';\n *\n * const atomicStore = new RedisAtomicStore({\n *   redis: process.env.REDIS_URL\n * });\n *\n * const vana = Vana({\n *   privateKey: process.env.RELAYER_PRIVATE_KEY,\n *   atomicStore\n * });\n * ```\n *\n * @category Storage\n */\nexport interface IAtomicStore {\n  /**\n   * Atomically increments a counter and returns the new value.\n   *\n   * @remarks\n   * This operation MUST be atomic. If the key doesn't exist, it should be\n   * initialized to 0 before incrementing. The operation must return the\n   * value after incrementing.\n   *\n   * This is used primarily for nonce assignment where atomicity is critical\n   * to prevent conflicts under concurrent load.\n   *\n   * @param key - The key to increment\n   * @returns The new value after incrementing\n   *\n   * @example\n   * ```typescript\n   * // First call returns 1\n   * const nonce1 = await store.incr('nonce:0x123:1480');\n   * // Second call returns 2\n   * const nonce2 = await store.incr('nonce:0x123:1480');\n   * ```\n   */\n  incr(key: string): Promise<number>;\n\n  /**\n   * Attempts to acquire a distributed lock with automatic expiration.\n   *\n   * @remarks\n   * This operation MUST be atomic and follow the \"SET NX EX\" semantics:\n   * - Only succeeds if the lock doesn't exist (NX - \"Not eXists\")\n   * - Automatically expires after the specified TTL (EX - \"EXpire\")\n   * - Returns a unique lock ID on success for safe release\n   *\n   * The lock ID should be a unique value (e.g., UUID or timestamp+random)\n   * that prevents accidental release by other processes.\n   *\n   * @param key - The lock key\n   * @param ttlSeconds - Time-to-live in seconds (automatic expiration)\n   * @returns A unique lock ID if acquired, null if lock is already held\n   *\n   * @example\n   * ```typescript\n   * const lockId = await store.acquireLock('nonce:lock:0x123', 5);\n   * if (lockId) {\n   *   try {\n   *     // Critical section - only one process can be here\n   *     await performCriticalOperation();\n   *   } finally {\n   *     await store.releaseLock('nonce:lock:0x123', lockId);\n   *   }\n   * }\n   * ```\n   */\n  acquireLock(key: string, ttlSeconds: number): Promise<string | null>;\n\n  /**\n   * Releases a previously acquired lock.\n   *\n   * @remarks\n   * This operation MUST be atomic and safe. It should only succeed if the\n   * provided lockId matches the current lock value. This prevents accidental\n   * release of locks acquired by other processes.\n   *\n   * Implementations should use compare-and-delete semantics or a Lua script\n   * (in Redis) to ensure atomicity.\n   *\n   * @param key - The lock key\n   * @param lockId - The unique ID returned by acquireLock\n   *\n   * @example\n   * ```typescript\n   * const lockId = await store.acquireLock('lock:key', 5);\n   * if (lockId) {\n   *   // ... do work ...\n   *   await store.releaseLock('lock:key', lockId);\n   * }\n   * ```\n   */\n  releaseLock(key: string, lockId: string): Promise<void>;\n\n  /**\n   * Gets the value associated with a key.\n   *\n   * @remarks\n   * This is a simple read operation. It should return null if the key\n   * doesn't exist.\n   *\n   * @param key - The key to retrieve\n   * @returns The stored value, or null if not found\n   *\n   * @example\n   * ```typescript\n   * const lastUsedNonce = await store.get('lastNonce:0x123:1480');\n   * ```\n   */\n  get(key: string): Promise<string | null>;\n\n  /**\n   * Sets a key-value pair.\n   *\n   * @remarks\n   * This is a simple write operation. It should overwrite any existing value.\n   *\n   * @param key - The key to set\n   * @param value - The value to store\n   *\n   * @example\n   * ```typescript\n   * await store.set('lastNonce:0x123:1480', '42');\n   * ```\n   */\n  set(key: string, value: string): Promise<void>;\n\n  /**\n   * Sets a key-value pair with expiration.\n   *\n   * @remarks\n   * This operation sets a value with automatic expiration after the specified TTL.\n   * Useful for temporary state that should be automatically cleaned up.\n   *\n   * @param key - The key to set\n   * @param value - The value to store\n   * @param ttlSeconds - Time-to-live in seconds\n   *\n   * @example\n   * ```typescript\n   * // Store operation state for 24 hours\n   * await store.setWithTTL('operation:123', JSON.stringify(state), 86400);\n   * ```\n   */\n  setWithTTL?(key: string, value: string, ttlSeconds: number): Promise<void>;\n\n  /**\n   * Deletes a key.\n   *\n   * @remarks\n   * This operation removes a key from storage. Should be idempotent\n   * (no error if key doesn't exist).\n   *\n   * @param key - The key to delete\n   *\n   * @example\n   * ```typescript\n   * await store.delete('temp:data:123');\n   * ```\n   */\n  delete?(key: string): Promise<void>;\n\n  /**\n   * Executes an atomic script (e.g., Lua in Redis, stored procedure in SQL).\n   *\n   * @remarks\n   * This is an optional method that allows execution of atomic scripts\n   * for complex operations that require multiple steps to be atomic.\n   * Not all stores support this - simple stores may omit it.\n   *\n   * For Redis: executes a Lua script\n   * For PostgreSQL: executes a stored procedure or CTE\n   * For DynamoDB: might use TransactWrite\n   *\n   * @param script - The script to execute\n   * @param keys - Array of keys the script will operate on\n   * @param args - Array of arguments to pass to the script\n   * @returns The script's return value\n   *\n   * @example\n   * ```typescript\n   * const result = await store.eval(\n   *   'return redis.call(\"INCR\", KEYS[1])',\n   *   ['counter:users'],\n   *   []\n   * );\n   * ```\n   */\n  eval?(script: string, keys: string[], args: string[]): Promise<any>;\n}\n\n/**\n * Extended atomic store interface with nonce support.\n *\n * @remarks\n * Some atomic stores (like Redis) provide optimized atomic nonce assignment\n * through native scripting capabilities. This interface extends the base\n * IAtomicStore with this optional optimization.\n *\n * @internal\n */\nexport interface IAtomicStoreWithNonceSupport extends IAtomicStore {\n  /**\n   * Atomically assigns a nonce with gap prevention.\n   *\n   * @param key - The storage key for the last used nonce\n   * @param pendingCount - The current pending transaction count from blockchain\n   * @returns The assigned nonce\n   */\n  atomicAssignNonce(key: string, pendingCount: number): Promise<number>;\n}\n\n/**\n * Type guard to check if an atomic store supports optimized nonce assignment.\n *\n * @param store - The atomic store to check\n * @returns True if the store supports atomicAssignNonce\n *\n * @internal\n */\nexport function hasNonceSupport(\n  store: IAtomicStore,\n): store is IAtomicStoreWithNonceSupport {\n  return (\n    \"atomicAssignNonce\" in store &&\n    typeof (store as IAtomicStoreWithNonceSupport).atomicAssignNonce ===\n      \"function\"\n  );\n}\n"],"mappings":"AAqPO,SAAS,gBACd,OACuC;AACvC,SACE,uBAAuB,SACvB,OAAQ,MAAuC,sBAC7C;AAEN;","names":[]}