@opendatalabs/vana-sdk 0.1.0-alpha.f54fafd → 0.1.0-alpha.f732fa2

package/dist/utils/ipfs.cjs

@@ -0,0 +1,130 @@
+"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 ipfs_exports = {};
+__export(ipfs_exports, {
+  DEFAULT_IPFS_GATEWAY: () => DEFAULT_IPFS_GATEWAY,
+  IPFS_GATEWAYS: () => IPFS_GATEWAYS,
+  convertIpfsUrl: () => convertIpfsUrl,
+  convertIpfsUrlWithFallbacks: () => convertIpfsUrlWithFallbacks,
+  extractIpfsHash: () => extractIpfsHash,
+  fetchWithFallbacks: () => fetchWithFallbacks,
+  getGatewayUrls: () => getGatewayUrls,
+  isIpfsUrl: () => isIpfsUrl
+});
+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://gateway.pinata.cloud/ipfs/",
+  // Pinata - backup option (has rate limits)
+  "https://ipfs.filebase.io/ipfs/"
+  // Filebase - emerging reliable option
+];
+function isIpfsUrl(url) {
+  return url.startsWith("ipfs://");
+}
+function convertIpfsUrl(url, gateway = DEFAULT_IPFS_GATEWAY) {
+  if (isIpfsUrl(url)) {
+    const hash = url.replace("ipfs://", "");
+    return `${gateway}${hash}`;
+  }
+  return url;
+}
+function extractIpfsHash(url) {
+  const patterns = [
+    /ipfs\/([a-zA-Z0-9]+)/,
+    // https://gateway.pinata.cloud/ipfs/HASH
+    /^ipfs:\/\/([a-zA-Z0-9]+)$/,
+    // ipfs://HASH
+    /^([a-zA-Z0-9]{46,})$/
+    // Just the hash (46+ chars for IPFS hashes)
+  ];
+  for (const pattern of patterns) {
+    const match = url.match(pattern);
+    if (match) {
+      return match[1];
+    }
+  }
+  return null;
+}
+function getGatewayUrls(hash) {
+  return IPFS_GATEWAYS.map((gateway) => `${gateway}${hash}`);
+}
+function convertIpfsUrlWithFallbacks(url) {
+  const hash = extractIpfsHash(url);
+  if (hash) {
+    return getGatewayUrls(hash);
+  }
+  return [url];
+}
+async function fetchWithFallbacks(url, options) {
+  const hash = extractIpfsHash(url);
+  if (!hash) {
+    return fetch(url, options);
+  }
+  const gatewayUrls = getGatewayUrls(hash);
+  let lastError = null;
+  for (let i = 0; i < gatewayUrls.length; i++) {
+    const gatewayUrl = gatewayUrls[i];
+    try {
+      const response = await fetch(gatewayUrl, {
+        ...options,
+        // Add timeout to avoid hanging on slow gateways
+        signal: AbortSignal.timeout(1e4)
+        // 10 second timeout
+      });
+      if (response.ok) {
+        return response;
+      }
+      if (response.status === 429) {
+        lastError = new Error(`Gateway rate limited: ${gatewayUrl}`);
+        continue;
+      }
+      lastError = new Error(`Gateway error ${response.status}: ${gatewayUrl}`);
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (lastError.message.includes("429") || lastError.name === "TimeoutError") {
+        continue;
+      }
+    }
+    if (i < gatewayUrls.length - 1) {
+      await new Promise((resolve) => setTimeout(resolve, 1e3 * (i + 1)));
+    }
+  }
+  throw new Error(
+    `All IPFS gateways failed for hash ${hash}. Last error: ${lastError?.message}`
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_IPFS_GATEWAY,
+  IPFS_GATEWAYS,
+  convertIpfsUrl,
+  convertIpfsUrlWithFallbacks,
+  extractIpfsHash,
+  fetchWithFallbacks,
+  getGatewayUrls,
+  isIpfsUrl
+});
+//# sourceMappingURL=ipfs.cjs.map

package/dist/utils/ipfs.cjs.map

@@ -0,0 +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":[]}

package/dist/utils/ipfs.d.ts

@@ -0,0 +1,88 @@
+/**
+ * IPFS URL utilities for the Vana SDK
+ *
+ * Centralized functions for handling IPFS URLs, converting them to gateway URLs,
+ * and extracting IPFS hashes from various URL formats.
+ */
+/**
+ * Default IPFS gateway URL
+ */
+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/"];
+/**
+ * Check if a URL is an IPFS URL (starts with ipfs://)
+ *
+ * @param url - The URL to check
+ * @returns True if the URL is an IPFS URL
+ */
+export declare function isIpfsUrl(url: string): boolean;
+/**
+ * Convert an IPFS URL to an HTTP gateway URL
+ *
+ * @param url - The IPFS URL to convert (e.g., "ipfs://QmHash...")
+ * @param gateway - Optional gateway URL (defaults to DEFAULT_IPFS_GATEWAY)
+ * @returns The HTTP gateway URL or original URL if not an IPFS URL
+ * @example
+ * ```ts
+ * convertIpfsUrl("ipfs://QmHash123")
+ * // Returns: "https://ipfs.io/ipfs/QmHash123"
+ *
+ * convertIpfsUrl("ipfs://QmHash123", "https://gateway.pinata.cloud/ipfs/")
+ * // Returns: "https://gateway.pinata.cloud/ipfs/QmHash123"
+ * ```
+ */
+export declare function convertIpfsUrl(url: string, gateway?: string): string;
+/**
+ * Extract IPFS hash from various URL formats
+ *
+ * **Edge Cases:**
+ * - Returns null for non-IPFS URLs or malformed hashes
+ * - Handles both CIDv0 (starts with Qm) and CIDv1 formats
+ * - Minimum 46 characters required for standalone hash detection
+ * - Gateway paths with subdirectories are not supported
+ *
+ * @param url - The URL to extract hash from
+ * @returns The IPFS hash or null if not found
+ * @example
+ * ```ts
+ * extractIpfsHash("ipfs://QmHash123") // Returns: "QmHash123"
+ * extractIpfsHash("https://gateway.pinata.cloud/ipfs/QmHash123") // Returns: "QmHash123"
+ * extractIpfsHash("QmHash123456789012345678901234567890123456") // Returns: "QmHash123456789012345678901234567890123456"
+ * extractIpfsHash("https://example.com/file.json") // Returns: null (not IPFS)
+ * extractIpfsHash("ipfs://QmHash/subdirectory") // Returns: null (subdirectories not supported)
+ * ```
+ */
+export declare function extractIpfsHash(url: string): string | null;
+/**
+ * Get multiple gateway URLs for an IPFS hash (useful for fallback)
+ *
+ * @param hash - The IPFS hash
+ * @returns Array of gateway URLs
+ */
+export declare function getGatewayUrls(hash: string): string[];
+/**
+ * Convert an IPFS URL to multiple gateway URLs for fallback
+ *
+ * @param url - The IPFS URL
+ * @returns Array of gateway URLs or original URL if not IPFS
+ */
+export declare function convertIpfsUrlWithFallbacks(url: string): string[];
+/**
+ * Fetch content from IPFS with automatic gateway fallbacks
+ *
+ * **Edge Cases:**
+ * - Non-IPFS URLs are fetched directly without fallback
+ * - 10-second timeout per gateway attempt to prevent hanging
+ * - Rate-limited gateways (429) are skipped immediately
+ * - Exponential backoff between retries (1s, 2s, 3s, etc.)
+ * - AbortSignal in options is merged with timeout signal
+ *
+ * @param url - The IPFS URL to fetch
+ * @param options - Optional fetch options
+ * @returns Promise resolving to Response object
+ * @throws Error if all gateways fail
+ */
+export declare function fetchWithFallbacks(url: string, options?: RequestInit): Promise<Response>;

package/dist/utils/ipfs.js

@@ -0,0 +1,99 @@
+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://gateway.pinata.cloud/ipfs/",
+  // Pinata - backup option (has rate limits)
+  "https://ipfs.filebase.io/ipfs/"
+  // Filebase - emerging reliable option
+];
+function isIpfsUrl(url) {
+  return url.startsWith("ipfs://");
+}
+function convertIpfsUrl(url, gateway = DEFAULT_IPFS_GATEWAY) {
+  if (isIpfsUrl(url)) {
+    const hash = url.replace("ipfs://", "");
+    return `${gateway}${hash}`;
+  }
+  return url;
+}
+function extractIpfsHash(url) {
+  const patterns = [
+    /ipfs\/([a-zA-Z0-9]+)/,
+    // https://gateway.pinata.cloud/ipfs/HASH
+    /^ipfs:\/\/([a-zA-Z0-9]+)$/,
+    // ipfs://HASH
+    /^([a-zA-Z0-9]{46,})$/
+    // Just the hash (46+ chars for IPFS hashes)
+  ];
+  for (const pattern of patterns) {
+    const match = url.match(pattern);
+    if (match) {
+      return match[1];
+    }
+  }
+  return null;
+}
+function getGatewayUrls(hash) {
+  return IPFS_GATEWAYS.map((gateway) => `${gateway}${hash}`);
+}
+function convertIpfsUrlWithFallbacks(url) {
+  const hash = extractIpfsHash(url);
+  if (hash) {
+    return getGatewayUrls(hash);
+  }
+  return [url];
+}
+async function fetchWithFallbacks(url, options) {
+  const hash = extractIpfsHash(url);
+  if (!hash) {
+    return fetch(url, options);
+  }
+  const gatewayUrls = getGatewayUrls(hash);
+  let lastError = null;
+  for (let i = 0; i < gatewayUrls.length; i++) {
+    const gatewayUrl = gatewayUrls[i];
+    try {
+      const response = await fetch(gatewayUrl, {
+        ...options,
+        // Add timeout to avoid hanging on slow gateways
+        signal: AbortSignal.timeout(1e4)
+        // 10 second timeout
+      });
+      if (response.ok) {
+        return response;
+      }
+      if (response.status === 429) {
+        lastError = new Error(`Gateway rate limited: ${gatewayUrl}`);
+        continue;
+      }
+      lastError = new Error(`Gateway error ${response.status}: ${gatewayUrl}`);
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (lastError.message.includes("429") || lastError.name === "TimeoutError") {
+        continue;
+      }
+    }
+    if (i < gatewayUrls.length - 1) {
+      await new Promise((resolve) => setTimeout(resolve, 1e3 * (i + 1)));
+    }
+  }
+  throw new Error(
+    `All IPFS gateways failed for hash ${hash}. Last error: ${lastError?.message}`
+  );
+}
+export {
+  DEFAULT_IPFS_GATEWAY,
+  IPFS_GATEWAYS,
+  convertIpfsUrl,
+  convertIpfsUrlWithFallbacks,
+  extractIpfsHash,
+  fetchWithFallbacks,
+  getGatewayUrls,
+  isIpfsUrl
+};
+//# sourceMappingURL=ipfs.js.map

package/dist/utils/ipfs.js.map

@@ -0,0 +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":[]}

package/dist/utils/lazy-import.cjs

@@ -0,0 +1,38 @@
+"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 lazy_import_exports = {};
+__export(lazy_import_exports, {
+  lazyImport: () => lazyImport
+});
+module.exports = __toCommonJS(lazy_import_exports);
+function lazyImport(importFn) {
+  let cached = null;
+  return () => {
+    cached ??= importFn().catch((err) => {
+      cached = null;
+      throw new Error("Failed to load module", { cause: err });
+    });
+    return cached;
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  lazyImport
+});
+//# sourceMappingURL=lazy-import.cjs.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,43 @@
+/**
+ * Provides lazy module loading to avoid Temporal Dead Zone issues.
+ *
+ * @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 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.
+ *   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

@@ -0,0 +1,14 @@
+function lazyImport(importFn) {
+  let cached = null;
+  return () => {
+    cached ??= importFn().catch((err) => {
+      cached = null;
+      throw new Error("Failed to load module", { cause: err });
+    });
+    return cached;
+  };
+}
+export {
+  lazyImport
+};
+//# sourceMappingURL=lazy-import.js.map

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

@@ -0,0 +1 @@
+{"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":[]}