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

package/dist/utils/ipfs.cjs

@@ -30,12 +30,10 @@ __export(ipfs_exports, {
 module.exports = __toCommonJS(ipfs_exports);
 const DEFAULT_IPFS_GATEWAY = "https://dweb.link/ipfs/";
 const IPFS_GATEWAYS = [
-  "https://dweb.link/ipfs/",
-  // Interplanetary Shipyard - highly reliable
   "https://ipfs.io/ipfs/",
   // IPFS Foundation - reliable
-  "https://cloudflare-ipfs.com/ipfs/",
-  // Cloudflare - good performance
+  "https://dweb.link/ipfs/",
+  // Interplanetary Shipyard - observed to be having issues
   "https://gateway.pinata.cloud/ipfs/",
   // Pinata - backup option (has rate limits)
   "https://ipfs.filebase.io/ipfs/"

package/dist/utils/ipfs.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/ipfs.ts"],"sourcesContent":["/**\n * IPFS URL utilities for the Vana SDK\n *\n * Centralized functions for handling IPFS URLs, converting them to gateway URLs,\n * and extracting IPFS hashes from various URL formats.\n */\n\n/**\n * Default IPFS gateway URL\n */\nexport const DEFAULT_IPFS_GATEWAY = \"https://dweb.link/ipfs/\";\n\n/**\n * Alternative IPFS gateways for fallback - ordered by reliability and rate limits\n */\nexport const IPFS_GATEWAYS = [\n  \"https://dweb.link/ipfs/\", // Interplanetary Shipyard - highly reliable\n  \"https://ipfs.io/ipfs/\", // IPFS Foundation - reliable\n  \"https://cloudflare-ipfs.com/ipfs/\", // Cloudflare - good performance\n  \"https://gateway.pinata.cloud/ipfs/\", // Pinata - backup option (has rate limits)\n  \"https://ipfs.filebase.io/ipfs/\", // Filebase - emerging reliable option\n] as const;\n\n/**\n * Check if a URL is an IPFS URL (starts with ipfs://)\n *\n * @param url - The URL to check\n * @returns True if the URL is an IPFS URL\n */\nexport function isIpfsUrl(url: string): boolean {\n  return url.startsWith(\"ipfs://\");\n}\n\n/**\n * Convert an IPFS URL to an HTTP gateway URL\n *\n * @param url - The IPFS URL to convert (e.g., \"ipfs://QmHash...\")\n * @param gateway - Optional gateway URL (defaults to DEFAULT_IPFS_GATEWAY)\n * @returns The HTTP gateway URL or original URL if not an IPFS URL\n * @example\n * ```ts\n * convertIpfsUrl(\"ipfs://QmHash123\")\n * // Returns: \"https://ipfs.io/ipfs/QmHash123\"\n *\n * convertIpfsUrl(\"ipfs://QmHash123\", \"https://gateway.pinata.cloud/ipfs/\")\n * // Returns: \"https://gateway.pinata.cloud/ipfs/QmHash123\"\n * ```\n */\nexport function convertIpfsUrl(\n  url: string,\n  gateway: string = DEFAULT_IPFS_GATEWAY,\n): string {\n  if (isIpfsUrl(url)) {\n    const hash = url.replace(\"ipfs://\", \"\");\n    return `${gateway}${hash}`;\n  }\n  return url;\n}\n\n/**\n * Extract IPFS hash from various URL formats\n *\n * **Edge Cases:**\n * - Returns null for non-IPFS URLs or malformed hashes\n * - Handles both CIDv0 (starts with Qm) and CIDv1 formats\n * - Minimum 46 characters required for standalone hash detection\n * - Gateway paths with subdirectories are not supported\n *\n * @param url - The URL to extract hash from\n * @returns The IPFS hash or null if not found\n * @example\n * ```ts\n * extractIpfsHash(\"ipfs://QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"https://gateway.pinata.cloud/ipfs/QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"QmHash123456789012345678901234567890123456\") // Returns: \"QmHash123456789012345678901234567890123456\"\n * extractIpfsHash(\"https://example.com/file.json\") // Returns: null (not IPFS)\n * extractIpfsHash(\"ipfs://QmHash/subdirectory\") // Returns: null (subdirectories not supported)\n * ```\n */\nexport function extractIpfsHash(url: string): string | null {\n  // Handle various IPFS URL formats\n  const patterns = [\n    /ipfs\\/([a-zA-Z0-9]+)/, // https://gateway.pinata.cloud/ipfs/HASH\n    /^ipfs:\\/\\/([a-zA-Z0-9]+)$/, // ipfs://HASH\n    /^([a-zA-Z0-9]{46,})$/, // Just the hash (46+ chars for IPFS hashes)\n  ];\n\n  for (const pattern of patterns) {\n    const match = url.match(pattern);\n    if (match) {\n      return match[1];\n    }\n  }\n\n  return null;\n}\n\n/**\n * Get multiple gateway URLs for an IPFS hash (useful for fallback)\n *\n * @param hash - The IPFS hash\n * @returns Array of gateway URLs\n */\nexport function getGatewayUrls(hash: string): string[] {\n  return IPFS_GATEWAYS.map((gateway) => `${gateway}${hash}`);\n}\n\n/**\n * Convert an IPFS URL to multiple gateway URLs for fallback\n *\n * @param url - The IPFS URL\n * @returns Array of gateway URLs or original URL if not IPFS\n */\nexport function convertIpfsUrlWithFallbacks(url: string): string[] {\n  const hash = extractIpfsHash(url);\n  if (hash) {\n    return getGatewayUrls(hash);\n  }\n  return [url];\n}\n\n/**\n * Fetch content from IPFS with automatic gateway fallbacks\n *\n * **Edge Cases:**\n * - Non-IPFS URLs are fetched directly without fallback\n * - 10-second timeout per gateway attempt to prevent hanging\n * - Rate-limited gateways (429) are skipped immediately\n * - Exponential backoff between retries (1s, 2s, 3s, etc.)\n * - AbortSignal in options is merged with timeout signal\n *\n * @param url - The IPFS URL to fetch\n * @param options - Optional fetch options\n * @returns Promise resolving to Response object\n * @throws Error if all gateways fail\n */\nexport async function fetchWithFallbacks(\n  url: string,\n  options?: RequestInit,\n): Promise<Response> {\n  const hash = extractIpfsHash(url);\n  if (!hash) {\n    // Not an IPFS URL, fetch directly\n    return fetch(url, options);\n  }\n\n  const gatewayUrls = getGatewayUrls(hash);\n  let lastError: Error | null = null;\n\n  for (let i = 0; i < gatewayUrls.length; i++) {\n    const gatewayUrl = gatewayUrls[i];\n    try {\n      const response = await fetch(gatewayUrl, {\n        ...options,\n        // Add timeout to avoid hanging on slow gateways\n        signal: AbortSignal.timeout(10000), // 10 second timeout\n      });\n\n      // If response is ok, return it\n      if (response.ok) {\n        return response;\n      }\n\n      // If rate limited (429), try next gateway immediately\n      if (response.status === 429) {\n        lastError = new Error(`Gateway rate limited: ${gatewayUrl}`);\n        continue;\n      }\n\n      // For other HTTP errors, still try next gateway\n      lastError = new Error(`Gateway error ${response.status}: ${gatewayUrl}`);\n    } catch (error) {\n      lastError = error instanceof Error ? error : new Error(String(error));\n\n      // For rate limiting or timeout errors, continue to next gateway\n      if (\n        lastError.message.includes(\"429\") ||\n        lastError.name === \"TimeoutError\"\n      ) {\n        continue;\n      }\n    }\n\n    // Add delay between retries (except for last attempt)\n    if (i < gatewayUrls.length - 1) {\n      await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1))); // Exponential backoff\n    }\n  }\n\n  throw new Error(\n    `All IPFS gateways failed for hash ${hash}. Last error: ${lastError?.message}`,\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUO,MAAM,uBAAuB;AAK7B,MAAM,gBAAgB;AAAA,EAC3B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAQO,SAAS,UAAU,KAAsB;AAC9C,SAAO,IAAI,WAAW,SAAS;AACjC;AAiBO,SAAS,eACd,KACA,UAAkB,sBACV;AACR,MAAI,UAAU,GAAG,GAAG;AAClB,UAAM,OAAO,IAAI,QAAQ,WAAW,EAAE;AACtC,WAAO,GAAG,OAAO,GAAG,IAAI;AAAA,EAC1B;AACA,SAAO;AACT;AAsBO,SAAS,gBAAgB,KAA4B;AAE1D,QAAM,WAAW;AAAA,IACf;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,EACF;AAEA,aAAW,WAAW,UAAU;AAC9B,UAAM,QAAQ,IAAI,MAAM,OAAO;AAC/B,QAAI,OAAO;AACT,aAAO,MAAM,CAAC;AAAA,IAChB;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,eAAe,MAAwB;AACrD,SAAO,cAAc,IAAI,CAAC,YAAY,GAAG,OAAO,GAAG,IAAI,EAAE;AAC3D;AAQO,SAAS,4BAA4B,KAAuB;AACjE,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,MAAM;AACR,WAAO,eAAe,IAAI;AAAA,EAC5B;AACA,SAAO,CAAC,GAAG;AACb;AAiBA,eAAsB,mBACpB,KACA,SACmB;AACnB,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,CAAC,MAAM;AAET,WAAO,MAAM,KAAK,OAAO;AAAA,EAC3B;AAEA,QAAM,cAAc,eAAe,IAAI;AACvC,MAAI,YAA0B;AAE9B,WAAS,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;AAC3C,UAAM,aAAa,YAAY,CAAC;AAChC,QAAI;AACF,YAAM,WAAW,MAAM,MAAM,YAAY;AAAA,QACvC,GAAG;AAAA;AAAA,QAEH,QAAQ,YAAY,QAAQ,GAAK;AAAA;AAAA,MACnC,CAAC;AAGD,UAAI,SAAS,IAAI;AACf,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,WAAW,KAAK;AAC3B,oBAAY,IAAI,MAAM,yBAAyB,UAAU,EAAE;AAC3D;AAAA,MACF;AAGA,kBAAY,IAAI,MAAM,iBAAiB,SAAS,MAAM,KAAK,UAAU,EAAE;AAAA,IACzE,SAAS,OAAO;AACd,kBAAY,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAGpE,UACE,UAAU,QAAQ,SAAS,KAAK,KAChC,UAAU,SAAS,gBACnB;AACA;AAAA,MACF;AAAA,IACF;AAGA,QAAI,IAAI,YAAY,SAAS,GAAG;AAC9B,YAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,OAAQ,IAAI,EAAE,CAAC;AAAA,IACpE;AAAA,EACF;AAEA,QAAM,IAAI;AAAA,IACR,qCAAqC,IAAI,iBAAiB,WAAW,OAAO;AAAA,EAC9E;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/ipfs.ts"],"sourcesContent":["/**\n * IPFS URL utilities for the Vana SDK\n *\n * Centralized functions for handling IPFS URLs, converting them to gateway URLs,\n * and extracting IPFS hashes from various URL formats.\n */\n\n/**\n * Default IPFS gateway URL\n */\nexport const DEFAULT_IPFS_GATEWAY = \"https://dweb.link/ipfs/\";\n\n/**\n * Alternative IPFS gateways for fallback - ordered by reliability and rate limits\n */\nexport const IPFS_GATEWAYS = [\n  \"https://ipfs.io/ipfs/\", // IPFS Foundation - reliable\n  \"https://dweb.link/ipfs/\", // Interplanetary Shipyard - observed to be having issues\n  \"https://gateway.pinata.cloud/ipfs/\", // Pinata - backup option (has rate limits)\n  \"https://ipfs.filebase.io/ipfs/\", // Filebase - emerging reliable option\n] as const;\n\n/**\n * Check if a URL is an IPFS URL (starts with ipfs://)\n *\n * @param url - The URL to check\n * @returns True if the URL is an IPFS URL\n */\nexport function isIpfsUrl(url: string): boolean {\n  return url.startsWith(\"ipfs://\");\n}\n\n/**\n * Convert an IPFS URL to an HTTP gateway URL\n *\n * @param url - The IPFS URL to convert (e.g., \"ipfs://QmHash...\")\n * @param gateway - Optional gateway URL (defaults to DEFAULT_IPFS_GATEWAY)\n * @returns The HTTP gateway URL or original URL if not an IPFS URL\n * @example\n * ```ts\n * convertIpfsUrl(\"ipfs://QmHash123\")\n * // Returns: \"https://ipfs.io/ipfs/QmHash123\"\n *\n * convertIpfsUrl(\"ipfs://QmHash123\", \"https://gateway.pinata.cloud/ipfs/\")\n * // Returns: \"https://gateway.pinata.cloud/ipfs/QmHash123\"\n * ```\n */\nexport function convertIpfsUrl(\n  url: string,\n  gateway: string = DEFAULT_IPFS_GATEWAY,\n): string {\n  if (isIpfsUrl(url)) {\n    const hash = url.replace(\"ipfs://\", \"\");\n    return `${gateway}${hash}`;\n  }\n  return url;\n}\n\n/**\n * Extract IPFS hash from various URL formats\n *\n * **Edge Cases:**\n * - Returns null for non-IPFS URLs or malformed hashes\n * - Handles both CIDv0 (starts with Qm) and CIDv1 formats\n * - Minimum 46 characters required for standalone hash detection\n * - Gateway paths with subdirectories are not supported\n *\n * @param url - The URL to extract hash from\n * @returns The IPFS hash or null if not found\n * @example\n * ```ts\n * extractIpfsHash(\"ipfs://QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"https://gateway.pinata.cloud/ipfs/QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"QmHash123456789012345678901234567890123456\") // Returns: \"QmHash123456789012345678901234567890123456\"\n * extractIpfsHash(\"https://example.com/file.json\") // Returns: null (not IPFS)\n * extractIpfsHash(\"ipfs://QmHash/subdirectory\") // Returns: null (subdirectories not supported)\n * ```\n */\nexport function extractIpfsHash(url: string): string | null {\n  // Handle various IPFS URL formats\n  const patterns = [\n    /ipfs\\/([a-zA-Z0-9]+)/, // https://gateway.pinata.cloud/ipfs/HASH\n    /^ipfs:\\/\\/([a-zA-Z0-9]+)$/, // ipfs://HASH\n    /^([a-zA-Z0-9]{46,})$/, // Just the hash (46+ chars for IPFS hashes)\n  ];\n\n  for (const pattern of patterns) {\n    const match = url.match(pattern);\n    if (match) {\n      return match[1];\n    }\n  }\n\n  return null;\n}\n\n/**\n * Get multiple gateway URLs for an IPFS hash (useful for fallback)\n *\n * @param hash - The IPFS hash\n * @returns Array of gateway URLs\n */\nexport function getGatewayUrls(hash: string): string[] {\n  return IPFS_GATEWAYS.map((gateway) => `${gateway}${hash}`);\n}\n\n/**\n * Convert an IPFS URL to multiple gateway URLs for fallback\n *\n * @param url - The IPFS URL\n * @returns Array of gateway URLs or original URL if not IPFS\n */\nexport function convertIpfsUrlWithFallbacks(url: string): string[] {\n  const hash = extractIpfsHash(url);\n  if (hash) {\n    return getGatewayUrls(hash);\n  }\n  return [url];\n}\n\n/**\n * Fetch content from IPFS with automatic gateway fallbacks\n *\n * **Edge Cases:**\n * - Non-IPFS URLs are fetched directly without fallback\n * - 10-second timeout per gateway attempt to prevent hanging\n * - Rate-limited gateways (429) are skipped immediately\n * - Exponential backoff between retries (1s, 2s, 3s, etc.)\n * - AbortSignal in options is merged with timeout signal\n *\n * @param url - The IPFS URL to fetch\n * @param options - Optional fetch options\n * @returns Promise resolving to Response object\n * @throws Error if all gateways fail\n */\nexport async function fetchWithFallbacks(\n  url: string,\n  options?: RequestInit,\n): Promise<Response> {\n  const hash = extractIpfsHash(url);\n  if (!hash) {\n    // Not an IPFS URL, fetch directly\n    return fetch(url, options);\n  }\n\n  const gatewayUrls = getGatewayUrls(hash);\n  let lastError: Error | null = null;\n\n  for (let i = 0; i < gatewayUrls.length; i++) {\n    const gatewayUrl = gatewayUrls[i];\n    try {\n      const response = await fetch(gatewayUrl, {\n        ...options,\n        // Add timeout to avoid hanging on slow gateways\n        signal: AbortSignal.timeout(10000), // 10 second timeout\n      });\n\n      // If response is ok, return it\n      if (response.ok) {\n        return response;\n      }\n\n      // If rate limited (429), try next gateway immediately\n      if (response.status === 429) {\n        lastError = new Error(`Gateway rate limited: ${gatewayUrl}`);\n        continue;\n      }\n\n      // For other HTTP errors, still try next gateway\n      lastError = new Error(`Gateway error ${response.status}: ${gatewayUrl}`);\n    } catch (error) {\n      lastError = error instanceof Error ? error : new Error(String(error));\n\n      // For rate limiting or timeout errors, continue to next gateway\n      if (\n        lastError.message.includes(\"429\") ||\n        lastError.name === \"TimeoutError\"\n      ) {\n        continue;\n      }\n    }\n\n    // Add delay between retries (except for last attempt)\n    if (i < gatewayUrls.length - 1) {\n      await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1))); // Exponential backoff\n    }\n  }\n\n  throw new Error(\n    `All IPFS gateways failed for hash ${hash}. Last error: ${lastError?.message}`,\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUO,MAAM,uBAAuB;AAK7B,MAAM,gBAAgB;AAAA,EAC3B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAQO,SAAS,UAAU,KAAsB;AAC9C,SAAO,IAAI,WAAW,SAAS;AACjC;AAiBO,SAAS,eACd,KACA,UAAkB,sBACV;AACR,MAAI,UAAU,GAAG,GAAG;AAClB,UAAM,OAAO,IAAI,QAAQ,WAAW,EAAE;AACtC,WAAO,GAAG,OAAO,GAAG,IAAI;AAAA,EAC1B;AACA,SAAO;AACT;AAsBO,SAAS,gBAAgB,KAA4B;AAE1D,QAAM,WAAW;AAAA,IACf;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,EACF;AAEA,aAAW,WAAW,UAAU;AAC9B,UAAM,QAAQ,IAAI,MAAM,OAAO;AAC/B,QAAI,OAAO;AACT,aAAO,MAAM,CAAC;AAAA,IAChB;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,eAAe,MAAwB;AACrD,SAAO,cAAc,IAAI,CAAC,YAAY,GAAG,OAAO,GAAG,IAAI,EAAE;AAC3D;AAQO,SAAS,4BAA4B,KAAuB;AACjE,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,MAAM;AACR,WAAO,eAAe,IAAI;AAAA,EAC5B;AACA,SAAO,CAAC,GAAG;AACb;AAiBA,eAAsB,mBACpB,KACA,SACmB;AACnB,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,CAAC,MAAM;AAET,WAAO,MAAM,KAAK,OAAO;AAAA,EAC3B;AAEA,QAAM,cAAc,eAAe,IAAI;AACvC,MAAI,YAA0B;AAE9B,WAAS,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;AAC3C,UAAM,aAAa,YAAY,CAAC;AAChC,QAAI;AACF,YAAM,WAAW,MAAM,MAAM,YAAY;AAAA,QACvC,GAAG;AAAA;AAAA,QAEH,QAAQ,YAAY,QAAQ,GAAK;AAAA;AAAA,MACnC,CAAC;AAGD,UAAI,SAAS,IAAI;AACf,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,WAAW,KAAK;AAC3B,oBAAY,IAAI,MAAM,yBAAyB,UAAU,EAAE;AAC3D;AAAA,MACF;AAGA,kBAAY,IAAI,MAAM,iBAAiB,SAAS,MAAM,KAAK,UAAU,EAAE;AAAA,IACzE,SAAS,OAAO;AACd,kBAAY,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAGpE,UACE,UAAU,QAAQ,SAAS,KAAK,KAChC,UAAU,SAAS,gBACnB;AACA;AAAA,MACF;AAAA,IACF;AAGA,QAAI,IAAI,YAAY,SAAS,GAAG;AAC9B,YAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,OAAQ,IAAI,EAAE,CAAC;AAAA,IACpE;AAAA,EACF;AAEA,QAAM,IAAI;AAAA,IACR,qCAAqC,IAAI,iBAAiB,WAAW,OAAO;AAAA,EAC9E;AACF;","names":[]}

package/dist/utils/ipfs.d.ts

@@ -11,7 +11,7 @@ export declare const DEFAULT_IPFS_GATEWAY = "https://dweb.link/ipfs/";
 /**
  * Alternative IPFS gateways for fallback - ordered by reliability and rate limits
  */
-export declare const IPFS_GATEWAYS: readonly ["https://dweb.link/ipfs/", "https://ipfs.io/ipfs/", "https://cloudflare-ipfs.com/ipfs/", "https://gateway.pinata.cloud/ipfs/", "https://ipfs.filebase.io/ipfs/"];
+export declare const IPFS_GATEWAYS: readonly ["https://ipfs.io/ipfs/", "https://dweb.link/ipfs/", "https://gateway.pinata.cloud/ipfs/", "https://ipfs.filebase.io/ipfs/"];
 /**
  * Check if a URL is an IPFS URL (starts with ipfs://)
  *

package/dist/utils/ipfs.js

@@ -1,11 +1,9 @@
 const DEFAULT_IPFS_GATEWAY = "https://dweb.link/ipfs/";
 const IPFS_GATEWAYS = [
-  "https://dweb.link/ipfs/",
-  // Interplanetary Shipyard - highly reliable
   "https://ipfs.io/ipfs/",
   // IPFS Foundation - reliable
-  "https://cloudflare-ipfs.com/ipfs/",
-  // Cloudflare - good performance
+  "https://dweb.link/ipfs/",
+  // Interplanetary Shipyard - observed to be having issues
   "https://gateway.pinata.cloud/ipfs/",
   // Pinata - backup option (has rate limits)
   "https://ipfs.filebase.io/ipfs/"

package/dist/utils/ipfs.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/ipfs.ts"],"sourcesContent":["/**\n * IPFS URL utilities for the Vana SDK\n *\n * Centralized functions for handling IPFS URLs, converting them to gateway URLs,\n * and extracting IPFS hashes from various URL formats.\n */\n\n/**\n * Default IPFS gateway URL\n */\nexport const DEFAULT_IPFS_GATEWAY = \"https://dweb.link/ipfs/\";\n\n/**\n * Alternative IPFS gateways for fallback - ordered by reliability and rate limits\n */\nexport const IPFS_GATEWAYS = [\n  \"https://dweb.link/ipfs/\", // Interplanetary Shipyard - highly reliable\n  \"https://ipfs.io/ipfs/\", // IPFS Foundation - reliable\n  \"https://cloudflare-ipfs.com/ipfs/\", // Cloudflare - good performance\n  \"https://gateway.pinata.cloud/ipfs/\", // Pinata - backup option (has rate limits)\n  \"https://ipfs.filebase.io/ipfs/\", // Filebase - emerging reliable option\n] as const;\n\n/**\n * Check if a URL is an IPFS URL (starts with ipfs://)\n *\n * @param url - The URL to check\n * @returns True if the URL is an IPFS URL\n */\nexport function isIpfsUrl(url: string): boolean {\n  return url.startsWith(\"ipfs://\");\n}\n\n/**\n * Convert an IPFS URL to an HTTP gateway URL\n *\n * @param url - The IPFS URL to convert (e.g., \"ipfs://QmHash...\")\n * @param gateway - Optional gateway URL (defaults to DEFAULT_IPFS_GATEWAY)\n * @returns The HTTP gateway URL or original URL if not an IPFS URL\n * @example\n * ```ts\n * convertIpfsUrl(\"ipfs://QmHash123\")\n * // Returns: \"https://ipfs.io/ipfs/QmHash123\"\n *\n * convertIpfsUrl(\"ipfs://QmHash123\", \"https://gateway.pinata.cloud/ipfs/\")\n * // Returns: \"https://gateway.pinata.cloud/ipfs/QmHash123\"\n * ```\n */\nexport function convertIpfsUrl(\n  url: string,\n  gateway: string = DEFAULT_IPFS_GATEWAY,\n): string {\n  if (isIpfsUrl(url)) {\n    const hash = url.replace(\"ipfs://\", \"\");\n    return `${gateway}${hash}`;\n  }\n  return url;\n}\n\n/**\n * Extract IPFS hash from various URL formats\n *\n * **Edge Cases:**\n * - Returns null for non-IPFS URLs or malformed hashes\n * - Handles both CIDv0 (starts with Qm) and CIDv1 formats\n * - Minimum 46 characters required for standalone hash detection\n * - Gateway paths with subdirectories are not supported\n *\n * @param url - The URL to extract hash from\n * @returns The IPFS hash or null if not found\n * @example\n * ```ts\n * extractIpfsHash(\"ipfs://QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"https://gateway.pinata.cloud/ipfs/QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"QmHash123456789012345678901234567890123456\") // Returns: \"QmHash123456789012345678901234567890123456\"\n * extractIpfsHash(\"https://example.com/file.json\") // Returns: null (not IPFS)\n * extractIpfsHash(\"ipfs://QmHash/subdirectory\") // Returns: null (subdirectories not supported)\n * ```\n */\nexport function extractIpfsHash(url: string): string | null {\n  // Handle various IPFS URL formats\n  const patterns = [\n    /ipfs\\/([a-zA-Z0-9]+)/, // https://gateway.pinata.cloud/ipfs/HASH\n    /^ipfs:\\/\\/([a-zA-Z0-9]+)$/, // ipfs://HASH\n    /^([a-zA-Z0-9]{46,})$/, // Just the hash (46+ chars for IPFS hashes)\n  ];\n\n  for (const pattern of patterns) {\n    const match = url.match(pattern);\n    if (match) {\n      return match[1];\n    }\n  }\n\n  return null;\n}\n\n/**\n * Get multiple gateway URLs for an IPFS hash (useful for fallback)\n *\n * @param hash - The IPFS hash\n * @returns Array of gateway URLs\n */\nexport function getGatewayUrls(hash: string): string[] {\n  return IPFS_GATEWAYS.map((gateway) => `${gateway}${hash}`);\n}\n\n/**\n * Convert an IPFS URL to multiple gateway URLs for fallback\n *\n * @param url - The IPFS URL\n * @returns Array of gateway URLs or original URL if not IPFS\n */\nexport function convertIpfsUrlWithFallbacks(url: string): string[] {\n  const hash = extractIpfsHash(url);\n  if (hash) {\n    return getGatewayUrls(hash);\n  }\n  return [url];\n}\n\n/**\n * Fetch content from IPFS with automatic gateway fallbacks\n *\n * **Edge Cases:**\n * - Non-IPFS URLs are fetched directly without fallback\n * - 10-second timeout per gateway attempt to prevent hanging\n * - Rate-limited gateways (429) are skipped immediately\n * - Exponential backoff between retries (1s, 2s, 3s, etc.)\n * - AbortSignal in options is merged with timeout signal\n *\n * @param url - The IPFS URL to fetch\n * @param options - Optional fetch options\n * @returns Promise resolving to Response object\n * @throws Error if all gateways fail\n */\nexport async function fetchWithFallbacks(\n  url: string,\n  options?: RequestInit,\n): Promise<Response> {\n  const hash = extractIpfsHash(url);\n  if (!hash) {\n    // Not an IPFS URL, fetch directly\n    return fetch(url, options);\n  }\n\n  const gatewayUrls = getGatewayUrls(hash);\n  let lastError: Error | null = null;\n\n  for (let i = 0; i < gatewayUrls.length; i++) {\n    const gatewayUrl = gatewayUrls[i];\n    try {\n      const response = await fetch(gatewayUrl, {\n        ...options,\n        // Add timeout to avoid hanging on slow gateways\n        signal: AbortSignal.timeout(10000), // 10 second timeout\n      });\n\n      // If response is ok, return it\n      if (response.ok) {\n        return response;\n      }\n\n      // If rate limited (429), try next gateway immediately\n      if (response.status === 429) {\n        lastError = new Error(`Gateway rate limited: ${gatewayUrl}`);\n        continue;\n      }\n\n      // For other HTTP errors, still try next gateway\n      lastError = new Error(`Gateway error ${response.status}: ${gatewayUrl}`);\n    } catch (error) {\n      lastError = error instanceof Error ? error : new Error(String(error));\n\n      // For rate limiting or timeout errors, continue to next gateway\n      if (\n        lastError.message.includes(\"429\") ||\n        lastError.name === \"TimeoutError\"\n      ) {\n        continue;\n      }\n    }\n\n    // Add delay between retries (except for last attempt)\n    if (i < gatewayUrls.length - 1) {\n      await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1))); // Exponential backoff\n    }\n  }\n\n  throw new Error(\n    `All IPFS gateways failed for hash ${hash}. Last error: ${lastError?.message}`,\n  );\n}\n"],"mappings":"AAUO,MAAM,uBAAuB;AAK7B,MAAM,gBAAgB;AAAA,EAC3B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAQO,SAAS,UAAU,KAAsB;AAC9C,SAAO,IAAI,WAAW,SAAS;AACjC;AAiBO,SAAS,eACd,KACA,UAAkB,sBACV;AACR,MAAI,UAAU,GAAG,GAAG;AAClB,UAAM,OAAO,IAAI,QAAQ,WAAW,EAAE;AACtC,WAAO,GAAG,OAAO,GAAG,IAAI;AAAA,EAC1B;AACA,SAAO;AACT;AAsBO,SAAS,gBAAgB,KAA4B;AAE1D,QAAM,WAAW;AAAA,IACf;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,EACF;AAEA,aAAW,WAAW,UAAU;AAC9B,UAAM,QAAQ,IAAI,MAAM,OAAO;AAC/B,QAAI,OAAO;AACT,aAAO,MAAM,CAAC;AAAA,IAChB;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,eAAe,MAAwB;AACrD,SAAO,cAAc,IAAI,CAAC,YAAY,GAAG,OAAO,GAAG,IAAI,EAAE;AAC3D;AAQO,SAAS,4BAA4B,KAAuB;AACjE,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,MAAM;AACR,WAAO,eAAe,IAAI;AAAA,EAC5B;AACA,SAAO,CAAC,GAAG;AACb;AAiBA,eAAsB,mBACpB,KACA,SACmB;AACnB,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,CAAC,MAAM;AAET,WAAO,MAAM,KAAK,OAAO;AAAA,EAC3B;AAEA,QAAM,cAAc,eAAe,IAAI;AACvC,MAAI,YAA0B;AAE9B,WAAS,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;AAC3C,UAAM,aAAa,YAAY,CAAC;AAChC,QAAI;AACF,YAAM,WAAW,MAAM,MAAM,YAAY;AAAA,QACvC,GAAG;AAAA;AAAA,QAEH,QAAQ,YAAY,QAAQ,GAAK;AAAA;AAAA,MACnC,CAAC;AAGD,UAAI,SAAS,IAAI;AACf,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,WAAW,KAAK;AAC3B,oBAAY,IAAI,MAAM,yBAAyB,UAAU,EAAE;AAC3D;AAAA,MACF;AAGA,kBAAY,IAAI,MAAM,iBAAiB,SAAS,MAAM,KAAK,UAAU,EAAE;AAAA,IACzE,SAAS,OAAO;AACd,kBAAY,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAGpE,UACE,UAAU,QAAQ,SAAS,KAAK,KAChC,UAAU,SAAS,gBACnB;AACA;AAAA,MACF;AAAA,IACF;AAGA,QAAI,IAAI,YAAY,SAAS,GAAG;AAC9B,YAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,OAAQ,IAAI,EAAE,CAAC;AAAA,IACpE;AAAA,EACF;AAEA,QAAM,IAAI;AAAA,IACR,qCAAqC,IAAI,iBAAiB,WAAW,OAAO;AAAA,EAC9E;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/ipfs.ts"],"sourcesContent":["/**\n * IPFS URL utilities for the Vana SDK\n *\n * Centralized functions for handling IPFS URLs, converting them to gateway URLs,\n * and extracting IPFS hashes from various URL formats.\n */\n\n/**\n * Default IPFS gateway URL\n */\nexport const DEFAULT_IPFS_GATEWAY = \"https://dweb.link/ipfs/\";\n\n/**\n * Alternative IPFS gateways for fallback - ordered by reliability and rate limits\n */\nexport const IPFS_GATEWAYS = [\n  \"https://ipfs.io/ipfs/\", // IPFS Foundation - reliable\n  \"https://dweb.link/ipfs/\", // Interplanetary Shipyard - observed to be having issues\n  \"https://gateway.pinata.cloud/ipfs/\", // Pinata - backup option (has rate limits)\n  \"https://ipfs.filebase.io/ipfs/\", // Filebase - emerging reliable option\n] as const;\n\n/**\n * Check if a URL is an IPFS URL (starts with ipfs://)\n *\n * @param url - The URL to check\n * @returns True if the URL is an IPFS URL\n */\nexport function isIpfsUrl(url: string): boolean {\n  return url.startsWith(\"ipfs://\");\n}\n\n/**\n * Convert an IPFS URL to an HTTP gateway URL\n *\n * @param url - The IPFS URL to convert (e.g., \"ipfs://QmHash...\")\n * @param gateway - Optional gateway URL (defaults to DEFAULT_IPFS_GATEWAY)\n * @returns The HTTP gateway URL or original URL if not an IPFS URL\n * @example\n * ```ts\n * convertIpfsUrl(\"ipfs://QmHash123\")\n * // Returns: \"https://ipfs.io/ipfs/QmHash123\"\n *\n * convertIpfsUrl(\"ipfs://QmHash123\", \"https://gateway.pinata.cloud/ipfs/\")\n * // Returns: \"https://gateway.pinata.cloud/ipfs/QmHash123\"\n * ```\n */\nexport function convertIpfsUrl(\n  url: string,\n  gateway: string = DEFAULT_IPFS_GATEWAY,\n): string {\n  if (isIpfsUrl(url)) {\n    const hash = url.replace(\"ipfs://\", \"\");\n    return `${gateway}${hash}`;\n  }\n  return url;\n}\n\n/**\n * Extract IPFS hash from various URL formats\n *\n * **Edge Cases:**\n * - Returns null for non-IPFS URLs or malformed hashes\n * - Handles both CIDv0 (starts with Qm) and CIDv1 formats\n * - Minimum 46 characters required for standalone hash detection\n * - Gateway paths with subdirectories are not supported\n *\n * @param url - The URL to extract hash from\n * @returns The IPFS hash or null if not found\n * @example\n * ```ts\n * extractIpfsHash(\"ipfs://QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"https://gateway.pinata.cloud/ipfs/QmHash123\") // Returns: \"QmHash123\"\n * extractIpfsHash(\"QmHash123456789012345678901234567890123456\") // Returns: \"QmHash123456789012345678901234567890123456\"\n * extractIpfsHash(\"https://example.com/file.json\") // Returns: null (not IPFS)\n * extractIpfsHash(\"ipfs://QmHash/subdirectory\") // Returns: null (subdirectories not supported)\n * ```\n */\nexport function extractIpfsHash(url: string): string | null {\n  // Handle various IPFS URL formats\n  const patterns = [\n    /ipfs\\/([a-zA-Z0-9]+)/, // https://gateway.pinata.cloud/ipfs/HASH\n    /^ipfs:\\/\\/([a-zA-Z0-9]+)$/, // ipfs://HASH\n    /^([a-zA-Z0-9]{46,})$/, // Just the hash (46+ chars for IPFS hashes)\n  ];\n\n  for (const pattern of patterns) {\n    const match = url.match(pattern);\n    if (match) {\n      return match[1];\n    }\n  }\n\n  return null;\n}\n\n/**\n * Get multiple gateway URLs for an IPFS hash (useful for fallback)\n *\n * @param hash - The IPFS hash\n * @returns Array of gateway URLs\n */\nexport function getGatewayUrls(hash: string): string[] {\n  return IPFS_GATEWAYS.map((gateway) => `${gateway}${hash}`);\n}\n\n/**\n * Convert an IPFS URL to multiple gateway URLs for fallback\n *\n * @param url - The IPFS URL\n * @returns Array of gateway URLs or original URL if not IPFS\n */\nexport function convertIpfsUrlWithFallbacks(url: string): string[] {\n  const hash = extractIpfsHash(url);\n  if (hash) {\n    return getGatewayUrls(hash);\n  }\n  return [url];\n}\n\n/**\n * Fetch content from IPFS with automatic gateway fallbacks\n *\n * **Edge Cases:**\n * - Non-IPFS URLs are fetched directly without fallback\n * - 10-second timeout per gateway attempt to prevent hanging\n * - Rate-limited gateways (429) are skipped immediately\n * - Exponential backoff between retries (1s, 2s, 3s, etc.)\n * - AbortSignal in options is merged with timeout signal\n *\n * @param url - The IPFS URL to fetch\n * @param options - Optional fetch options\n * @returns Promise resolving to Response object\n * @throws Error if all gateways fail\n */\nexport async function fetchWithFallbacks(\n  url: string,\n  options?: RequestInit,\n): Promise<Response> {\n  const hash = extractIpfsHash(url);\n  if (!hash) {\n    // Not an IPFS URL, fetch directly\n    return fetch(url, options);\n  }\n\n  const gatewayUrls = getGatewayUrls(hash);\n  let lastError: Error | null = null;\n\n  for (let i = 0; i < gatewayUrls.length; i++) {\n    const gatewayUrl = gatewayUrls[i];\n    try {\n      const response = await fetch(gatewayUrl, {\n        ...options,\n        // Add timeout to avoid hanging on slow gateways\n        signal: AbortSignal.timeout(10000), // 10 second timeout\n      });\n\n      // If response is ok, return it\n      if (response.ok) {\n        return response;\n      }\n\n      // If rate limited (429), try next gateway immediately\n      if (response.status === 429) {\n        lastError = new Error(`Gateway rate limited: ${gatewayUrl}`);\n        continue;\n      }\n\n      // For other HTTP errors, still try next gateway\n      lastError = new Error(`Gateway error ${response.status}: ${gatewayUrl}`);\n    } catch (error) {\n      lastError = error instanceof Error ? error : new Error(String(error));\n\n      // For rate limiting or timeout errors, continue to next gateway\n      if (\n        lastError.message.includes(\"429\") ||\n        lastError.name === \"TimeoutError\"\n      ) {\n        continue;\n      }\n    }\n\n    // Add delay between retries (except for last attempt)\n    if (i < gatewayUrls.length - 1) {\n      await new Promise((resolve) => setTimeout(resolve, 1000 * (i + 1))); // Exponential backoff\n    }\n  }\n\n  throw new Error(\n    `All IPFS gateways failed for hash ${hash}. Last error: ${lastError?.message}`,\n  );\n}\n"],"mappings":"AAUO,MAAM,uBAAuB;AAK7B,MAAM,gBAAgB;AAAA,EAC3B;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AAAA,EACA;AAAA;AACF;AAQO,SAAS,UAAU,KAAsB;AAC9C,SAAO,IAAI,WAAW,SAAS;AACjC;AAiBO,SAAS,eACd,KACA,UAAkB,sBACV;AACR,MAAI,UAAU,GAAG,GAAG;AAClB,UAAM,OAAO,IAAI,QAAQ,WAAW,EAAE;AACtC,WAAO,GAAG,OAAO,GAAG,IAAI;AAAA,EAC1B;AACA,SAAO;AACT;AAsBO,SAAS,gBAAgB,KAA4B;AAE1D,QAAM,WAAW;AAAA,IACf;AAAA;AAAA,IACA;AAAA;AAAA,IACA;AAAA;AAAA,EACF;AAEA,aAAW,WAAW,UAAU;AAC9B,UAAM,QAAQ,IAAI,MAAM,OAAO;AAC/B,QAAI,OAAO;AACT,aAAO,MAAM,CAAC;AAAA,IAChB;AAAA,EACF;AAEA,SAAO;AACT;AAQO,SAAS,eAAe,MAAwB;AACrD,SAAO,cAAc,IAAI,CAAC,YAAY,GAAG,OAAO,GAAG,IAAI,EAAE;AAC3D;AAQO,SAAS,4BAA4B,KAAuB;AACjE,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,MAAM;AACR,WAAO,eAAe,IAAI;AAAA,EAC5B;AACA,SAAO,CAAC,GAAG;AACb;AAiBA,eAAsB,mBACpB,KACA,SACmB;AACnB,QAAM,OAAO,gBAAgB,GAAG;AAChC,MAAI,CAAC,MAAM;AAET,WAAO,MAAM,KAAK,OAAO;AAAA,EAC3B;AAEA,QAAM,cAAc,eAAe,IAAI;AACvC,MAAI,YAA0B;AAE9B,WAAS,IAAI,GAAG,IAAI,YAAY,QAAQ,KAAK;AAC3C,UAAM,aAAa,YAAY,CAAC;AAChC,QAAI;AACF,YAAM,WAAW,MAAM,MAAM,YAAY;AAAA,QACvC,GAAG;AAAA;AAAA,QAEH,QAAQ,YAAY,QAAQ,GAAK;AAAA;AAAA,MACnC,CAAC;AAGD,UAAI,SAAS,IAAI;AACf,eAAO;AAAA,MACT;AAGA,UAAI,SAAS,WAAW,KAAK;AAC3B,oBAAY,IAAI,MAAM,yBAAyB,UAAU,EAAE;AAC3D;AAAA,MACF;AAGA,kBAAY,IAAI,MAAM,iBAAiB,SAAS,MAAM,KAAK,UAAU,EAAE;AAAA,IACzE,SAAS,OAAO;AACd,kBAAY,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAGpE,UACE,UAAU,QAAQ,SAAS,KAAK,KAChC,UAAU,SAAS,gBACnB;AACA;AAAA,MACF;AAAA,IACF;AAGA,QAAI,IAAI,YAAY,SAAS,GAAG;AAC9B,YAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,OAAQ,IAAI,EAAE,CAAC;AAAA,IACpE;AAAA,EACF;AAEA,QAAM,IAAI;AAAA,IACR,qCAAqC,IAAI,iBAAiB,WAAW,OAAO;AAAA,EAC9E;AACF;","names":[]}

package/dist/utils/lazy-import.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/lazy-import.ts"],"sourcesContent":["/**\n * Utility for lazy-loading modules to avoid Turbopack TDZ issues\n *\n * WARNING: This is a workaround for Turbopack's strict module initialization.\n * Dependencies that access globals during init must be dynamically imported.\n */\n\n/**\n * Creates a lazy import function that caches the promise (not the module)\n * to avoid race conditions on concurrent first calls\n *\n * @param importFn - Function that returns a dynamic import promise\n * @returns Function that returns the cached import promise\n *\n * @example\n * const getOpenPGP = lazyImport(() => import('openpgp'));\n * const openpgp = await getOpenPGP();\n */\nexport function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T> {\n  let cached: Promise<T> | null = null;\n\n  return () => {\n    cached ??= importFn().catch((err) => {\n      // Clear cache on error so next attempt can retry\n      cached = null;\n      throw new Error(\"Failed to load module\", { cause: err });\n    });\n    return cached;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAkBO,SAAS,WAAc,UAA8C;AAC1E,MAAI,SAA4B;AAEhC,SAAO,MAAM;AACX,eAAW,SAAS,EAAE,MAAM,CAAC,QAAQ;AAEnC,eAAS;AACT,YAAM,IAAI,MAAM,yBAAyB,EAAE,OAAO,IAAI,CAAC;AAAA,IACzD,CAAC;AACD,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/lazy-import.ts"],"sourcesContent":["/**\n * Provides lazy module loading to avoid Temporal Dead Zone issues.\n *\n * @remarks\n * This module implements a caching lazy import pattern to work around Turbopack's\n * strict module initialization. Dependencies that access globals during initialization\n * must be dynamically imported to prevent TDZ errors in Next.js environments.\n *\n * @see {@link https://github.com/vercel/next.js/issues/82632 | Turbopack TDZ Issue}\n *\n * @category Utilities\n * @module utils/lazy-import\n */\n\n/**\n * Creates a cached lazy import function for deferred module loading.\n *\n * @remarks\n * Caches the import promise (not the module) to prevent race conditions\n * during concurrent first calls. On import failure, clears the cache to\n * allow retry on next attempt.\n *\n * @typeParam T - The type of the module being imported\n *\n * @param importFn - Function that returns a dynamic import promise.\n *   Should be a dynamic import expression like `() => import('module')`.\n * @returns A function that returns the cached import promise\n *\n * @example\n * ```typescript\n * // Create lazy loader for heavy crypto library\n * const getOpenPGP = lazyImport(() => import('openpgp'));\n *\n * // Use when needed (first call triggers import)\n * const openpgp = await getOpenPGP();\n * const encrypted = await openpgp.encrypt(data);\n *\n * // Subsequent calls return cached promise\n * const openpgp2 = await getOpenPGP(); // Same instance\n * ```\n *\n * @category Utilities\n */\nexport function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T> {\n  let cached: Promise<T> | null = null;\n\n  return () => {\n    cached ??= importFn().catch((err) => {\n      // Clear cache on error so next attempt can retry\n      cached = null;\n      throw new Error(\"Failed to load module\", { cause: err });\n    });\n    return cached;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA2CO,SAAS,WAAc,UAA8C;AAC1E,MAAI,SAA4B;AAEhC,SAAO,MAAM;AACX,eAAW,SAAS,EAAE,MAAM,CAAC,QAAQ;AAEnC,eAAS;AACT,YAAM,IAAI,MAAM,yBAAyB,EAAE,OAAO,IAAI,CAAC;AAAA,IACzD,CAAC;AACD,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/utils/lazy-import.d.ts

@@ -1,18 +1,43 @@
 /**
- * Utility for lazy-loading modules to avoid Turbopack TDZ issues
+ * Provides lazy module loading to avoid Temporal Dead Zone issues.
  *
- * WARNING: This is a workaround for Turbopack's strict module initialization.
- * Dependencies that access globals during init must be dynamically imported.
+ * @remarks
+ * This module implements a caching lazy import pattern to work around Turbopack's
+ * strict module initialization. Dependencies that access globals during initialization
+ * must be dynamically imported to prevent TDZ errors in Next.js environments.
+ *
+ * @see {@link https://github.com/vercel/next.js/issues/82632 | Turbopack TDZ Issue}
+ *
+ * @category Utilities
+ * @module utils/lazy-import
  */
 /**
- * Creates a lazy import function that caches the promise (not the module)
- * to avoid race conditions on concurrent first calls
+ * Creates a cached lazy import function for deferred module loading.
+ *
+ * @remarks
+ * Caches the import promise (not the module) to prevent race conditions
+ * during concurrent first calls. On import failure, clears the cache to
+ * allow retry on next attempt.
+ *
+ * @typeParam T - The type of the module being imported
  *
- * @param importFn - Function that returns a dynamic import promise
- * @returns Function that returns the cached import promise
+ * @param importFn - Function that returns a dynamic import promise.
+ *   Should be a dynamic import expression like `() => import('module')`.
+ * @returns A function that returns the cached import promise
  *
  * @example
+ * ```typescript
+ * // Create lazy loader for heavy crypto library
  * const getOpenPGP = lazyImport(() => import('openpgp'));
+ *
+ * // Use when needed (first call triggers import)
  * const openpgp = await getOpenPGP();
+ * const encrypted = await openpgp.encrypt(data);
+ *
+ * // Subsequent calls return cached promise
+ * const openpgp2 = await getOpenPGP(); // Same instance
+ * ```
+ *
+ * @category Utilities
  */
 export declare function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T>;

package/dist/utils/lazy-import.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/lazy-import.ts"],"sourcesContent":["/**\n * Utility for lazy-loading modules to avoid Turbopack TDZ issues\n *\n * WARNING: This is a workaround for Turbopack's strict module initialization.\n * Dependencies that access globals during init must be dynamically imported.\n */\n\n/**\n * Creates a lazy import function that caches the promise (not the module)\n * to avoid race conditions on concurrent first calls\n *\n * @param importFn - Function that returns a dynamic import promise\n * @returns Function that returns the cached import promise\n *\n * @example\n * const getOpenPGP = lazyImport(() => import('openpgp'));\n * const openpgp = await getOpenPGP();\n */\nexport function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T> {\n  let cached: Promise<T> | null = null;\n\n  return () => {\n    cached ??= importFn().catch((err) => {\n      // Clear cache on error so next attempt can retry\n      cached = null;\n      throw new Error(\"Failed to load module\", { cause: err });\n    });\n    return cached;\n  };\n}\n"],"mappings":"AAkBO,SAAS,WAAc,UAA8C;AAC1E,MAAI,SAA4B;AAEhC,SAAO,MAAM;AACX,eAAW,SAAS,EAAE,MAAM,CAAC,QAAQ;AAEnC,eAAS;AACT,YAAM,IAAI,MAAM,yBAAyB,EAAE,OAAO,IAAI,CAAC;AAAA,IACzD,CAAC;AACD,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../../src/utils/lazy-import.ts"],"sourcesContent":["/**\n * Provides lazy module loading to avoid Temporal Dead Zone issues.\n *\n * @remarks\n * This module implements a caching lazy import pattern to work around Turbopack's\n * strict module initialization. Dependencies that access globals during initialization\n * must be dynamically imported to prevent TDZ errors in Next.js environments.\n *\n * @see {@link https://github.com/vercel/next.js/issues/82632 | Turbopack TDZ Issue}\n *\n * @category Utilities\n * @module utils/lazy-import\n */\n\n/**\n * Creates a cached lazy import function for deferred module loading.\n *\n * @remarks\n * Caches the import promise (not the module) to prevent race conditions\n * during concurrent first calls. On import failure, clears the cache to\n * allow retry on next attempt.\n *\n * @typeParam T - The type of the module being imported\n *\n * @param importFn - Function that returns a dynamic import promise.\n *   Should be a dynamic import expression like `() => import('module')`.\n * @returns A function that returns the cached import promise\n *\n * @example\n * ```typescript\n * // Create lazy loader for heavy crypto library\n * const getOpenPGP = lazyImport(() => import('openpgp'));\n *\n * // Use when needed (first call triggers import)\n * const openpgp = await getOpenPGP();\n * const encrypted = await openpgp.encrypt(data);\n *\n * // Subsequent calls return cached promise\n * const openpgp2 = await getOpenPGP(); // Same instance\n * ```\n *\n * @category Utilities\n */\nexport function lazyImport<T>(importFn: () => Promise<T>): () => Promise<T> {\n  let cached: Promise<T> | null = null;\n\n  return () => {\n    cached ??= importFn().catch((err) => {\n      // Clear cache on error so next attempt can retry\n      cached = null;\n      throw new Error(\"Failed to load module\", { cause: err });\n    });\n    return cached;\n  };\n}\n"],"mappings":"AA2CO,SAAS,WAAc,UAA8C;AAC1E,MAAI,SAA4B;AAEhC,SAAO,MAAM;AACX,eAAW,SAAS,EAAE,MAAM,CAAC,QAAQ;AAEnC,eAAS;AACT,YAAM,IAAI,MAAM,yBAAyB,EAAE,OAAO,IAAI,CAAC;AAAA,IACzD,CAAC;AACD,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/utils/signatureCache.cjs

@@ -145,12 +145,18 @@ class SignatureCache {
     return (0, import_viem.toHex)(hashBytes);
   }
   /**
-   * Deterministic JSON replacer that handles BigInt values and sorts object keys
-   * This ensures consistent cache key generation for EIP-712 typed data
+   * Deterministic JSON replacer for consistent cache key generation.
+   *
+   * @remarks
+   * Handles BigInt serialization and sorts object keys to ensure
+   * identical objects always produce the same hash regardless of
+   * property order.
    *
    * @param _key - The object key being serialized (unused)
    * @param value - The value to serialize
    * @returns The serialized value with sorted keys for objects
+   *
+   * @internal
    */
   static deterministicReplacer(_key, value) {
     if (typeof value === "bigint") {

package/dist/utils/signatureCache.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/signatureCache.ts"],"sourcesContent":["import type { Hash } from \"viem\";\nimport { getAddress, toHex } from \"viem\";\nimport type { VanaCacheAdapter } from \"../platform/interface\";\nimport { sha256 } from \"@noble/hashes/sha256\";\n\ninterface CachedSignature {\n  signature: Hash;\n  expires: number;\n}\n\n/**\n * Simple signature cache using platform cache adapter to avoid repeated signing of identical messages.\n *\n * @remarks\n * This cache significantly improves UX by avoiding repeated wallet signature prompts\n * for identical operations. It's particularly useful for operations that may be\n * retried or called multiple times with the same parameters.\n *\n * Features:\n * - Platform-appropriate storage (sessionStorage in browser, memory in Node.js)\n * - Configurable TTL (default 2 hours)\n * - Automatic cleanup of expired entries\n * - Cache keys based on wallet address + message hash\n *\n * @example\n * ```typescript\n * // Check cache before requesting signature\n * const cached = SignatureCache.get(cache, walletAddress, messageHash);\n * if (cached) {\n *   return cached;\n * }\n *\n * // Request signature and cache it\n * const signature = await wallet.signTypedData(typedData);\n * SignatureCache.set(cache, walletAddress, messageHash, signature);\n * ```\n * @category Utilities\n */\nexport class SignatureCache {\n  private static readonly PREFIX = \"vana_sig_\";\n  private static readonly DEFAULT_TTL_HOURS = 2;\n\n  /**\n   * Get a cached signature if it exists and hasn't expired\n   *\n   * @param cache - Platform cache adapter instance\n   * @param walletAddress - Wallet address that created the signature\n   * @param messageHash - Hash of the message that was signed\n   * @returns The cached signature if valid, null if expired or not found\n   * @example\n   * ```typescript\n   * const messageHash = SignatureCache.hashMessage(typedData);\n   * const cached = SignatureCache.get(cache, '0x123...', messageHash);\n   * if (cached) {\n   *   console.log('Using cached signature:', cached);\n   * }\n   * ```\n   */\n  static get(\n    cache: VanaCacheAdapter,\n    walletAddress: string,\n    messageHash: string,\n  ): Hash | null {\n    const key = this.getCacheKey(walletAddress, messageHash);\n\n    try {\n      const stored = cache.get(key);\n      if (!stored) return null;\n\n      const cached: CachedSignature = JSON.parse(stored);\n\n      // Check if expired\n      if (Date.now() > cached.expires) {\n        cache.delete(key);\n        return null;\n      }\n\n      return cached.signature;\n    } catch {\n      // Invalid JSON or storage error, clean up\n      try {\n        cache.delete(key);\n      } catch {\n        // Ignore cache cleanup errors\n      }\n      return null;\n    }\n  }\n\n  /**\n   * Store a signature in the cache with configurable TTL\n   *\n   * @param cache - Platform cache adapter instance\n   * @param walletAddress - Wallet address that created the signature\n   * @param messageHash - Hash of the message that was signed\n   * @param signature - The signature to cache\n   * @param ttlHours - Time to live in hours (default: 2)\n   * @example\n   * ```typescript\n   * const signature = await wallet.signTypedData(typedData);\n   * const messageHash = SignatureCache.hashMessage(typedData);\n   *\n   * // Cache for default 2 hours\n   * SignatureCache.set(cache, walletAddress, messageHash, signature);\n   *\n   * // Cache for 24 hours\n   * SignatureCache.set(cache, walletAddress, messageHash, signature, 24);\n   * ```\n   */\n  static set(\n    cache: VanaCacheAdapter,\n    walletAddress: string,\n    messageHash: string,\n    signature: Hash,\n    ttlHours: number = this.DEFAULT_TTL_HOURS,\n  ): void {\n    const key = this.getCacheKey(walletAddress, messageHash);\n    const cached: CachedSignature = {\n      signature,\n      expires: Date.now() + ttlHours * 3600000, // Convert hours to milliseconds\n    };\n\n    try {\n      cache.set(key, JSON.stringify(cached));\n    } catch {\n      // Storage quota exceeded or other error, ignore silently\n      // Better to continue without caching than to fail\n    }\n  }\n\n  /**\n   * Clear all cached signatures (useful for testing or explicit cleanup)\n   *\n   * @param cache - Platform cache adapter instance\n   * @example\n   * ```typescript\n   * // Clear all signatures when user logs out\n   * SignatureCache.clear(cache);\n   *\n   * // Clear before running tests\n   * beforeEach(() => {\n   *   SignatureCache.clear(cache);\n   * });\n   * ```\n   */\n  static clear(cache: VanaCacheAdapter): void {\n    try {\n      cache.clear();\n    } catch {\n      // Ignore storage errors\n    }\n  }\n\n  private static getCacheKey(\n    walletAddress: string,\n    messageHash: string,\n  ): string {\n    return `${this.PREFIX}${getAddress(walletAddress)}:${messageHash}`;\n  }\n\n  /**\n   * Generate a deterministic hash of a message object for cache key generation\n   *\n   * @remarks\n   * Creates a cryptographically secure hash from complex objects including EIP-712 typed data.\n   * Uses SHA-256 for collision resistance and deterministic key generation.\n   * Handles BigInt serialization and sorts object keys for consistency.\n   *\n   * @param message - The message object to hash (typically EIP-712 typed data)\n   * @returns A hex string hash (SHA-256) suitable for cache keys\n   * @example\n   * ```typescript\n   * const typedData = {\n   *   domain: { name: 'Vana', version: '1' },\n   *   message: { nonce: 123n, grant: '...' }\n   * };\n   *\n   * const hash = SignatureCache.hashMessage(typedData);\n   * // Returns SHA-256 hash like: \"a1b2c3d4e5f6...\"\n   * ```\n   */\n  static hashMessage(message: object): string {\n    // Deterministically stringify the object with sorted keys\n    const jsonString = JSON.stringify(message, this.deterministicReplacer);\n\n    // Use SHA-256 for cryptographic hashing\n    const hashBytes = sha256(new TextEncoder().encode(jsonString));\n    return toHex(hashBytes);\n  }\n\n  /**\n   * Deterministic JSON replacer that handles BigInt values and sorts object keys\n   * This ensures consistent cache key generation for EIP-712 typed data\n   *\n   * @param _key - The object key being serialized (unused)\n   * @param value - The value to serialize\n   * @returns The serialized value with sorted keys for objects\n   */\n  private static deterministicReplacer(_key: string, value: unknown): unknown {\n    if (typeof value === \"bigint\") {\n      return `__BIGINT__${value.toString()}`;\n    }\n    // Sort object keys for deterministic serialization\n    if (value !== null && typeof value === \"object\" && !Array.isArray(value)) {\n      return Object.keys(value as Record<string, unknown>)\n        .sort()\n        .reduce(\n          (sorted, key) => {\n            sorted[key] = (value as Record<string, unknown>)[key];\n            return sorted;\n          },\n          {} as Record<string, unknown>,\n        );\n    }\n    return value;\n  }\n}\n\n/**\n * Wrapper function to cache signature operations\n *\n * @param cache - The cache adapter to use for storage\n * @param walletAddress - The wallet address signing the message\n * @param typedData - The EIP-712 typed data being signed\n * @param signFn - Function that performs the actual signing\n * @param ttlHours - Cache TTL in hours (default 2)\n * @returns The signature (cached or newly generated)\n */\nexport async function withSignatureCache(\n  cache: VanaCacheAdapter,\n  walletAddress: string,\n  typedData: Record<string, unknown>,\n  signFn: () => Promise<Hash>,\n  ttlHours?: number,\n): Promise<Hash> {\n  // Create a hash of the typed data for the cache key\n  const messageHash = SignatureCache.hashMessage(typedData);\n\n  // Try to get from cache first\n  const cached = SignatureCache.get(cache, walletAddress, messageHash);\n  if (cached) {\n    return cached;\n  }\n\n  // Not in cache, sign and store\n  const signature = await signFn();\n  SignatureCache.set(cache, walletAddress, messageHash, signature, ttlHours);\n\n  return signature;\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/utils/signatureCache.ts"],"sourcesContent":["/**\n * Provides signature caching to improve UX by avoiding repeated wallet prompts.\n *\n * @remarks\n * This module implements a secure signature cache that stores signed messages\n * temporarily to avoid repeatedly prompting users for the same signature.\n * It uses platform-appropriate storage (sessionStorage in browser, memory in Node.js)\n * and includes automatic expiration and cleanup.\n *\n * @category Utilities\n * @module utils/signatureCache\n */\n\nimport type { Hash } from \"viem\";\nimport { getAddress, toHex } from \"viem\";\nimport type { VanaCacheAdapter } from \"../platform/interface\";\nimport { sha256 } from \"@noble/hashes/sha256\";\n\n/**\n * Represents a cached signature with expiration metadata.\n *\n * @internal\n */\ninterface CachedSignature {\n  /** The cached signature hash */\n  signature: Hash;\n  /** Unix timestamp when this cache entry expires */\n  expires: number;\n}\n\n/**\n * Simple signature cache using platform cache adapter to avoid repeated signing of identical messages.\n *\n * @remarks\n * This cache significantly improves UX by avoiding repeated wallet signature prompts\n * for identical operations. It's particularly useful for operations that may be\n * retried or called multiple times with the same parameters.\n *\n * Features:\n * - Platform-appropriate storage (sessionStorage in browser, memory in Node.js)\n * - Configurable TTL (default 2 hours)\n * - Automatic cleanup of expired entries\n * - Cache keys based on wallet address + message hash\n *\n * @example\n * ```typescript\n * // Check cache before requesting signature\n * const cached = SignatureCache.get(cache, walletAddress, messageHash);\n * if (cached) {\n *   return cached;\n * }\n *\n * // Request signature and cache it\n * const signature = await wallet.signTypedData(typedData);\n * SignatureCache.set(cache, walletAddress, messageHash, signature);\n * ```\n * @category Utilities\n */\nexport class SignatureCache {\n  private static readonly PREFIX = \"vana_sig_\";\n  private static readonly DEFAULT_TTL_HOURS = 2;\n\n  /**\n   * Get a cached signature if it exists and hasn't expired\n   *\n   * @param cache - Platform cache adapter instance\n   * @param walletAddress - Wallet address that created the signature\n   * @param messageHash - Hash of the message that was signed\n   * @returns The cached signature if valid, null if expired or not found\n   * @example\n   * ```typescript\n   * const messageHash = SignatureCache.hashMessage(typedData);\n   * const cached = SignatureCache.get(cache, '0x123...', messageHash);\n   * if (cached) {\n   *   console.log('Using cached signature:', cached);\n   * }\n   * ```\n   */\n  static get(\n    cache: VanaCacheAdapter,\n    walletAddress: string,\n    messageHash: string,\n  ): Hash | null {\n    const key = this.getCacheKey(walletAddress, messageHash);\n\n    try {\n      const stored = cache.get(key);\n      if (!stored) return null;\n\n      const cached: CachedSignature = JSON.parse(stored);\n\n      // Check if expired\n      if (Date.now() > cached.expires) {\n        cache.delete(key);\n        return null;\n      }\n\n      return cached.signature;\n    } catch {\n      // Invalid JSON or storage error, clean up\n      try {\n        cache.delete(key);\n      } catch {\n        // Ignore cache cleanup errors\n      }\n      return null;\n    }\n  }\n\n  /**\n   * Store a signature in the cache with configurable TTL\n   *\n   * @param cache - Platform cache adapter instance\n   * @param walletAddress - Wallet address that created the signature\n   * @param messageHash - Hash of the message that was signed\n   * @param signature - The signature to cache\n   * @param ttlHours - Time to live in hours (default: 2)\n   * @example\n   * ```typescript\n   * const signature = await wallet.signTypedData(typedData);\n   * const messageHash = SignatureCache.hashMessage(typedData);\n   *\n   * // Cache for default 2 hours\n   * SignatureCache.set(cache, walletAddress, messageHash, signature);\n   *\n   * // Cache for 24 hours\n   * SignatureCache.set(cache, walletAddress, messageHash, signature, 24);\n   * ```\n   */\n  static set(\n    cache: VanaCacheAdapter,\n    walletAddress: string,\n    messageHash: string,\n    signature: Hash,\n    ttlHours: number = this.DEFAULT_TTL_HOURS,\n  ): void {\n    const key = this.getCacheKey(walletAddress, messageHash);\n    const cached: CachedSignature = {\n      signature,\n      expires: Date.now() + ttlHours * 3600000, // Convert hours to milliseconds\n    };\n\n    try {\n      cache.set(key, JSON.stringify(cached));\n    } catch {\n      // Storage quota exceeded or other error, ignore silently\n      // Better to continue without caching than to fail\n    }\n  }\n\n  /**\n   * Clear all cached signatures (useful for testing or explicit cleanup)\n   *\n   * @param cache - Platform cache adapter instance\n   * @example\n   * ```typescript\n   * // Clear all signatures when user logs out\n   * SignatureCache.clear(cache);\n   *\n   * // Clear before running tests\n   * beforeEach(() => {\n   *   SignatureCache.clear(cache);\n   * });\n   * ```\n   */\n  static clear(cache: VanaCacheAdapter): void {\n    try {\n      cache.clear();\n    } catch {\n      // Ignore storage errors\n    }\n  }\n\n  private static getCacheKey(\n    walletAddress: string,\n    messageHash: string,\n  ): string {\n    return `${this.PREFIX}${getAddress(walletAddress)}:${messageHash}`;\n  }\n\n  /**\n   * Generate a deterministic hash of a message object for cache key generation\n   *\n   * @remarks\n   * Creates a cryptographically secure hash from complex objects including EIP-712 typed data.\n   * Uses SHA-256 for collision resistance and deterministic key generation.\n   * Handles BigInt serialization and sorts object keys for consistency.\n   *\n   * @param message - The message object to hash (typically EIP-712 typed data)\n   * @returns A hex string hash (SHA-256) suitable for cache keys\n   * @example\n   * ```typescript\n   * const typedData = {\n   *   domain: { name: 'Vana', version: '1' },\n   *   message: { nonce: 123n, grant: '...' }\n   * };\n   *\n   * const hash = SignatureCache.hashMessage(typedData);\n   * // Returns SHA-256 hash like: \"a1b2c3d4e5f6...\"\n   * ```\n   */\n  static hashMessage(message: object): string {\n    // Deterministically stringify the object with sorted keys\n    const jsonString = JSON.stringify(message, this.deterministicReplacer);\n\n    // Use SHA-256 for cryptographic hashing\n    const hashBytes = sha256(new TextEncoder().encode(jsonString));\n    return toHex(hashBytes);\n  }\n\n  /**\n   * Deterministic JSON replacer for consistent cache key generation.\n   *\n   * @remarks\n   * Handles BigInt serialization and sorts object keys to ensure\n   * identical objects always produce the same hash regardless of\n   * property order.\n   *\n   * @param _key - The object key being serialized (unused)\n   * @param value - The value to serialize\n   * @returns The serialized value with sorted keys for objects\n   *\n   * @internal\n   */\n  private static deterministicReplacer(_key: string, value: unknown): unknown {\n    if (typeof value === \"bigint\") {\n      return `__BIGINT__${value.toString()}`;\n    }\n    // Sort object keys for deterministic serialization\n    if (value !== null && typeof value === \"object\" && !Array.isArray(value)) {\n      return Object.keys(value as Record<string, unknown>)\n        .sort()\n        .reduce(\n          (sorted, key) => {\n            sorted[key] = (value as Record<string, unknown>)[key];\n            return sorted;\n          },\n          {} as Record<string, unknown>,\n        );\n    }\n    return value;\n  }\n}\n\n/**\n * Wraps signature operations with caching to avoid repeated prompts.\n *\n * @remarks\n * This helper function checks the cache before requesting a signature\n * and stores new signatures for future use. It significantly improves\n * UX for operations that may be retried or called multiple times.\n *\n * @param cache - The cache adapter to use for storage.\n *   Obtain from platform adapter.\n * @param walletAddress - The wallet address signing the message.\n *   Obtain from wallet connection.\n * @param typedData - The EIP-712 typed data being signed.\n *   Typically permission or grant data.\n * @param signFn - Async function that performs the actual signing.\n *   Usually calls wallet.signTypedData().\n * @param ttlHours - Cache TTL in hours.\n *   Defaults to 2 hours.\n * @returns The signature (cached or newly generated)\n *\n * @example\n * ```typescript\n * const signature = await withSignatureCache(\n *   platformAdapter.cache,\n *   walletAddress,\n *   typedData,\n *   async () => wallet.signTypedData(typedData),\n *   24 // Cache for 24 hours\n * );\n * ```\n *\n * @category Utilities\n */\nexport async function withSignatureCache(\n  cache: VanaCacheAdapter,\n  walletAddress: string,\n  typedData: Record<string, unknown>,\n  signFn: () => Promise<Hash>,\n  ttlHours?: number,\n): Promise<Hash> {\n  // Create a hash of the typed data for the cache key\n  const messageHash = SignatureCache.hashMessage(typedData);\n\n  // Try to get from cache first\n  const cached = SignatureCache.get(cache, walletAddress, messageHash);\n  if (cached) {\n    return cached;\n  }\n\n  // Not in cache, sign and store\n  const signature = await signFn();\n  SignatureCache.set(cache, walletAddress, messageHash, signature, ttlHours);\n\n  return signature;\n}\n"],"mappings":"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","names":[]}

package/dist/utils/signatureCache.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Provides signature caching to improve UX by avoiding repeated wallet prompts.
+ *
+ * @remarks
+ * This module implements a secure signature cache that stores signed messages
+ * temporarily to avoid repeatedly prompting users for the same signature.
+ * It uses platform-appropriate storage (sessionStorage in browser, memory in Node.js)
+ * and includes automatic expiration and cleanup.
+ *
+ * @category Utilities
+ * @module utils/signatureCache
+ */
 import type { Hash } from "viem";
 import type { VanaCacheAdapter } from "../platform/interface";
 /**
@@ -109,23 +121,52 @@ export declare class SignatureCache {
      */
     static hashMessage(message: object): string;
     /**
-     * Deterministic JSON replacer that handles BigInt values and sorts object keys
-     * This ensures consistent cache key generation for EIP-712 typed data
+     * Deterministic JSON replacer for consistent cache key generation.
+     *
+     * @remarks
+     * Handles BigInt serialization and sorts object keys to ensure
+     * identical objects always produce the same hash regardless of
+     * property order.
      *
      * @param _key - The object key being serialized (unused)
      * @param value - The value to serialize
      * @returns The serialized value with sorted keys for objects
+     *
+     * @internal
      */
     private static deterministicReplacer;
 }
 /**
- * Wrapper function to cache signature operations
+ * Wraps signature operations with caching to avoid repeated prompts.
  *
- * @param cache - The cache adapter to use for storage
- * @param walletAddress - The wallet address signing the message
- * @param typedData - The EIP-712 typed data being signed
- * @param signFn - Function that performs the actual signing
- * @param ttlHours - Cache TTL in hours (default 2)
+ * @remarks
+ * This helper function checks the cache before requesting a signature
+ * and stores new signatures for future use. It significantly improves
+ * UX for operations that may be retried or called multiple times.
+ *
+ * @param cache - The cache adapter to use for storage.
+ *   Obtain from platform adapter.
+ * @param walletAddress - The wallet address signing the message.
+ *   Obtain from wallet connection.
+ * @param typedData - The EIP-712 typed data being signed.
+ *   Typically permission or grant data.
+ * @param signFn - Async function that performs the actual signing.
+ *   Usually calls wallet.signTypedData().
+ * @param ttlHours - Cache TTL in hours.
+ *   Defaults to 2 hours.
  * @returns The signature (cached or newly generated)
+ *
+ * @example
+ * ```typescript
+ * const signature = await withSignatureCache(
+ *   platformAdapter.cache,
+ *   walletAddress,
+ *   typedData,
+ *   async () => wallet.signTypedData(typedData),
+ *   24 // Cache for 24 hours
+ * );
+ * ```
+ *
+ * @category Utilities
  */
 export declare function withSignatureCache(cache: VanaCacheAdapter, walletAddress: string, typedData: Record<string, unknown>, signFn: () => Promise<Hash>, ttlHours?: number): Promise<Hash>;

package/dist/utils/signatureCache.js

@@ -121,12 +121,18 @@ class SignatureCache {
     return toHex(hashBytes);
   }
   /**
-   * Deterministic JSON replacer that handles BigInt values and sorts object keys
-   * This ensures consistent cache key generation for EIP-712 typed data
+   * Deterministic JSON replacer for consistent cache key generation.
+   *
+   * @remarks
+   * Handles BigInt serialization and sorts object keys to ensure
+   * identical objects always produce the same hash regardless of
+   * property order.
    *
    * @param _key - The object key being serialized (unused)
    * @param value - The value to serialize
    * @returns The serialized value with sorted keys for objects
+   *
+   * @internal
    */
   static deterministicReplacer(_key, value) {
     if (typeof value === "bigint") {

package/dist/utils/signatureCache.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/signatureCache.ts"],"sourcesContent":["import type { Hash } from \"viem\";\nimport { getAddress, toHex } from \"viem\";\nimport type { VanaCacheAdapter } from \"../platform/interface\";\nimport { sha256 } from \"@noble/hashes/sha256\";\n\ninterface CachedSignature {\n  signature: Hash;\n  expires: number;\n}\n\n/**\n * Simple signature cache using platform cache adapter to avoid repeated signing of identical messages.\n *\n * @remarks\n * This cache significantly improves UX by avoiding repeated wallet signature prompts\n * for identical operations. It's particularly useful for operations that may be\n * retried or called multiple times with the same parameters.\n *\n * Features:\n * - Platform-appropriate storage (sessionStorage in browser, memory in Node.js)\n * - Configurable TTL (default 2 hours)\n * - Automatic cleanup of expired entries\n * - Cache keys based on wallet address + message hash\n *\n * @example\n * ```typescript\n * // Check cache before requesting signature\n * const cached = SignatureCache.get(cache, walletAddress, messageHash);\n * if (cached) {\n *   return cached;\n * }\n *\n * // Request signature and cache it\n * const signature = await wallet.signTypedData(typedData);\n * SignatureCache.set(cache, walletAddress, messageHash, signature);\n * ```\n * @category Utilities\n */\nexport class SignatureCache {\n  private static readonly PREFIX = \"vana_sig_\";\n  private static readonly DEFAULT_TTL_HOURS = 2;\n\n  /**\n   * Get a cached signature if it exists and hasn't expired\n   *\n   * @param cache - Platform cache adapter instance\n   * @param walletAddress - Wallet address that created the signature\n   * @param messageHash - Hash of the message that was signed\n   * @returns The cached signature if valid, null if expired or not found\n   * @example\n   * ```typescript\n   * const messageHash = SignatureCache.hashMessage(typedData);\n   * const cached = SignatureCache.get(cache, '0x123...', messageHash);\n   * if (cached) {\n   *   console.log('Using cached signature:', cached);\n   * }\n   * ```\n   */\n  static get(\n    cache: VanaCacheAdapter,\n    walletAddress: string,\n    messageHash: string,\n  ): Hash | null {\n    const key = this.getCacheKey(walletAddress, messageHash);\n\n    try {\n      const stored = cache.get(key);\n      if (!stored) return null;\n\n      const cached: CachedSignature = JSON.parse(stored);\n\n      // Check if expired\n      if (Date.now() > cached.expires) {\n        cache.delete(key);\n        return null;\n      }\n\n      return cached.signature;\n    } catch {\n      // Invalid JSON or storage error, clean up\n      try {\n        cache.delete(key);\n      } catch {\n        // Ignore cache cleanup errors\n      }\n      return null;\n    }\n  }\n\n  /**\n   * Store a signature in the cache with configurable TTL\n   *\n   * @param cache - Platform cache adapter instance\n   * @param walletAddress - Wallet address that created the signature\n   * @param messageHash - Hash of the message that was signed\n   * @param signature - The signature to cache\n   * @param ttlHours - Time to live in hours (default: 2)\n   * @example\n   * ```typescript\n   * const signature = await wallet.signTypedData(typedData);\n   * const messageHash = SignatureCache.hashMessage(typedData);\n   *\n   * // Cache for default 2 hours\n   * SignatureCache.set(cache, walletAddress, messageHash, signature);\n   *\n   * // Cache for 24 hours\n   * SignatureCache.set(cache, walletAddress, messageHash, signature, 24);\n   * ```\n   */\n  static set(\n    cache: VanaCacheAdapter,\n    walletAddress: string,\n    messageHash: string,\n    signature: Hash,\n    ttlHours: number = this.DEFAULT_TTL_HOURS,\n  ): void {\n    const key = this.getCacheKey(walletAddress, messageHash);\n    const cached: CachedSignature = {\n      signature,\n      expires: Date.now() + ttlHours * 3600000, // Convert hours to milliseconds\n    };\n\n    try {\n      cache.set(key, JSON.stringify(cached));\n    } catch {\n      // Storage quota exceeded or other error, ignore silently\n      // Better to continue without caching than to fail\n    }\n  }\n\n  /**\n   * Clear all cached signatures (useful for testing or explicit cleanup)\n   *\n   * @param cache - Platform cache adapter instance\n   * @example\n   * ```typescript\n   * // Clear all signatures when user logs out\n   * SignatureCache.clear(cache);\n   *\n   * // Clear before running tests\n   * beforeEach(() => {\n   *   SignatureCache.clear(cache);\n   * });\n   * ```\n   */\n  static clear(cache: VanaCacheAdapter): void {\n    try {\n      cache.clear();\n    } catch {\n      // Ignore storage errors\n    }\n  }\n\n  private static getCacheKey(\n    walletAddress: string,\n    messageHash: string,\n  ): string {\n    return `${this.PREFIX}${getAddress(walletAddress)}:${messageHash}`;\n  }\n\n  /**\n   * Generate a deterministic hash of a message object for cache key generation\n   *\n   * @remarks\n   * Creates a cryptographically secure hash from complex objects including EIP-712 typed data.\n   * Uses SHA-256 for collision resistance and deterministic key generation.\n   * Handles BigInt serialization and sorts object keys for consistency.\n   *\n   * @param message - The message object to hash (typically EIP-712 typed data)\n   * @returns A hex string hash (SHA-256) suitable for cache keys\n   * @example\n   * ```typescript\n   * const typedData = {\n   *   domain: { name: 'Vana', version: '1' },\n   *   message: { nonce: 123n, grant: '...' }\n   * };\n   *\n   * const hash = SignatureCache.hashMessage(typedData);\n   * // Returns SHA-256 hash like: \"a1b2c3d4e5f6...\"\n   * ```\n   */\n  static hashMessage(message: object): string {\n    // Deterministically stringify the object with sorted keys\n    const jsonString = JSON.stringify(message, this.deterministicReplacer);\n\n    // Use SHA-256 for cryptographic hashing\n    const hashBytes = sha256(new TextEncoder().encode(jsonString));\n    return toHex(hashBytes);\n  }\n\n  /**\n   * Deterministic JSON replacer that handles BigInt values and sorts object keys\n   * This ensures consistent cache key generation for EIP-712 typed data\n   *\n   * @param _key - The object key being serialized (unused)\n   * @param value - The value to serialize\n   * @returns The serialized value with sorted keys for objects\n   */\n  private static deterministicReplacer(_key: string, value: unknown): unknown {\n    if (typeof value === \"bigint\") {\n      return `__BIGINT__${value.toString()}`;\n    }\n    // Sort object keys for deterministic serialization\n    if (value !== null && typeof value === \"object\" && !Array.isArray(value)) {\n      return Object.keys(value as Record<string, unknown>)\n        .sort()\n        .reduce(\n          (sorted, key) => {\n            sorted[key] = (value as Record<string, unknown>)[key];\n            return sorted;\n          },\n          {} as Record<string, unknown>,\n        );\n    }\n    return value;\n  }\n}\n\n/**\n * Wrapper function to cache signature operations\n *\n * @param cache - The cache adapter to use for storage\n * @param walletAddress - The wallet address signing the message\n * @param typedData - The EIP-712 typed data being signed\n * @param signFn - Function that performs the actual signing\n * @param ttlHours - Cache TTL in hours (default 2)\n * @returns The signature (cached or newly generated)\n */\nexport async function withSignatureCache(\n  cache: VanaCacheAdapter,\n  walletAddress: string,\n  typedData: Record<string, unknown>,\n  signFn: () => Promise<Hash>,\n  ttlHours?: number,\n): Promise<Hash> {\n  // Create a hash of the typed data for the cache key\n  const messageHash = SignatureCache.hashMessage(typedData);\n\n  // Try to get from cache first\n  const cached = SignatureCache.get(cache, walletAddress, messageHash);\n  if (cached) {\n    return cached;\n  }\n\n  // Not in cache, sign and store\n  const signature = await signFn();\n  SignatureCache.set(cache, walletAddress, messageHash, signature, ttlHours);\n\n  return signature;\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/utils/signatureCache.ts"],"sourcesContent":["/**\n * Provides signature caching to improve UX by avoiding repeated wallet prompts.\n *\n * @remarks\n * This module implements a secure signature cache that stores signed messages\n * temporarily to avoid repeatedly prompting users for the same signature.\n * It uses platform-appropriate storage (sessionStorage in browser, memory in Node.js)\n * and includes automatic expiration and cleanup.\n *\n * @category Utilities\n * @module utils/signatureCache\n */\n\nimport type { Hash } from \"viem\";\nimport { getAddress, toHex } from \"viem\";\nimport type { VanaCacheAdapter } from \"../platform/interface\";\nimport { sha256 } from \"@noble/hashes/sha256\";\n\n/**\n * Represents a cached signature with expiration metadata.\n *\n * @internal\n */\ninterface CachedSignature {\n  /** The cached signature hash */\n  signature: Hash;\n  /** Unix timestamp when this cache entry expires */\n  expires: number;\n}\n\n/**\n * Simple signature cache using platform cache adapter to avoid repeated signing of identical messages.\n *\n * @remarks\n * This cache significantly improves UX by avoiding repeated wallet signature prompts\n * for identical operations. It's particularly useful for operations that may be\n * retried or called multiple times with the same parameters.\n *\n * Features:\n * - Platform-appropriate storage (sessionStorage in browser, memory in Node.js)\n * - Configurable TTL (default 2 hours)\n * - Automatic cleanup of expired entries\n * - Cache keys based on wallet address + message hash\n *\n * @example\n * ```typescript\n * // Check cache before requesting signature\n * const cached = SignatureCache.get(cache, walletAddress, messageHash);\n * if (cached) {\n *   return cached;\n * }\n *\n * // Request signature and cache it\n * const signature = await wallet.signTypedData(typedData);\n * SignatureCache.set(cache, walletAddress, messageHash, signature);\n * ```\n * @category Utilities\n */\nexport class SignatureCache {\n  private static readonly PREFIX = \"vana_sig_\";\n  private static readonly DEFAULT_TTL_HOURS = 2;\n\n  /**\n   * Get a cached signature if it exists and hasn't expired\n   *\n   * @param cache - Platform cache adapter instance\n   * @param walletAddress - Wallet address that created the signature\n   * @param messageHash - Hash of the message that was signed\n   * @returns The cached signature if valid, null if expired or not found\n   * @example\n   * ```typescript\n   * const messageHash = SignatureCache.hashMessage(typedData);\n   * const cached = SignatureCache.get(cache, '0x123...', messageHash);\n   * if (cached) {\n   *   console.log('Using cached signature:', cached);\n   * }\n   * ```\n   */\n  static get(\n    cache: VanaCacheAdapter,\n    walletAddress: string,\n    messageHash: string,\n  ): Hash | null {\n    const key = this.getCacheKey(walletAddress, messageHash);\n\n    try {\n      const stored = cache.get(key);\n      if (!stored) return null;\n\n      const cached: CachedSignature = JSON.parse(stored);\n\n      // Check if expired\n      if (Date.now() > cached.expires) {\n        cache.delete(key);\n        return null;\n      }\n\n      return cached.signature;\n    } catch {\n      // Invalid JSON or storage error, clean up\n      try {\n        cache.delete(key);\n      } catch {\n        // Ignore cache cleanup errors\n      }\n      return null;\n    }\n  }\n\n  /**\n   * Store a signature in the cache with configurable TTL\n   *\n   * @param cache - Platform cache adapter instance\n   * @param walletAddress - Wallet address that created the signature\n   * @param messageHash - Hash of the message that was signed\n   * @param signature - The signature to cache\n   * @param ttlHours - Time to live in hours (default: 2)\n   * @example\n   * ```typescript\n   * const signature = await wallet.signTypedData(typedData);\n   * const messageHash = SignatureCache.hashMessage(typedData);\n   *\n   * // Cache for default 2 hours\n   * SignatureCache.set(cache, walletAddress, messageHash, signature);\n   *\n   * // Cache for 24 hours\n   * SignatureCache.set(cache, walletAddress, messageHash, signature, 24);\n   * ```\n   */\n  static set(\n    cache: VanaCacheAdapter,\n    walletAddress: string,\n    messageHash: string,\n    signature: Hash,\n    ttlHours: number = this.DEFAULT_TTL_HOURS,\n  ): void {\n    const key = this.getCacheKey(walletAddress, messageHash);\n    const cached: CachedSignature = {\n      signature,\n      expires: Date.now() + ttlHours * 3600000, // Convert hours to milliseconds\n    };\n\n    try {\n      cache.set(key, JSON.stringify(cached));\n    } catch {\n      // Storage quota exceeded or other error, ignore silently\n      // Better to continue without caching than to fail\n    }\n  }\n\n  /**\n   * Clear all cached signatures (useful for testing or explicit cleanup)\n   *\n   * @param cache - Platform cache adapter instance\n   * @example\n   * ```typescript\n   * // Clear all signatures when user logs out\n   * SignatureCache.clear(cache);\n   *\n   * // Clear before running tests\n   * beforeEach(() => {\n   *   SignatureCache.clear(cache);\n   * });\n   * ```\n   */\n  static clear(cache: VanaCacheAdapter): void {\n    try {\n      cache.clear();\n    } catch {\n      // Ignore storage errors\n    }\n  }\n\n  private static getCacheKey(\n    walletAddress: string,\n    messageHash: string,\n  ): string {\n    return `${this.PREFIX}${getAddress(walletAddress)}:${messageHash}`;\n  }\n\n  /**\n   * Generate a deterministic hash of a message object for cache key generation\n   *\n   * @remarks\n   * Creates a cryptographically secure hash from complex objects including EIP-712 typed data.\n   * Uses SHA-256 for collision resistance and deterministic key generation.\n   * Handles BigInt serialization and sorts object keys for consistency.\n   *\n   * @param message - The message object to hash (typically EIP-712 typed data)\n   * @returns A hex string hash (SHA-256) suitable for cache keys\n   * @example\n   * ```typescript\n   * const typedData = {\n   *   domain: { name: 'Vana', version: '1' },\n   *   message: { nonce: 123n, grant: '...' }\n   * };\n   *\n   * const hash = SignatureCache.hashMessage(typedData);\n   * // Returns SHA-256 hash like: \"a1b2c3d4e5f6...\"\n   * ```\n   */\n  static hashMessage(message: object): string {\n    // Deterministically stringify the object with sorted keys\n    const jsonString = JSON.stringify(message, this.deterministicReplacer);\n\n    // Use SHA-256 for cryptographic hashing\n    const hashBytes = sha256(new TextEncoder().encode(jsonString));\n    return toHex(hashBytes);\n  }\n\n  /**\n   * Deterministic JSON replacer for consistent cache key generation.\n   *\n   * @remarks\n   * Handles BigInt serialization and sorts object keys to ensure\n   * identical objects always produce the same hash regardless of\n   * property order.\n   *\n   * @param _key - The object key being serialized (unused)\n   * @param value - The value to serialize\n   * @returns The serialized value with sorted keys for objects\n   *\n   * @internal\n   */\n  private static deterministicReplacer(_key: string, value: unknown): unknown {\n    if (typeof value === \"bigint\") {\n      return `__BIGINT__${value.toString()}`;\n    }\n    // Sort object keys for deterministic serialization\n    if (value !== null && typeof value === \"object\" && !Array.isArray(value)) {\n      return Object.keys(value as Record<string, unknown>)\n        .sort()\n        .reduce(\n          (sorted, key) => {\n            sorted[key] = (value as Record<string, unknown>)[key];\n            return sorted;\n          },\n          {} as Record<string, unknown>,\n        );\n    }\n    return value;\n  }\n}\n\n/**\n * Wraps signature operations with caching to avoid repeated prompts.\n *\n * @remarks\n * This helper function checks the cache before requesting a signature\n * and stores new signatures for future use. It significantly improves\n * UX for operations that may be retried or called multiple times.\n *\n * @param cache - The cache adapter to use for storage.\n *   Obtain from platform adapter.\n * @param walletAddress - The wallet address signing the message.\n *   Obtain from wallet connection.\n * @param typedData - The EIP-712 typed data being signed.\n *   Typically permission or grant data.\n * @param signFn - Async function that performs the actual signing.\n *   Usually calls wallet.signTypedData().\n * @param ttlHours - Cache TTL in hours.\n *   Defaults to 2 hours.\n * @returns The signature (cached or newly generated)\n *\n * @example\n * ```typescript\n * const signature = await withSignatureCache(\n *   platformAdapter.cache,\n *   walletAddress,\n *   typedData,\n *   async () => wallet.signTypedData(typedData),\n *   24 // Cache for 24 hours\n * );\n * ```\n *\n * @category Utilities\n */\nexport async function withSignatureCache(\n  cache: VanaCacheAdapter,\n  walletAddress: string,\n  typedData: Record<string, unknown>,\n  signFn: () => Promise<Hash>,\n  ttlHours?: number,\n): Promise<Hash> {\n  // Create a hash of the typed data for the cache key\n  const messageHash = SignatureCache.hashMessage(typedData);\n\n  // Try to get from cache first\n  const cached = SignatureCache.get(cache, walletAddress, messageHash);\n  if (cached) {\n    return cached;\n  }\n\n  // Not in cache, sign and store\n  const signature = await signFn();\n  SignatureCache.set(cache, walletAddress, messageHash, signature, ttlHours);\n\n  return signature;\n}\n"],"mappings":"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","names":[]}

package/dist/utils/subgraphConsistency.cjs

@@ -0,0 +1,184 @@
+"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 subgraphConsistency_exports = {};
+__export(subgraphConsistency_exports, {
+  StaleDataError: () => StaleDataError,
+  addMetaToQuery: () => addMetaToQuery,
+  calculateStaleness: () => calculateStaleness,
+  checkSubgraphConsistency: () => checkSubgraphConsistency,
+  fetchSubgraphMeta: () => fetchSubgraphMeta,
+  waitForSubgraphSync: () => waitForSubgraphSync
+});
+module.exports = __toCommonJS(subgraphConsistency_exports);
+var import_graphql = require("graphql");
+var import_subgraph = require("../generated/subgraph");
+var import_subgraphMetaCache = require("./subgraphMetaCache");
+class StaleDataError extends Error {
+  constructor(requiredBlock, currentBlock, message) {
+    super(
+      message ?? `Subgraph data is stale. Required block: ${requiredBlock}, Current block: ${currentBlock}`
+    );
+    this.requiredBlock = requiredBlock;
+    this.currentBlock = currentBlock;
+    this.name = "StaleDataError";
+  }
+}
+async function fetchSubgraphMeta(subgraphUrl, useCache = true) {
+  if (useCache) {
+    const cached = import_subgraphMetaCache.globalMetaCache.get(subgraphUrl);
+    if (cached) {
+      return cached;
+    }
+  }
+  const response = await fetch(subgraphUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      query: (0, import_graphql.print)(import_subgraph.GetSubgraphMetaDocument)
+    })
+  });
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch subgraph metadata: ${response.status} ${response.statusText}`
+    );
+  }
+  const result = await response.json();
+  if (result.errors) {
+    throw new Error(
+      `Subgraph query errors: ${result.errors.map((e) => e.message).join(", ")}`
+    );
+  }
+  if (!result.data?._meta) {
+    throw new Error("No metadata returned from subgraph");
+  }
+  const meta = result.data._meta;
+  const subgraphMeta = {
+    blockNumber: meta.block.number,
+    blockTimestamp: meta.block.timestamp ?? void 0,
+    blockHash: meta.block.hash ?? void 0,
+    deployment: meta.deployment,
+    hasIndexingErrors: meta.hasIndexingErrors
+  };
+  if (useCache) {
+    import_subgraphMetaCache.globalMetaCache.set(subgraphUrl, subgraphMeta);
+  }
+  return subgraphMeta;
+}
+async function checkSubgraphConsistency(subgraphUrl, options) {
+  if (options?.signal?.aborted) {
+    throw new Error("Operation aborted");
+  }
+  if (!options?.minBlock) {
+    return fetchSubgraphMeta(subgraphUrl);
+  }
+  const meta = await fetchSubgraphMeta(subgraphUrl);
+  if (meta.blockNumber < options.minBlock) {
+    if (options.waitForSync && options.waitForSync > 0) {
+      return waitForSubgraphSync(
+        subgraphUrl,
+        options.minBlock,
+        options.waitForSync,
+        2e3,
+        // pollInterval
+        options.signal
+      );
+    }
+    throw new StaleDataError(options.minBlock, meta.blockNumber);
+  }
+  return meta;
+}
+async function waitForSubgraphSync(subgraphUrl, targetBlock, maxWait, pollInterval = 2e3, signal) {
+  const startTime = Date.now();
+  if (signal?.aborted) {
+    throw new Error("Operation aborted");
+  }
+  const checkAbort = () => {
+    if (signal?.aborted) {
+      throw new Error("Operation aborted");
+    }
+  };
+  while (Date.now() - startTime < maxWait) {
+    checkAbort();
+    const meta = await fetchSubgraphMeta(subgraphUrl);
+    if (meta.blockNumber >= targetBlock) {
+      return meta;
+    }
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(resolve, pollInterval);
+      if (signal) {
+        const abortHandler = () => {
+          clearTimeout(timer);
+          reject(new Error("Operation aborted"));
+        };
+        if (signal.aborted) {
+          abortHandler();
+        } else {
+          signal.addEventListener("abort", abortHandler, { once: true });
+        }
+      }
+    });
+  }
+  checkAbort();
+  const finalMeta = await fetchSubgraphMeta(subgraphUrl);
+  if (finalMeta.blockNumber >= targetBlock) {
+    return finalMeta;
+  }
+  throw new StaleDataError(
+    targetBlock,
+    finalMeta.blockNumber,
+    `Subgraph did not sync to block ${targetBlock} within ${maxWait}ms. Current block: ${finalMeta.blockNumber}`
+  );
+}
+function calculateStaleness(meta, currentTimestamp) {
+  if (!meta.blockTimestamp) {
+    return void 0;
+  }
+  return Math.max(0, currentTimestamp - meta.blockTimestamp);
+}
+function addMetaToQuery(baseQuery) {
+  if (baseQuery.includes("_meta")) {
+    return baseQuery;
+  }
+  const queryMatch = baseQuery.match(/query\s+\w+[^{]*\{/);
+  if (!queryMatch) {
+    return baseQuery;
+  }
+  const insertPoint = queryMatch.index + queryMatch[0].length;
+  return baseQuery.slice(0, insertPoint) + `
+  _meta {
+    block {
+      number
+      timestamp
+    }
+    hasIndexingErrors
+  }
+  ` + baseQuery.slice(insertPoint);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StaleDataError,
+  addMetaToQuery,
+  calculateStaleness,
+  checkSubgraphConsistency,
+  fetchSubgraphMeta,
+  waitForSubgraphSync
+});
+//# sourceMappingURL=subgraphConsistency.cjs.map