@opendatalabs/vana-sdk 0.1.0-alpha.fd33fc9 → 2.0.0

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":"AAAA;AAAA,EACE;AAAA,OAMK;AAiGA,MAAM,cAAyC;AAAA,EAIpD,YAAoB,QAAsB;AAAtB;AAClB,SAAK,aAAa,OAAO,cAAc;AACvC,QAAI,CAAC,OAAO,KAAK;AACf,YAAM,IAAI;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA,EAZiB,SAAS;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAuCjB,MAAM,OAAO,MAAY,UAAiD;AACxE,QAAI;AACF,YAAM,WAAW,YAAY,aAAa,KAAK,IAAI,CAAC;AAGpD,YAAM,WAAW,IAAI,SAAS;AAC9B,eAAS,OAAO,QAAQ,MAAM,QAAQ;AAGtC,YAAM,WAAW;AAAA,QACf,MAAM;AAAA,QACN,WAAW;AAAA,UACT,YAAY;AAAA,UACZ,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,QACpC;AAAA,MACF;AACA,eAAS,OAAO,kBAAkB,KAAK,UAAU,QAAQ,CAAC;AAG1D,YAAM,WAAW,MAAM,MAAM,GAAG,KAAK,MAAM,0BAA0B;AAAA,QACnE,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,eAAe,UAAU,KAAK,OAAO,GAAG;AAAA,QAC1C;AAAA,QACA,MAAM;AAAA,MACR,CAAC;AAED,UAAI,CAAC,SAAS,IAAI;AAChB,cAAM,YAAY,MAAM,SAAS,KAAK;AACtC,cAAM,IAAI;AAAA,UACR,yBAAyB,SAAS;AAAA,UAClC;AAAA,UACA;AAAA,QACF;AAAA,MACF;AAEA,YAAM,SAAU,MAAM,SAAS,KAAK;AACpC,YAAM,WAAW,OAAO;AAExB,UAAI,CAAC,UAAU;AACb,cAAM,IAAI;AAAA,UACR;AAAA,UACA;AAAA,UACA;AAAA,QACF;AAAA,MACF;AAEA,aAAO;AAAA,QACL,KAAK,UAAU,QAAQ;AAAA,QACvB,MAAM,KAAK;AAAA,QACX,aAAa,KAAK,QAAQ;AAAA,MAC5B;AAAA,IACF,SAAS,OAAO;AACd,UAAI,iBAAiB,cAAc;AACjC,cAAM;AAAA,MACR;AACA,YAAM,IAAI;AAAA,QACR,wBAAwB,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,QAChF;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,SAAS,KAA4B;AACzC,QAAI;AAEF,UAAI,CAAC,KAAK,WAAW,GAAG,GAAG;AACzB,cAAM,IAAI;AAAA,UACR;AAAA,UACA;AAAA,UACA;AAAA,QACF;AAAA,MACF;AAGA,YAAM,cAAc,GAAG,KAAK,UAAU,SAAS,GAAG;AAClD,YAAM,WAAW,MAAM,MAAM,WAAW;AAExC,UAAI,CAAC,SAAS,IAAI;AAChB,cAAM,IAAI;AAAA,UACR,iCAAiC,SAAS,UAAU;AAAA,UACpD;AAAA,UACA;AAAA,QACF;AAAA,MACF;AAEA,aAAO,MAAM,SAAS,KAAK;AAAA,IAC7B,SAAS,OAAO;AACd,UAAI,iBAAiB,cAAc;AACjC,cAAM;AAAA,MACR;AACA,YAAM,IAAI;AAAA,QACR,0BAA0B,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,QAClF;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkCA,MAAM,KAAK,SAAsD;AAC/D,QAAI;AACF,YAAM,SAAS,IAAI,gBAAgB;AAAA,QACjC,QAAQ;AAAA,QACR,YAAY,SAAS,SAAS,IAAI,SAAS;AAAA,QAC3C,UAAU,KAAK,UAAU;AAAA,UACvB,WAAW;AAAA,YACT,YAAY;AAAA,UACd;AAAA,QACF,CAAC;AAAA,MACH,CAAC;AAED,UAAI,SAAS,QAAQ;AACnB,eAAO,IAAI,cAAc,QAAQ,OAAO,SAAS,CAAC;AAAA,MACpD;AAEA,UAAI,SAAS,aAAa;AACxB,eAAO,IAAI,kBAAkB,QAAQ,WAAW;AAAA,MAClD;AAEA,YAAM,WAAW,MAAM,MAAM,GAAG,KAAK,MAAM,iBAAiB,MAAM,IAAI;AAAA,QACpE,SAAS;AAAA,UACP,eAAe,UAAU,KAAK,OAAO,GAAG;AAAA,QAC1C;AAAA,MACF,CAAC;AAED,UAAI,CAAC,SAAS,IAAI;AAChB,cAAM,YAAY,MAAM,SAAS,KAAK;AACtC,cAAM,IAAI;AAAA,UACR,gCAAgC,SAAS;AAAA,UACzC;AAAA,UACA;AAAA,QACF;AAAA,MACF;AAEA,YAAM,SAAU,MAAM,SAAS,KAAK;AAEpC,aAAO,OAAO,KAAK,IAAI,CAAC,SAAS;AAAA,QAC/B,IAAI,IAAI;AAAA,QACR,MAAM,IAAI,UAAU,QAAQ;AAAA,QAC5B,KAAK,UAAU,IAAI,aAAa;AAAA,QAChC,MAAM,SAAS,OAAO,IAAI,IAAI,GAAG,EAAE,KAAK;AAAA,QACxC,aAAa;AAAA;AAAA,QACb,WAAW,IAAI,KAAK,IAAI,WAAW;AAAA,QACnC,UAAU,IAAI,UAAU,aAAa,CAAC;AAAA,MACxC,EAAE;AAAA,IACJ,SAAS,OAAO;AACd,UAAI,iBAAiB,cAAc;AACjC,cAAM;AAAA,MACR;AACA,YAAM,IAAI;AAAA,QACR,sBAAsB,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,QAC9E;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA8BA,MAAM,OAAO,KAA+B;AAC1C,QAAI;AAEF,YAAM,MAAM,KAAK,kBAAkB,GAAG;AAGtC,UAAI,CAAC,KAAK,WAAW,GAAG,GAAG;AACzB,cAAM,IAAI;AAAA,UACR;AAAA,UACA;AAAA,UACA;AAAA,QACF;AAAA,MACF;AAEA,YAAM,WAAW,MAAM,MAAM,GAAG,KAAK,MAAM,kBAAkB,GAAG,IAAI;AAAA,QAClE,QAAQ;AAAA,QACR,SAAS;AAAA,UACP,eAAe,UAAU,KAAK,OAAO,GAAG;AAAA,QAC1C;AAAA,MACF,CAAC;AAED,UAAI,CAAC,SAAS,IAAI;AAChB,cAAM,YAAY,MAAM,SAAS,KAAK;AACtC,cAAM,IAAI;AAAA,UACR,iCAAiC,SAAS;AAAA,UAC1C;AAAA,UACA;AAAA,QACF;AAAA,MACF;AAEA,aAAO;AAAA,IACT,SAAS,OAAO;AACd,UAAI,iBAAiB,cAAc;AACjC,cAAM;AAAA,MACR;AACA,YAAM,IAAI;AAAA,QACR,wBAAwB,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,QAChF;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA,EAEA,YAAmC;AACjC,WAAO;AAAA,MACL,MAAM;AAAA,MACN,MAAM;AAAA,MACN,cAAc;AAAA,MACd,UAAU;AAAA,QACR,QAAQ;AAAA,QACR,UAAU;AAAA,QACV,MAAM;AAAA,QACN,QAAQ;AAAA,MACV;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQQ,kBAAkB,KAAqB;AAE7C,QAAI,CAAC,IAAI,SAAS,GAAG,GAAG;AACtB,aAAO;AAAA,IACT;AAGA,UAAM,WAAW,IAAI,MAAM,wBAAwB;AACnD,QAAI,UAAU;AACZ,aAAO,SAAS,CAAC;AAAA,IACnB;AAGA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQQ,WAAW,KAAsB;AAEvC,WACE,qBAAqB,KAAK,GAAG,MAC5B,IAAI,WAAW,IAAI,KAAK,IAAI,WAAW,IAAI,KAAK,IAAI,SAAS,MAAM;AAAA,EAExE;AACF;","names":[]}

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

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

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

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

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":[]}

package/dist/types/blockchain.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/blockchain.ts"],"sourcesContent":["/**\n * Core blockchain types for the Vana SDK\n */\n\nimport type { Hash, Address } from \"viem\";\n\n/**\n * Represents a transaction that has been submitted to the blockchain\n * This is what contract calls return before confirmation\n */\nexport interface TransactionRequest {\n  /** Transaction hash */\n  hash: Hash;\n  /** Account that initiated the transaction */\n  from: Address;\n  /** Contract that was called */\n  contractName: string;\n  /** Function that was called */\n  functionName: string;\n  /** Function arguments (for debugging/logging) */\n  args?: readonly unknown[];\n}\n\n/**\n * Options for waiting for transaction confirmation\n */\nexport interface TransactionWaitOptions {\n  /** Number of confirmations to wait for (default: 1) */\n  confirmations?: number;\n  /** Timeout in milliseconds (default: 30000) */\n  timeout?: number;\n  /** Polling interval in milliseconds (default: 4000) */\n  pollingInterval?: number;\n}\n\n/**\n * Base result for all confirmed transactions\n */\nexport interface TransactionResult {\n  /** Transaction hash */\n  transactionHash: Hash;\n  /** Block number where transaction was included */\n  blockNumber: bigint;\n  /** Gas used by the transaction */\n  gasUsed: bigint;\n  /** Account that initiated the transaction */\n  from: Address;\n  /** Contract that was called */\n  contractName: string;\n  /** Function that was called */\n  functionName: string;\n}\n\n/**\n * Event arguments are dynamically typed based on the contract mappings.\n * The parseTransaction function will:\n * 1. Return expectedEvents with typed args for mapped functions\n * 2. Return allEvents with all parsed events from the transaction\n *\n * This approach avoids the need for specific result interfaces per event type,\n * letting the mapping file drive the types instead.\n */\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/types/blockchain.ts"],"sourcesContent":["/**\n * Defines core blockchain interaction types.\n *\n * @remarks\n * This module provides fundamental types for blockchain transactions,\n * including transaction requests, confirmation options, and results.\n * These types form the basis for all blockchain interactions in the SDK.\n *\n * @category Types\n * @module types/blockchain\n */\n\nimport type { Hash, Address } from \"viem\";\n\n/**\n * Represents a submitted blockchain transaction awaiting confirmation.\n *\n * @remarks\n * Returned immediately after transaction submission, before confirmation.\n * Use `waitForTransactionEvents` to wait for confirmation and retrieve events.\n *\n * @category Blockchain\n */\nexport interface TransactionRequest {\n  /** Transaction hash */\n  hash: Hash;\n  /** Account that initiated the transaction */\n  from: Address;\n  /** Contract that was called */\n  contractName: string;\n  /** Function that was called */\n  functionName: string;\n  /** Function arguments (for debugging/logging) */\n  args?: readonly unknown[];\n}\n\n/**\n * Configures transaction confirmation waiting behavior.\n *\n * @remarks\n * Controls how long and how often to check for transaction confirmation.\n * Adjust based on network congestion and application requirements.\n *\n * @category Blockchain\n */\nexport interface TransactionWaitOptions {\n  /** Number of confirmations to wait for (default: 1) */\n  confirmations?: number;\n  /** Timeout in milliseconds (default: 30000) */\n  timeout?: number;\n  /** Polling interval in milliseconds (default: 4000) */\n  pollingInterval?: number;\n}\n\n/**\n * Represents a confirmed blockchain transaction with metadata.\n *\n * @remarks\n * Contains essential transaction information after confirmation including\n * gas usage, block number, and function details. Extended by specific\n * result types with parsed events.\n *\n * @category Blockchain\n */\nexport interface TransactionResult {\n  /** Transaction hash */\n  transactionHash: Hash;\n  /** Block number where transaction was included */\n  blockNumber: bigint;\n  /** Gas used by the transaction */\n  gasUsed: bigint;\n  /** Account that initiated the transaction */\n  from: Address;\n  /** Contract that was called */\n  contractName: string;\n  /** Function that was called */\n  functionName: string;\n}\n\n/**\n * @remarks\n * Event typing strategy:\n * - Event arguments are dynamically typed based on contract mappings\n * - `parseTransaction` returns `expectedEvents` with typed args for mapped functions\n * - `allEvents` contains all parsed events from the transaction\n * - This approach lets the mapping file drive types rather than requiring\n *   specific result interfaces per event type\n *\n * @internal\n */\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types/blockchain.d.ts

@@ -1,10 +1,23 @@
 /**
- * Core blockchain types for the Vana SDK
+ * Defines core blockchain interaction types.
+ *
+ * @remarks
+ * This module provides fundamental types for blockchain transactions,
+ * including transaction requests, confirmation options, and results.
+ * These types form the basis for all blockchain interactions in the SDK.
+ *
+ * @category Types
+ * @module types/blockchain
  */
 import type { Hash, Address } from "viem";
 /**
- * Represents a transaction that has been submitted to the blockchain
- * This is what contract calls return before confirmation
+ * Represents a submitted blockchain transaction awaiting confirmation.
+ *
+ * @remarks
+ * Returned immediately after transaction submission, before confirmation.
+ * Use `waitForTransactionEvents` to wait for confirmation and retrieve events.
+ *
+ * @category Blockchain
  */
 export interface TransactionRequest {
     /** Transaction hash */
@@ -19,7 +32,13 @@ export interface TransactionRequest {
     args?: readonly unknown[];
 }
 /**
- * Options for waiting for transaction confirmation
+ * Configures transaction confirmation waiting behavior.
+ *
+ * @remarks
+ * Controls how long and how often to check for transaction confirmation.
+ * Adjust based on network congestion and application requirements.
+ *
+ * @category Blockchain
  */
 export interface TransactionWaitOptions {
     /** Number of confirmations to wait for (default: 1) */
@@ -30,7 +49,14 @@ export interface TransactionWaitOptions {
     pollingInterval?: number;
 }
 /**
- * Base result for all confirmed transactions
+ * Represents a confirmed blockchain transaction with metadata.
+ *
+ * @remarks
+ * Contains essential transaction information after confirmation including
+ * gas usage, block number, and function details. Extended by specific
+ * result types with parsed events.
+ *
+ * @category Blockchain
  */
 export interface TransactionResult {
     /** Transaction hash */
@@ -47,11 +73,13 @@ export interface TransactionResult {
     functionName: string;
 }
 /**
- * Event arguments are dynamically typed based on the contract mappings.
- * The parseTransaction function will:
- * 1. Return expectedEvents with typed args for mapped functions
- * 2. Return allEvents with all parsed events from the transaction
+ * @remarks
+ * Event typing strategy:
+ * - Event arguments are dynamically typed based on contract mappings
+ * - `parseTransaction` returns `expectedEvents` with typed args for mapped functions
+ * - `allEvents` contains all parsed events from the transaction
+ * - This approach lets the mapping file drive types rather than requiring
+ *   specific result interfaces per event type
  *
- * This approach avoids the need for specific result interfaces per event type,
- * letting the mapping file drive the types instead.
+ * @internal
  */

package/dist/types/chains.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/chains.ts"],"sourcesContent":["import type { Chain } from \"viem\";\n\n/**\n * Supported Vana chain IDs\n */\nexport type VanaChainId = 14800 | 1480;\n\n/**\n * Supported Vana chains\n */\nexport type VanaChain = Chain & {\n  id: VanaChainId;\n};\n\n/**\n * Chain configuration mapping\n */\nexport type ChainConfig = {\n  [K in VanaChainId]: VanaChain;\n};\n\n/**\n * Type guard to check if a chain ID is supported\n *\n * @param chainId - The chain ID to validate\n * @returns True if the chain ID is a supported Vana chain ID\n */\nexport function isVanaChainId(chainId: number): chainId is VanaChainId {\n  return chainId === 14800 || chainId === 1480;\n}\n\n/**\n * Type guard to check if a chain is a Vana chain\n *\n * @param chain - The chain object to validate\n * @returns True if the chain is a supported Vana chain\n */\nexport function isVanaChain(chain: Chain): chain is VanaChain {\n  return isVanaChainId(chain.id);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA2BO,SAAS,cAAc,SAAyC;AACrE,SAAO,YAAY,SAAS,YAAY;AAC1C;AAQO,SAAS,YAAY,OAAkC;AAC5D,SAAO,cAAc,MAAM,EAAE;AAC/B;","names":[]}
+{"version":3,"sources":["../../src/types/chains.ts"],"sourcesContent":["import type { Chain } from \"viem\";\n\n/**\n * Represents the supported Vana network chain identifiers.\n *\n * @remarks\n * The Vana protocol operates on two primary networks:\n * - `14800`: Moksha testnet for development and testing\n * - `1480`: Vana mainnet for production deployment\n *\n * Use these chain IDs when configuring the SDK or checking network compatibility.\n *\n * @category Blockchain\n * @see {@link https://docs.vana.org/docs/networks | Network Documentation}\n */\nexport type VanaChainId = 14800 | 1480;\n\n/**\n * Extends viem's Chain type with Vana-specific chain constraints.\n *\n * @remarks\n * Ensures type safety for Vana-specific chains by restricting the chain ID\n * to supported networks. This type provides full viem Chain compatibility\n * while guaranteeing the chain is a valid Vana network.\n *\n * @category Blockchain\n */\nexport type VanaChain = Chain & {\n  id: VanaChainId;\n};\n\n/**\n * Maps Vana chain IDs to their complete chain configurations.\n *\n * @remarks\n * Provides type-safe access to chain configurations indexed by chain ID.\n * Use this for dynamic chain selection based on runtime chain ID values.\n *\n * @category Blockchain\n * @example\n * ```typescript\n * const configs: ChainConfig = {\n *   14800: mokshaTestnet,\n *   1480: vanaMainnet\n * };\n * const chain = configs[chainId];\n * ```\n */\nexport type ChainConfig = {\n  [K in VanaChainId]: VanaChain;\n};\n\n/**\n * Validates whether a chain ID represents a supported Vana network.\n *\n * @remarks\n * Type guard for runtime validation of chain IDs from external sources.\n * Use when accepting user input or processing network configurations.\n *\n * @param chainId - The chain ID to validate\n * @returns `true` if the chain ID is a supported Vana network, `false` otherwise\n *\n * @example\n * ```typescript\n * const chainId = parseInt(process.env.CHAIN_ID);\n *\n * if (!isVanaChainId(chainId)) {\n *   throw new Error(`Unsupported chain ID: ${chainId}`);\n * }\n *\n * // TypeScript now knows chainId is VanaChainId\n * const config = getChainConfig(chainId);\n * ```\n *\n * @category Blockchain\n */\nexport function isVanaChainId(chainId: number): chainId is VanaChainId {\n  return chainId === 14800 || chainId === 1480;\n}\n\n/**\n * Validates whether a Chain object represents a supported Vana network.\n *\n * @remarks\n * Type guard for validating viem Chain objects as Vana chains.\n * Ensures both type safety and runtime validation for chain compatibility.\n *\n * @param chain - The chain object to validate\n * @returns `true` if the chain is a supported Vana network, `false` otherwise\n *\n * @example\n * ```typescript\n * import { mainnet, mokshaTestnet } from 'viem/chains';\n *\n * if (isVanaChain(chain)) {\n *   // TypeScript knows this is a VanaChain\n *   console.log(`Connected to Vana network: ${chain.id}`);\n * } else {\n *   console.error('Please connect to a Vana network');\n * }\n * ```\n *\n * @category Blockchain\n */\nexport function isVanaChain(chain: Chain): chain is VanaChain {\n  return isVanaChainId(chain.id);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA4EO,SAAS,cAAc,SAAyC;AACrE,SAAO,YAAY,SAAS,YAAY;AAC1C;AA0BO,SAAS,YAAY,OAAkC;AAC5D,SAAO,cAAc,MAAM,EAAE;AAC/B;","names":[]}