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

package/dist/utils/grants.cjs

@@ -0,0 +1,108 @@
+"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 grants_exports = {};
+__export(grants_exports, {
+  checkGrantAccess: () => checkGrantAccess,
+  createAndStoreGrant: () => createAndStoreGrant,
+  createValidatedGrant: () => createValidatedGrant,
+  getGrantTimeRemaining: () => getGrantTimeRemaining,
+  isGrantExpired: () => isGrantExpired,
+  retrieveAndValidateGrant: () => retrieveAndValidateGrant,
+  summarizeGrant: () => summarizeGrant
+});
+module.exports = __toCommonJS(grants_exports);
+var import_grantFiles = require("./grantFiles");
+var import_grantValidation = require("./grantValidation");
+function createValidatedGrant(params) {
+  const grantFile = (0, import_grantFiles.createGrantFile)(params);
+  try {
+    (0, import_grantValidation.validateGrant)(grantFile, {
+      schema: true,
+      grantee: params.grantee,
+      operation: params.operation
+    });
+  } catch (error) {
+    throw new import_grantValidation.GrantValidationError(
+      `Created grant file failed validation: ${error instanceof Error ? error.message : "Unknown error"}`,
+      { grantFile, params }
+    );
+  }
+  return grantFile;
+}
+async function createAndStoreGrant(params, relayerUrl) {
+  const grantFile = createValidatedGrant(params);
+  const grantUrl = await (0, import_grantFiles.storeGrantFile)(grantFile, relayerUrl);
+  return { grantFile, grantUrl };
+}
+async function retrieveAndValidateGrant(grantUrl, relayerUrl) {
+  const grantFile = await (0, import_grantFiles.retrieveGrantFile)(grantUrl, relayerUrl);
+  return grantFile;
+}
+async function checkGrantAccess(grantUrl, requestingAddress, operation, _fileIds, relayerUrl) {
+  try {
+    const grantFile = await retrieveAndValidateGrant(grantUrl, relayerUrl);
+    (0, import_grantValidation.validateGrant)(grantFile, {
+      schema: true,
+      grantee: requestingAddress,
+      operation
+    });
+    return { allowed: true, grantFile };
+  } catch (error) {
+    if (error instanceof import_grantValidation.GrantValidationError) {
+      return {
+        allowed: false,
+        reason: error.message
+      };
+    }
+    return {
+      allowed: false,
+      reason: `Grant access check failed: ${error instanceof Error ? error.message : "Unknown error"}`
+    };
+  }
+}
+function isGrantExpired(grantFile) {
+  if (!grantFile.expires) {
+    return false;
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  return now > grantFile.expires;
+}
+function getGrantTimeRemaining(grantFile) {
+  if (!grantFile.expires) {
+    return null;
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  const remaining = grantFile.expires - now;
+  return Math.max(0, remaining);
+}
+function summarizeGrant(grantFile) {
+  const expiration = grantFile.expires ? new Date(grantFile.expires * 1e3).toISOString() : "No expiration";
+  return `Grant for ${grantFile.grantee} to perform "${grantFile.operation}" (expires: ${expiration})`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  checkGrantAccess,
+  createAndStoreGrant,
+  createValidatedGrant,
+  getGrantTimeRemaining,
+  isGrantExpired,
+  retrieveAndValidateGrant,
+  summarizeGrant
+});
+//# sourceMappingURL=grants.cjs.map

package/dist/utils/grants.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/grants.ts"],"sourcesContent":["import type { Address } from \"viem\";\nimport type { GrantFile, GrantPermissionParams } from \"../types/permissions\";\nimport {\n  createGrantFile,\n  storeGrantFile,\n  retrieveGrantFile,\n} from \"./grantFiles\";\nimport { validateGrant, GrantValidationError } from \"./grantValidation\";\n\n/**\n * High-level utilities for working with grants in the Vana SDK\n */\n\n/**\n * Creates and validates a grant file from permission parameters\n *\n * @param params - The permission parameters to create and validate the grant from\n * @returns The validated grant file object\n */\nexport function createValidatedGrant(params: GrantPermissionParams): GrantFile {\n  const grantFile = createGrantFile(params);\n\n  // Validate the created grant file\n  try {\n    validateGrant(grantFile, {\n      schema: true,\n      grantee: params.grantee,\n      operation: params.operation,\n    });\n  } catch (error) {\n    throw new GrantValidationError(\n      `Created grant file failed validation: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      { grantFile, params },\n    );\n  }\n\n  return grantFile;\n}\n\n/**\n * Creates a grant file and stores it in IPFS\n *\n * @param params - The permission parameters to create the grant from\n * @param relayerUrl - The URL of the relayer service for IPFS storage\n * @returns Promise resolving to an object containing the grant file and its IPFS URL\n */\nexport async function createAndStoreGrant(\n  params: GrantPermissionParams,\n  relayerUrl: string,\n): Promise<{ grantFile: GrantFile; grantUrl: string }> {\n  const grantFile = createValidatedGrant(params);\n  const grantUrl = await storeGrantFile(grantFile, relayerUrl);\n\n  return { grantFile, grantUrl };\n}\n\n/**\n * Retrieves and validates a grant file from IPFS\n *\n * @param grantUrl - The IPFS URL of the grant file to retrieve\n * @param relayerUrl - Optional URL of the relayer service\n * @returns Promise resolving to the validated grant file\n */\nexport async function retrieveAndValidateGrant(\n  grantUrl: string,\n  relayerUrl?: string,\n): Promise<GrantFile> {\n  const grantFile = await retrieveGrantFile(grantUrl, relayerUrl);\n\n  // Additional validation can be added here if needed\n  return grantFile;\n}\n\n/**\n * Checks if a grant allows access for a specific request\n *\n * @param grantUrl - The IPFS URL of the grant file to check\n * @param requestingAddress - The address making the access request\n * @param operation - The operation being requested\n * @param _fileIds - Array of file IDs being accessed (currently unused but part of interface)\n * @param relayerUrl - Optional URL of the relayer service\n * @returns Promise resolving to access result with allowed status, reason, and grant file\n */\nexport async function checkGrantAccess(\n  grantUrl: string,\n  requestingAddress: Address,\n  operation: string,\n  _fileIds: number[],\n  relayerUrl?: string,\n): Promise<{ allowed: boolean; reason?: string; grantFile?: GrantFile }> {\n  try {\n    const grantFile = await retrieveAndValidateGrant(grantUrl, relayerUrl);\n\n    // Validate the grant for the request\n    validateGrant(grantFile, {\n      schema: true,\n      grantee: requestingAddress,\n      operation,\n    });\n\n    return { allowed: true, grantFile };\n  } catch (error) {\n    if (error instanceof GrantValidationError) {\n      return {\n        allowed: false,\n        reason: error.message,\n      };\n    }\n\n    return {\n      allowed: false,\n      reason: `Grant access check failed: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n    };\n  }\n}\n\n/**\n * Utility to check if a grant has expired\n *\n * @param grantFile - The grant file to check for expiration\n * @returns True if the grant has expired, false otherwise\n */\nexport function isGrantExpired(grantFile: GrantFile): boolean {\n  if (!grantFile.expires) {\n    return false; // No expiration set\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  return now > grantFile.expires;\n}\n\n/**\n * Utility to get the time remaining before grant expires (in seconds)\n *\n * @param grantFile - The grant file to check time remaining for\n * @returns Number of seconds remaining, or null if no expiration is set\n */\nexport function getGrantTimeRemaining(grantFile: GrantFile): number | null {\n  if (!grantFile.expires) {\n    return null; // No expiration set\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  const remaining = grantFile.expires - now;\n  return Math.max(0, remaining);\n}\n\n/**\n * Creates a human-readable summary of a grant\n *\n * @param grantFile - The grant file to create a summary for\n * @returns A human-readable string describing the grant\n */\nexport function summarizeGrant(grantFile: GrantFile): string {\n  const expiration = grantFile.expires\n    ? new Date(grantFile.expires * 1000).toISOString()\n    : \"No expiration\";\n\n  return `Grant for ${grantFile.grantee} to perform \"${grantFile.operation}\" (expires: ${expiration})`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA,wBAIO;AACP,6BAAoD;AAY7C,SAAS,qBAAqB,QAA0C;AAC7E,QAAM,gBAAY,mCAAgB,MAAM;AAGxC,MAAI;AACF,8CAAc,WAAW;AAAA,MACvB,QAAQ;AAAA,MACR,SAAS,OAAO;AAAA,MAChB,WAAW,OAAO;AAAA,IACpB,CAAC;AAAA,EACH,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,yCAAyC,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,MACjG,EAAE,WAAW,OAAO;AAAA,IACtB;AAAA,EACF;AAEA,SAAO;AACT;AASA,eAAsB,oBACpB,QACA,YACqD;AACrD,QAAM,YAAY,qBAAqB,MAAM;AAC7C,QAAM,WAAW,UAAM,kCAAe,WAAW,UAAU;AAE3D,SAAO,EAAE,WAAW,SAAS;AAC/B;AASA,eAAsB,yBACpB,UACA,YACoB;AACpB,QAAM,YAAY,UAAM,qCAAkB,UAAU,UAAU;AAG9D,SAAO;AACT;AAYA,eAAsB,iBACpB,UACA,mBACA,WACA,UACA,YACuE;AACvE,MAAI;AACF,UAAM,YAAY,MAAM,yBAAyB,UAAU,UAAU;AAGrE,8CAAc,WAAW;AAAA,MACvB,QAAQ;AAAA,MACR,SAAS;AAAA,MACT;AAAA,IACF,CAAC;AAED,WAAO,EAAE,SAAS,MAAM,UAAU;AAAA,EACpC,SAAS,OAAO;AACd,QAAI,iBAAiB,6CAAsB;AACzC,aAAO;AAAA,QACL,SAAS;AAAA,QACT,QAAQ,MAAM;AAAA,MAChB;AAAA,IACF;AAEA,WAAO;AAAA,MACL,SAAS;AAAA,MACT,QAAQ,8BAA8B,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,IAChG;AAAA,EACF;AACF;AAQO,SAAS,eAAe,WAA+B;AAC5D,MAAI,CAAC,UAAU,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,SAAO,MAAM,UAAU;AACzB;AAQO,SAAS,sBAAsB,WAAqC;AACzE,MAAI,CAAC,UAAU,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,YAAY,UAAU,UAAU;AACtC,SAAO,KAAK,IAAI,GAAG,SAAS;AAC9B;AAQO,SAAS,eAAe,WAA8B;AAC3D,QAAM,aAAa,UAAU,UACzB,IAAI,KAAK,UAAU,UAAU,GAAI,EAAE,YAAY,IAC/C;AAEJ,SAAO,aAAa,UAAU,OAAO,gBAAgB,UAAU,SAAS,eAAe,UAAU;AACnG;","names":[]}

package/dist/utils/grants.d.ts

@@ -0,0 +1,67 @@
+import type { Address } from "viem";
+import type { GrantFile, GrantPermissionParams } from "../types/permissions";
+/**
+ * High-level utilities for working with grants in the Vana SDK
+ */
+/**
+ * Creates and validates a grant file from permission parameters
+ *
+ * @param params - The permission parameters to create and validate the grant from
+ * @returns The validated grant file object
+ */
+export declare function createValidatedGrant(params: GrantPermissionParams): GrantFile;
+/**
+ * Creates a grant file and stores it in IPFS
+ *
+ * @param params - The permission parameters to create the grant from
+ * @param relayerUrl - The URL of the relayer service for IPFS storage
+ * @returns Promise resolving to an object containing the grant file and its IPFS URL
+ */
+export declare function createAndStoreGrant(params: GrantPermissionParams, relayerUrl: string): Promise<{
+    grantFile: GrantFile;
+    grantUrl: string;
+}>;
+/**
+ * Retrieves and validates a grant file from IPFS
+ *
+ * @param grantUrl - The IPFS URL of the grant file to retrieve
+ * @param relayerUrl - Optional URL of the relayer service
+ * @returns Promise resolving to the validated grant file
+ */
+export declare function retrieveAndValidateGrant(grantUrl: string, relayerUrl?: string): Promise<GrantFile>;
+/**
+ * Checks if a grant allows access for a specific request
+ *
+ * @param grantUrl - The IPFS URL of the grant file to check
+ * @param requestingAddress - The address making the access request
+ * @param operation - The operation being requested
+ * @param _fileIds - Array of file IDs being accessed (currently unused but part of interface)
+ * @param relayerUrl - Optional URL of the relayer service
+ * @returns Promise resolving to access result with allowed status, reason, and grant file
+ */
+export declare function checkGrantAccess(grantUrl: string, requestingAddress: Address, operation: string, _fileIds: number[], relayerUrl?: string): Promise<{
+    allowed: boolean;
+    reason?: string;
+    grantFile?: GrantFile;
+}>;
+/**
+ * Utility to check if a grant has expired
+ *
+ * @param grantFile - The grant file to check for expiration
+ * @returns True if the grant has expired, false otherwise
+ */
+export declare function isGrantExpired(grantFile: GrantFile): boolean;
+/**
+ * Utility to get the time remaining before grant expires (in seconds)
+ *
+ * @param grantFile - The grant file to check time remaining for
+ * @returns Number of seconds remaining, or null if no expiration is set
+ */
+export declare function getGrantTimeRemaining(grantFile: GrantFile): number | null;
+/**
+ * Creates a human-readable summary of a grant
+ *
+ * @param grantFile - The grant file to create a summary for
+ * @returns A human-readable string describing the grant
+ */
+export declare function summarizeGrant(grantFile: GrantFile): string;

package/dist/utils/grants.js

@@ -0,0 +1,82 @@
+import {
+  createGrantFile,
+  storeGrantFile,
+  retrieveGrantFile
+} from "./grantFiles";
+import { validateGrant, GrantValidationError } from "./grantValidation";
+function createValidatedGrant(params) {
+  const grantFile = createGrantFile(params);
+  try {
+    validateGrant(grantFile, {
+      schema: true,
+      grantee: params.grantee,
+      operation: params.operation
+    });
+  } catch (error) {
+    throw new GrantValidationError(
+      `Created grant file failed validation: ${error instanceof Error ? error.message : "Unknown error"}`,
+      { grantFile, params }
+    );
+  }
+  return grantFile;
+}
+async function createAndStoreGrant(params, relayerUrl) {
+  const grantFile = createValidatedGrant(params);
+  const grantUrl = await storeGrantFile(grantFile, relayerUrl);
+  return { grantFile, grantUrl };
+}
+async function retrieveAndValidateGrant(grantUrl, relayerUrl) {
+  const grantFile = await retrieveGrantFile(grantUrl, relayerUrl);
+  return grantFile;
+}
+async function checkGrantAccess(grantUrl, requestingAddress, operation, _fileIds, relayerUrl) {
+  try {
+    const grantFile = await retrieveAndValidateGrant(grantUrl, relayerUrl);
+    validateGrant(grantFile, {
+      schema: true,
+      grantee: requestingAddress,
+      operation
+    });
+    return { allowed: true, grantFile };
+  } catch (error) {
+    if (error instanceof GrantValidationError) {
+      return {
+        allowed: false,
+        reason: error.message
+      };
+    }
+    return {
+      allowed: false,
+      reason: `Grant access check failed: ${error instanceof Error ? error.message : "Unknown error"}`
+    };
+  }
+}
+function isGrantExpired(grantFile) {
+  if (!grantFile.expires) {
+    return false;
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  return now > grantFile.expires;
+}
+function getGrantTimeRemaining(grantFile) {
+  if (!grantFile.expires) {
+    return null;
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  const remaining = grantFile.expires - now;
+  return Math.max(0, remaining);
+}
+function summarizeGrant(grantFile) {
+  const expiration = grantFile.expires ? new Date(grantFile.expires * 1e3).toISOString() : "No expiration";
+  return `Grant for ${grantFile.grantee} to perform "${grantFile.operation}" (expires: ${expiration})`;
+}
+export {
+  checkGrantAccess,
+  createAndStoreGrant,
+  createValidatedGrant,
+  getGrantTimeRemaining,
+  isGrantExpired,
+  retrieveAndValidateGrant,
+  summarizeGrant
+};
+//# sourceMappingURL=grants.js.map

package/dist/utils/grants.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/grants.ts"],"sourcesContent":["import type { Address } from \"viem\";\nimport type { GrantFile, GrantPermissionParams } from \"../types/permissions\";\nimport {\n  createGrantFile,\n  storeGrantFile,\n  retrieveGrantFile,\n} from \"./grantFiles\";\nimport { validateGrant, GrantValidationError } from \"./grantValidation\";\n\n/**\n * High-level utilities for working with grants in the Vana SDK\n */\n\n/**\n * Creates and validates a grant file from permission parameters\n *\n * @param params - The permission parameters to create and validate the grant from\n * @returns The validated grant file object\n */\nexport function createValidatedGrant(params: GrantPermissionParams): GrantFile {\n  const grantFile = createGrantFile(params);\n\n  // Validate the created grant file\n  try {\n    validateGrant(grantFile, {\n      schema: true,\n      grantee: params.grantee,\n      operation: params.operation,\n    });\n  } catch (error) {\n    throw new GrantValidationError(\n      `Created grant file failed validation: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      { grantFile, params },\n    );\n  }\n\n  return grantFile;\n}\n\n/**\n * Creates a grant file and stores it in IPFS\n *\n * @param params - The permission parameters to create the grant from\n * @param relayerUrl - The URL of the relayer service for IPFS storage\n * @returns Promise resolving to an object containing the grant file and its IPFS URL\n */\nexport async function createAndStoreGrant(\n  params: GrantPermissionParams,\n  relayerUrl: string,\n): Promise<{ grantFile: GrantFile; grantUrl: string }> {\n  const grantFile = createValidatedGrant(params);\n  const grantUrl = await storeGrantFile(grantFile, relayerUrl);\n\n  return { grantFile, grantUrl };\n}\n\n/**\n * Retrieves and validates a grant file from IPFS\n *\n * @param grantUrl - The IPFS URL of the grant file to retrieve\n * @param relayerUrl - Optional URL of the relayer service\n * @returns Promise resolving to the validated grant file\n */\nexport async function retrieveAndValidateGrant(\n  grantUrl: string,\n  relayerUrl?: string,\n): Promise<GrantFile> {\n  const grantFile = await retrieveGrantFile(grantUrl, relayerUrl);\n\n  // Additional validation can be added here if needed\n  return grantFile;\n}\n\n/**\n * Checks if a grant allows access for a specific request\n *\n * @param grantUrl - The IPFS URL of the grant file to check\n * @param requestingAddress - The address making the access request\n * @param operation - The operation being requested\n * @param _fileIds - Array of file IDs being accessed (currently unused but part of interface)\n * @param relayerUrl - Optional URL of the relayer service\n * @returns Promise resolving to access result with allowed status, reason, and grant file\n */\nexport async function checkGrantAccess(\n  grantUrl: string,\n  requestingAddress: Address,\n  operation: string,\n  _fileIds: number[],\n  relayerUrl?: string,\n): Promise<{ allowed: boolean; reason?: string; grantFile?: GrantFile }> {\n  try {\n    const grantFile = await retrieveAndValidateGrant(grantUrl, relayerUrl);\n\n    // Validate the grant for the request\n    validateGrant(grantFile, {\n      schema: true,\n      grantee: requestingAddress,\n      operation,\n    });\n\n    return { allowed: true, grantFile };\n  } catch (error) {\n    if (error instanceof GrantValidationError) {\n      return {\n        allowed: false,\n        reason: error.message,\n      };\n    }\n\n    return {\n      allowed: false,\n      reason: `Grant access check failed: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n    };\n  }\n}\n\n/**\n * Utility to check if a grant has expired\n *\n * @param grantFile - The grant file to check for expiration\n * @returns True if the grant has expired, false otherwise\n */\nexport function isGrantExpired(grantFile: GrantFile): boolean {\n  if (!grantFile.expires) {\n    return false; // No expiration set\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  return now > grantFile.expires;\n}\n\n/**\n * Utility to get the time remaining before grant expires (in seconds)\n *\n * @param grantFile - The grant file to check time remaining for\n * @returns Number of seconds remaining, or null if no expiration is set\n */\nexport function getGrantTimeRemaining(grantFile: GrantFile): number | null {\n  if (!grantFile.expires) {\n    return null; // No expiration set\n  }\n\n  const now = Math.floor(Date.now() / 1000);\n  const remaining = grantFile.expires - now;\n  return Math.max(0, remaining);\n}\n\n/**\n * Creates a human-readable summary of a grant\n *\n * @param grantFile - The grant file to create a summary for\n * @returns A human-readable string describing the grant\n */\nexport function summarizeGrant(grantFile: GrantFile): string {\n  const expiration = grantFile.expires\n    ? new Date(grantFile.expires * 1000).toISOString()\n    : \"No expiration\";\n\n  return `Grant for ${grantFile.grantee} to perform \"${grantFile.operation}\" (expires: ${expiration})`;\n}\n"],"mappings":"AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,eAAe,4BAA4B;AAY7C,SAAS,qBAAqB,QAA0C;AAC7E,QAAM,YAAY,gBAAgB,MAAM;AAGxC,MAAI;AACF,kBAAc,WAAW;AAAA,MACvB,QAAQ;AAAA,MACR,SAAS,OAAO;AAAA,MAChB,WAAW,OAAO;AAAA,IACpB,CAAC;AAAA,EACH,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,yCAAyC,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,MACjG,EAAE,WAAW,OAAO;AAAA,IACtB;AAAA,EACF;AAEA,SAAO;AACT;AASA,eAAsB,oBACpB,QACA,YACqD;AACrD,QAAM,YAAY,qBAAqB,MAAM;AAC7C,QAAM,WAAW,MAAM,eAAe,WAAW,UAAU;AAE3D,SAAO,EAAE,WAAW,SAAS;AAC/B;AASA,eAAsB,yBACpB,UACA,YACoB;AACpB,QAAM,YAAY,MAAM,kBAAkB,UAAU,UAAU;AAG9D,SAAO;AACT;AAYA,eAAsB,iBACpB,UACA,mBACA,WACA,UACA,YACuE;AACvE,MAAI;AACF,UAAM,YAAY,MAAM,yBAAyB,UAAU,UAAU;AAGrE,kBAAc,WAAW;AAAA,MACvB,QAAQ;AAAA,MACR,SAAS;AAAA,MACT;AAAA,IACF,CAAC;AAED,WAAO,EAAE,SAAS,MAAM,UAAU;AAAA,EACpC,SAAS,OAAO;AACd,QAAI,iBAAiB,sBAAsB;AACzC,aAAO;AAAA,QACL,SAAS;AAAA,QACT,QAAQ,MAAM;AAAA,MAChB;AAAA,IACF;AAEA,WAAO;AAAA,MACL,SAAS;AAAA,MACT,QAAQ,8BAA8B,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,IAChG;AAAA,EACF;AACF;AAQO,SAAS,eAAe,WAA+B;AAC5D,MAAI,CAAC,UAAU,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,SAAO,MAAM,UAAU;AACzB;AAQO,SAAS,sBAAsB,WAAqC;AACzE,MAAI,CAAC,UAAU,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,YAAY,UAAU,UAAU;AACtC,SAAO,KAAK,IAAI,GAAG,SAAS;AAC9B;AAQO,SAAS,eAAe,WAA8B;AAC3D,QAAM,aAAa,UAAU,UACzB,IAAI,KAAK,UAAU,UAAU,GAAI,EAAE,YAAY,IAC/C;AAEJ,SAAO,aAAa,UAAU,OAAO,gBAAgB,UAAU,SAAS,eAAe,UAAU;AACnG;","names":[]}

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