@opendatalabs/vana-sdk 0.1.0-alpha.7e71046 → 0.1.0-alpha.7ee7635

package/dist/utils/transactionHelpers.d.ts

@@ -0,0 +1,86 @@
+import { Hash, Address } from 'viem';
+import { TransactionResult } from '../types/operations.js';
+import { Contract, Fn } from '../generated/event-types.js';
+import '../generated/server/server-exports.js';
+import '../generated/server/server.js';
+
+/**
+ * Helper functions for creating typed transaction POJOs
+ */
+
+/**
+ * Creates a strongly-typed TransactionResult POJO.
+ *
+ * @remarks
+ * This helper ensures all required fields are present and typed correctly,
+ * reducing boilerplate and preventing mistakes.
+ *
+ * @param input - Transaction details
+ * @param input.hash - Transaction hash
+ * @param input.from - Transaction sender address
+ * @param input.contract - Contract name
+ * @param input.fn - Function name
+ * @param input.chainId - Optional chain ID
+ * @param input.value - Optional transaction value
+ * @param input.nonce - Optional nonce
+ * @param input.to - Optional recipient address
+ * @returns Typed TransactionResult
+ *
+ * @example
+ * ```typescript
+ * return tx({
+ *   hash,
+ *   from: account.address,
+ *   contract: "DataPortabilityPermissions",
+ *   fn: "revokePermission",
+ * });
+ * ```
+ */
+declare function tx<C extends Contract, F extends Fn<C>>(input: {
+    hash: Hash;
+    from: Address;
+    contract: C;
+    fn: F;
+    chainId?: number;
+    value?: bigint;
+    nonce?: number;
+    to?: Address;
+}): TransactionResult<C, F>;
+/**
+ * Creates a transaction result with literal type inference.
+ * Use this when you need TypeScript to preserve exact string literals.
+ *
+ * @param input - Transaction details
+ * @param input.hash - Transaction hash
+ * @param input.from - Transaction sender address
+ * @param input.contract - Contract name
+ * @param input.fn - Function name
+ * @param input.chainId - Optional chain ID
+ * @param input.value - Optional transaction value
+ * @param input.nonce - Optional nonce
+ * @param input.to - Optional recipient address
+ * @returns Typed TransactionResult
+ *
+ * @example
+ * ```typescript
+ * const transaction = txLiteral({
+ *   hash: '0x...',
+ *   from: '0x...',
+ *   contract: "DataPortabilityPermissions",
+ *   fn: "revokePermission",
+ * });
+ * // TypeScript knows exactly: DataPortabilityPermissions + revokePermission
+ * ```
+ */
+declare function txLiteral<const C extends Contract, const F extends Fn<C>>(input: {
+    hash: Hash;
+    from: Address;
+    contract: C;
+    fn: F;
+    chainId?: number;
+    value?: bigint;
+    nonce?: number;
+    to?: Address;
+}): TransactionResult<C, F>;
+
+export { tx, txLiteral };

package/dist/utils/transactionHelpers.js

@@ -0,0 +1,29 @@
+function tx(input) {
+  return {
+    hash: input.hash,
+    from: input.from,
+    contract: input.contract,
+    fn: input.fn,
+    ...input.chainId !== void 0 && { chainId: input.chainId },
+    ...input.value !== void 0 && { value: input.value },
+    ...input.nonce !== void 0 && { nonce: input.nonce },
+    ...input.to !== void 0 && { to: input.to }
+  };
+}
+function txLiteral(input) {
+  return {
+    hash: input.hash,
+    from: input.from,
+    contract: input.contract,
+    fn: input.fn,
+    ...input.chainId !== void 0 && { chainId: input.chainId },
+    ...input.value !== void 0 && { value: input.value },
+    ...input.nonce !== void 0 && { nonce: input.nonce },
+    ...input.to !== void 0 && { to: input.to }
+  };
+}
+export {
+  tx,
+  txLiteral
+};
+//# sourceMappingURL=transactionHelpers.js.map

package/dist/utils/transactionHelpers.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/transactionHelpers.ts"],"sourcesContent":["/**\n * Helper functions for creating typed transaction POJOs\n */\n\nimport type { Hash, Address } from 'viem';\nimport type { TransactionResult } from '../types/operations';\nimport type { Contract, Fn } from '../generated/event-types';\n\n/**\n * Creates a strongly-typed TransactionResult POJO.\n * \n * @remarks\n * This helper ensures all required fields are present and typed correctly,\n * reducing boilerplate and preventing mistakes.\n * \n * @param input - Transaction details\n * @param input.hash - Transaction hash\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name\n * @param input.fn - Function name\n * @param input.chainId - Optional chain ID\n * @param input.value - Optional transaction value\n * @param input.nonce - Optional nonce\n * @param input.to - Optional recipient address\n * @returns Typed TransactionResult\n * \n * @example\n * ```typescript\n * return tx({\n *   hash,\n *   from: account.address,\n *   contract: \"DataPortabilityPermissions\",\n *   fn: \"revokePermission\",\n * });\n * ```\n */\nexport function tx<C extends Contract, F extends Fn<C>>(input: {\n  hash: Hash;\n  from: Address;\n  contract: C;\n  fn: F;\n  chainId?: number;\n  value?: bigint;\n  nonce?: number;\n  to?: Address;\n}): TransactionResult<C, F> {\n  // Create a new plain object to ensure independence and true POJO behavior\n  return {\n    hash: input.hash,\n    from: input.from,\n    contract: input.contract,\n    fn: input.fn,\n    ...(input.chainId !== undefined && { chainId: input.chainId }),\n    ...(input.value !== undefined && { value: input.value }),\n    ...(input.nonce !== undefined && { nonce: input.nonce }),\n    ...(input.to !== undefined && { to: input.to }),\n  };\n}\n\n/**\n * Creates a transaction result with literal type inference.\n * Use this when you need TypeScript to preserve exact string literals.\n * \n * @param input - Transaction details\n * @param input.hash - Transaction hash\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name\n * @param input.fn - Function name\n * @param input.chainId - Optional chain ID\n * @param input.value - Optional transaction value\n * @param input.nonce - Optional nonce\n * @param input.to - Optional recipient address\n * @returns Typed TransactionResult\n * \n * @example\n * ```typescript\n * const transaction = txLiteral({\n *   hash: '0x...',\n *   from: '0x...',\n *   contract: \"DataPortabilityPermissions\",\n *   fn: \"revokePermission\",\n * });\n * // TypeScript knows exactly: DataPortabilityPermissions + revokePermission\n * ```\n */\nexport function txLiteral<\n  const C extends Contract,\n  const F extends Fn<C>\n>(input: {\n  hash: Hash;\n  from: Address;\n  contract: C;\n  fn: F;\n  chainId?: number;\n  value?: bigint;\n  nonce?: number;\n  to?: Address;\n}): TransactionResult<C, F> {\n  // Create a new plain object to ensure independence and true POJO behavior\n  return {\n    hash: input.hash,\n    from: input.from,\n    contract: input.contract,\n    fn: input.fn,\n    ...(input.chainId !== undefined && { chainId: input.chainId }),\n    ...(input.value !== undefined && { value: input.value }),\n    ...(input.nonce !== undefined && { nonce: input.nonce }),\n    ...(input.to !== undefined && { to: input.to }),\n  };\n}"],"mappings":"AAoCO,SAAS,GAAwC,OAS5B;AAE1B,SAAO;AAAA,IACL,MAAM,MAAM;AAAA,IACZ,MAAM,MAAM;AAAA,IACZ,UAAU,MAAM;AAAA,IAChB,IAAI,MAAM;AAAA,IACV,GAAI,MAAM,YAAY,UAAa,EAAE,SAAS,MAAM,QAAQ;AAAA,IAC5D,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,OAAO,UAAa,EAAE,IAAI,MAAM,GAAG;AAAA,EAC/C;AACF;AA4BO,SAAS,UAGd,OAS0B;AAE1B,SAAO;AAAA,IACL,MAAM,MAAM;AAAA,IACZ,MAAM,MAAM;AAAA,IACZ,UAAU,MAAM;AAAA,IAChB,IAAI,MAAM;AAAA,IACV,GAAI,MAAM,YAAY,UAAa,EAAE,SAAS,MAAM,QAAQ;AAAA,IAC5D,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,UAAU,UAAa,EAAE,OAAO,MAAM,MAAM;AAAA,IACtD,GAAI,MAAM,OAAO,UAAa,EAAE,IAAI,MAAM,GAAG;AAAA,EAC/C;AACF;","names":[]}

package/dist/utils/typedDataConverter.cjs

@@ -0,0 +1,43 @@
+"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 typedDataConverter_exports = {};
+__export(typedDataConverter_exports, {
+  toViemTypedDataDefinition: () => toViemTypedDataDefinition
+});
+module.exports = __toCommonJS(typedDataConverter_exports);
+function toViemTypedDataDefinition(typedData) {
+  const viemTypes = {};
+  for (const [typeName, typeArray] of Object.entries(typedData.types)) {
+    viemTypes[typeName] = typeArray.map((field) => ({
+      name: field.name,
+      type: field.type
+    }));
+  }
+  return {
+    domain: typedData.domain,
+    types: viemTypes,
+    primaryType: typedData.primaryType,
+    message: typedData.message
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  toViemTypedDataDefinition
+});
+//# sourceMappingURL=typedDataConverter.cjs.map

package/dist/utils/typedDataConverter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/typedDataConverter.ts"],"sourcesContent":["import type { TypedDataDefinition } from \"viem\";\nimport type { GenericTypedData } from \"../types/permissions\";\n\n/**\n * Converts a GenericTypedData object to a Viem-compatible TypedDataDefinition.\n * This function ensures type safety when passing typed data to viem's signTypedData method.\n *\n * @param typedData - The typed data object to convert\n * @returns A properly typed TypedDataDefinition for use with viem\n */\nexport function toViemTypedDataDefinition(\n  typedData: GenericTypedData,\n): TypedDataDefinition {\n  // Transform the types to match viem's expected format with readonly arrays\n  const viemTypes: Record<string, readonly { name: string; type: string }[]> =\n    {};\n\n  for (const [typeName, typeArray] of Object.entries(typedData.types)) {\n    // Create a new readonly array for each type\n    viemTypes[typeName] = typeArray.map((field) => ({\n      name: field.name,\n      type: field.type,\n    })) as readonly { name: string; type: string }[];\n  }\n\n  return {\n    domain: typedData.domain,\n    types: viemTypes as TypedDataDefinition[\"types\"],\n    primaryType: typedData.primaryType,\n    message: typedData.message,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAUO,SAAS,0BACd,WACqB;AAErB,QAAM,YACJ,CAAC;AAEH,aAAW,CAAC,UAAU,SAAS,KAAK,OAAO,QAAQ,UAAU,KAAK,GAAG;AAEnE,cAAU,QAAQ,IAAI,UAAU,IAAI,CAAC,WAAW;AAAA,MAC9C,MAAM,MAAM;AAAA,MACZ,MAAM,MAAM;AAAA,IACd,EAAE;AAAA,EACJ;AAEA,SAAO;AAAA,IACL,QAAQ,UAAU;AAAA,IAClB,OAAO;AAAA,IACP,aAAa,UAAU;AAAA,IACvB,SAAS,UAAU;AAAA,EACrB;AACF;","names":[]}

package/dist/utils/typedDataConverter.d.cts

@@ -0,0 +1,13 @@
+import { TypedDataDefinition } from 'viem';
+import { GenericTypedData } from '../types/permissions.cjs';
+
+/**
+ * Converts a GenericTypedData object to a Viem-compatible TypedDataDefinition.
+ * This function ensures type safety when passing typed data to viem's signTypedData method.
+ *
+ * @param typedData - The typed data object to convert
+ * @returns A properly typed TypedDataDefinition for use with viem
+ */
+declare function toViemTypedDataDefinition(typedData: GenericTypedData): TypedDataDefinition;
+
+export { toViemTypedDataDefinition };

package/dist/utils/typedDataConverter.d.ts

@@ -0,0 +1,13 @@
+import { TypedDataDefinition } from 'viem';
+import { GenericTypedData } from '../types/permissions.js';
+
+/**
+ * Converts a GenericTypedData object to a Viem-compatible TypedDataDefinition.
+ * This function ensures type safety when passing typed data to viem's signTypedData method.
+ *
+ * @param typedData - The typed data object to convert
+ * @returns A properly typed TypedDataDefinition for use with viem
+ */
+declare function toViemTypedDataDefinition(typedData: GenericTypedData): TypedDataDefinition;
+
+export { toViemTypedDataDefinition };

package/dist/utils/typedDataConverter.js

@@ -0,0 +1,19 @@
+function toViemTypedDataDefinition(typedData) {
+  const viemTypes = {};
+  for (const [typeName, typeArray] of Object.entries(typedData.types)) {
+    viemTypes[typeName] = typeArray.map((field) => ({
+      name: field.name,
+      type: field.type
+    }));
+  }
+  return {
+    domain: typedData.domain,
+    types: viemTypes,
+    primaryType: typedData.primaryType,
+    message: typedData.message
+  };
+}
+export {
+  toViemTypedDataDefinition
+};
+//# sourceMappingURL=typedDataConverter.js.map

package/dist/utils/typedDataConverter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/typedDataConverter.ts"],"sourcesContent":["import type { TypedDataDefinition } from \"viem\";\nimport type { GenericTypedData } from \"../types/permissions\";\n\n/**\n * Converts a GenericTypedData object to a Viem-compatible TypedDataDefinition.\n * This function ensures type safety when passing typed data to viem's signTypedData method.\n *\n * @param typedData - The typed data object to convert\n * @returns A properly typed TypedDataDefinition for use with viem\n */\nexport function toViemTypedDataDefinition(\n  typedData: GenericTypedData,\n): TypedDataDefinition {\n  // Transform the types to match viem's expected format with readonly arrays\n  const viemTypes: Record<string, readonly { name: string; type: string }[]> =\n    {};\n\n  for (const [typeName, typeArray] of Object.entries(typedData.types)) {\n    // Create a new readonly array for each type\n    viemTypes[typeName] = typeArray.map((field) => ({\n      name: field.name,\n      type: field.type,\n    })) as readonly { name: string; type: string }[];\n  }\n\n  return {\n    domain: typedData.domain,\n    types: viemTypes as TypedDataDefinition[\"types\"],\n    primaryType: typedData.primaryType,\n    message: typedData.message,\n  };\n}\n"],"mappings":"AAUO,SAAS,0BACd,WACqB;AAErB,QAAM,YACJ,CAAC;AAEH,aAAW,CAAC,UAAU,SAAS,KAAK,OAAO,QAAQ,UAAU,KAAK,GAAG;AAEnE,cAAU,QAAQ,IAAI,UAAU,IAAI,CAAC,WAAW;AAAA,MAC9C,MAAM,MAAM;AAAA,MACZ,MAAM,MAAM;AAAA,IACd,EAAE;AAAA,EACJ;AAEA,SAAO;AAAA,IACL,QAAQ,UAAU;AAAA,IAClB,OAAO;AAAA,IACP,aAAa,UAAU;AAAA,IACvB,SAAS,UAAU;AAAA,EACrB;AACF;","names":[]}

package/dist/utils/urlResolver.cjs

@@ -0,0 +1,55 @@
+"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 urlResolver_exports = {};
+__export(urlResolver_exports, {
+  UrlResolutionError: () => UrlResolutionError,
+  fetchFromUrl: () => fetchFromUrl
+});
+module.exports = __toCommonJS(urlResolver_exports);
+var import_download = require("./download");
+class UrlResolutionError extends Error {
+  constructor(message, url, cause) {
+    super(message);
+    this.url = url;
+    this.cause = cause;
+    this.name = "UrlResolutionError";
+  }
+}
+async function fetchFromUrl(url, downloadRelayer) {
+  try {
+    const response = await (0, import_download.fetchWithRelayer)(url, downloadRelayer);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    throw new UrlResolutionError(
+      `Failed to fetch from ${url}: ${error instanceof Error ? error.message : "Unknown error"}`,
+      url,
+      error instanceof Error ? error : void 0
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  UrlResolutionError,
+  fetchFromUrl
+});
+//# sourceMappingURL=urlResolver.cjs.map

package/dist/utils/urlResolver.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/urlResolver.ts"],"sourcesContent":["/**\n * Universal URL resolver for the Vana SDK\n *\n * Handles fetching data from various protocols (IPFS, HTTP, Arweave, etc.)\n * in a consistent, reliable way.\n */\n\nimport { fetchWithRelayer } from \"./download\";\n\n/**\n * Error thrown when URL resolution fails\n */\nexport class UrlResolutionError extends Error {\n  constructor(\n    message: string,\n    public readonly url: string,\n    public override readonly cause?: Error,\n  ) {\n    super(message);\n    this.name = \"UrlResolutionError\";\n  }\n}\n\n/**\n * Fetches and parses JSON data from any supported URL protocol\n *\n * @param url - The URL to fetch from (supports ipfs://, https://, http://, ar://)\n * @param downloadRelayer - Optional download relayer for CORS bypass\n * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n * @returns Promise resolving to the parsed JSON data\n * @throws {UrlResolutionError} When the URL cannot be resolved or parsed\n *\n * @example\n * ```typescript\n * // Fetch from IPFS\n * const data = await fetchFromUrl(\"ipfs://QmXxx...\");\n *\n * // Fetch from HTTPS\n * const data = await fetchFromUrl(\"https://example.com/data.json\");\n *\n * // Handles protocol conversion internally\n * const schema = await fetchFromUrl(schemaDefinitionUrl);\n * ```\n */\nexport async function fetchFromUrl(\n  url: string,\n  downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n): Promise<unknown> {\n  try {\n    // Use unified download utility with automatic fallbacks\n    const response = await fetchWithRelayer(url, downloadRelayer);\n\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n    }\n\n    // Parse JSON response\n    const data = await response.json();\n    return data;\n  } catch (error) {\n    throw new UrlResolutionError(\n      `Failed to fetch from ${url}: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      url,\n      error instanceof Error ? error : undefined,\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,sBAAiC;AAK1B,MAAM,2BAA2B,MAAM;AAAA,EAC5C,YACE,SACgB,KACS,OACzB;AACA,UAAM,OAAO;AAHG;AACS;AAGzB,SAAK,OAAO;AAAA,EACd;AACF;AAuBA,eAAsB,aACpB,KACA,iBACkB;AAClB,MAAI;AAEF,UAAM,WAAW,UAAM,kCAAiB,KAAK,eAAe;AAE5D,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,IAAI,MAAM,QAAQ,SAAS,MAAM,KAAK,SAAS,UAAU,EAAE;AAAA,IACnE;AAGA,UAAM,OAAO,MAAM,SAAS,KAAK;AACjC,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,wBAAwB,GAAG,KAAK,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,MACxF;AAAA,MACA,iBAAiB,QAAQ,QAAQ;AAAA,IACnC;AAAA,EACF;AACF;","names":[]}

package/dist/utils/urlResolver.d.cts

@@ -0,0 +1,40 @@
+/**
+ * Universal URL resolver for the Vana SDK
+ *
+ * Handles fetching data from various protocols (IPFS, HTTP, Arweave, etc.)
+ * in a consistent, reliable way.
+ */
+/**
+ * Error thrown when URL resolution fails
+ */
+declare class UrlResolutionError extends Error {
+    readonly url: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, url: string, cause?: Error | undefined);
+}
+/**
+ * Fetches and parses JSON data from any supported URL protocol
+ *
+ * @param url - The URL to fetch from (supports ipfs://, https://, http://, ar://)
+ * @param downloadRelayer - Optional download relayer for CORS bypass
+ * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server
+ * @returns Promise resolving to the parsed JSON data
+ * @throws {UrlResolutionError} When the URL cannot be resolved or parsed
+ *
+ * @example
+ * ```typescript
+ * // Fetch from IPFS
+ * const data = await fetchFromUrl("ipfs://QmXxx...");
+ *
+ * // Fetch from HTTPS
+ * const data = await fetchFromUrl("https://example.com/data.json");
+ *
+ * // Handles protocol conversion internally
+ * const schema = await fetchFromUrl(schemaDefinitionUrl);
+ * ```
+ */
+declare function fetchFromUrl(url: string, downloadRelayer?: {
+    proxyDownload: (url: string) => Promise<Blob>;
+}): Promise<unknown>;
+
+export { UrlResolutionError, fetchFromUrl };

package/dist/utils/urlResolver.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Universal URL resolver for the Vana SDK
+ *
+ * Handles fetching data from various protocols (IPFS, HTTP, Arweave, etc.)
+ * in a consistent, reliable way.
+ */
+/**
+ * Error thrown when URL resolution fails
+ */
+declare class UrlResolutionError extends Error {
+    readonly url: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, url: string, cause?: Error | undefined);
+}
+/**
+ * Fetches and parses JSON data from any supported URL protocol
+ *
+ * @param url - The URL to fetch from (supports ipfs://, https://, http://, ar://)
+ * @param downloadRelayer - Optional download relayer for CORS bypass
+ * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server
+ * @returns Promise resolving to the parsed JSON data
+ * @throws {UrlResolutionError} When the URL cannot be resolved or parsed
+ *
+ * @example
+ * ```typescript
+ * // Fetch from IPFS
+ * const data = await fetchFromUrl("ipfs://QmXxx...");
+ *
+ * // Fetch from HTTPS
+ * const data = await fetchFromUrl("https://example.com/data.json");
+ *
+ * // Handles protocol conversion internally
+ * const schema = await fetchFromUrl(schemaDefinitionUrl);
+ * ```
+ */
+declare function fetchFromUrl(url: string, downloadRelayer?: {
+    proxyDownload: (url: string) => Promise<Blob>;
+}): Promise<unknown>;
+
+export { UrlResolutionError, fetchFromUrl };

package/dist/utils/urlResolver.js

@@ -0,0 +1,30 @@
+import { fetchWithRelayer } from "./download";
+class UrlResolutionError extends Error {
+  constructor(message, url, cause) {
+    super(message);
+    this.url = url;
+    this.cause = cause;
+    this.name = "UrlResolutionError";
+  }
+}
+async function fetchFromUrl(url, downloadRelayer) {
+  try {
+    const response = await fetchWithRelayer(url, downloadRelayer);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    throw new UrlResolutionError(
+      `Failed to fetch from ${url}: ${error instanceof Error ? error.message : "Unknown error"}`,
+      url,
+      error instanceof Error ? error : void 0
+    );
+  }
+}
+export {
+  UrlResolutionError,
+  fetchFromUrl
+};
+//# sourceMappingURL=urlResolver.js.map

package/dist/utils/urlResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/urlResolver.ts"],"sourcesContent":["/**\n * Universal URL resolver for the Vana SDK\n *\n * Handles fetching data from various protocols (IPFS, HTTP, Arweave, etc.)\n * in a consistent, reliable way.\n */\n\nimport { fetchWithRelayer } from \"./download\";\n\n/**\n * Error thrown when URL resolution fails\n */\nexport class UrlResolutionError extends Error {\n  constructor(\n    message: string,\n    public readonly url: string,\n    public override readonly cause?: Error,\n  ) {\n    super(message);\n    this.name = \"UrlResolutionError\";\n  }\n}\n\n/**\n * Fetches and parses JSON data from any supported URL protocol\n *\n * @param url - The URL to fetch from (supports ipfs://, https://, http://, ar://)\n * @param downloadRelayer - Optional download relayer for CORS bypass\n * @param downloadRelayer.proxyDownload - Function to proxy downloads through application server\n * @returns Promise resolving to the parsed JSON data\n * @throws {UrlResolutionError} When the URL cannot be resolved or parsed\n *\n * @example\n * ```typescript\n * // Fetch from IPFS\n * const data = await fetchFromUrl(\"ipfs://QmXxx...\");\n *\n * // Fetch from HTTPS\n * const data = await fetchFromUrl(\"https://example.com/data.json\");\n *\n * // Handles protocol conversion internally\n * const schema = await fetchFromUrl(schemaDefinitionUrl);\n * ```\n */\nexport async function fetchFromUrl(\n  url: string,\n  downloadRelayer?: { proxyDownload: (url: string) => Promise<Blob> },\n): Promise<unknown> {\n  try {\n    // Use unified download utility with automatic fallbacks\n    const response = await fetchWithRelayer(url, downloadRelayer);\n\n    if (!response.ok) {\n      throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n    }\n\n    // Parse JSON response\n    const data = await response.json();\n    return data;\n  } catch (error) {\n    throw new UrlResolutionError(\n      `Failed to fetch from ${url}: ${error instanceof Error ? error.message : \"Unknown error\"}`,\n      url,\n      error instanceof Error ? error : undefined,\n    );\n  }\n}\n"],"mappings":"AAOA,SAAS,wBAAwB;AAK1B,MAAM,2BAA2B,MAAM;AAAA,EAC5C,YACE,SACgB,KACS,OACzB;AACA,UAAM,OAAO;AAHG;AACS;AAGzB,SAAK,OAAO;AAAA,EACd;AACF;AAuBA,eAAsB,aACpB,KACA,iBACkB;AAClB,MAAI;AAEF,UAAM,WAAW,MAAM,iBAAiB,KAAK,eAAe;AAE5D,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,IAAI,MAAM,QAAQ,SAAS,MAAM,KAAK,SAAS,UAAU,EAAE;AAAA,IACnE;AAGA,UAAM,OAAO,MAAM,SAAS,KAAK;AACjC,WAAO;AAAA,EACT,SAAS,OAAO;AACd,UAAM,IAAI;AAAA,MACR,wBAAwB,GAAG,KAAK,iBAAiB,QAAQ,MAAM,UAAU,eAAe;AAAA,MACxF;AAAA,MACA,iBAAiB,QAAQ,QAAQ;AAAA,IACnC;AAAA,EACF;AACF;","names":[]}

package/dist/utils/withEvents.cjs

@@ -0,0 +1,44 @@
+"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 withEvents_exports = {};
+__export(withEvents_exports, {
+  txForRelayed: () => txForRelayed,
+  txWithEvents: () => txWithEvents,
+  withEvents: () => withEvents
+});
+module.exports = __toCommonJS(withEvents_exports);
+var import_transactionHelpers = require("./transactionHelpers");
+async function withEvents(waitFor, tx2, select) {
+  const result = await waitFor(tx2);
+  return select(result);
+}
+async function txWithEvents(waitFor, input, select) {
+  const txResult = (0, import_transactionHelpers.tx)(input);
+  return withEvents(waitFor, txResult, select);
+}
+function txForRelayed(input) {
+  return (0, import_transactionHelpers.tx)(input);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  txForRelayed,
+  txWithEvents,
+  withEvents
+});
+//# sourceMappingURL=withEvents.cjs.map

package/dist/utils/withEvents.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/withEvents.ts"],"sourcesContent":["/**\n * Internal helper for controllers to wait for transaction events and extract data.\n * This keeps the POJO system internal while providing simple return values to developers.\n * \n * @internal\n */\n\nimport type { Contract, Fn, TypedTransactionResult } from \"../generated/event-types\";\nimport type { TransactionResult } from \"../types/operations\";\nimport { tx } from \"./transactionHelpers\";\n\n/**\n * Waits for transaction events and transforms them into domain-specific results.\n * \n * @internal\n * @param waitFor - The waitForTransactionEvents function from context\n * @param tx - The transaction result POJO\n * @param select - Function to extract domain data from typed events\n * @returns The domain-specific result\n */\nexport async function withEvents<\n  C extends Contract,\n  F extends Fn<C>,\n  Out\n>(\n  waitFor: (tx: TransactionResult<C, F>) => Promise<TypedTransactionResult<C, F>>,\n  tx: TransactionResult<C, F>,\n  select: (result: TypedTransactionResult<C, F>) => Out\n): Promise<Out> {\n  const result = await waitFor(tx);\n  return select(result);\n}\n\n/**\n * Creates a transaction result POJO and immediately waits for events.\n * Convenience wrapper that combines tx() + withEvents() for cleaner controller code.\n * \n * @internal\n * @param waitFor - The waitForTransactionEvents function from context\n * @param input - Transaction details (hash, from, contract, fn)\n * @param input.hash - Transaction hash\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name\n * @param input.fn - Function name\n * @param select - Function to extract domain data from typed events\n * @returns The domain-specific result\n */\nexport async function txWithEvents<\n  C extends Contract,\n  F extends Fn<C>,\n  Out\n>(\n  waitFor: (tx: TransactionResult<C, F>) => Promise<TypedTransactionResult<C, F>>,\n  input: {\n    hash: `0x${string}`;\n    from: `0x${string}`;\n    contract: C;\n    fn: F;\n  },\n  select: (result: TypedTransactionResult<C, F>) => Out\n): Promise<Out> {\n  const txResult = tx(input);\n  return withEvents(waitFor, txResult, select);\n}\n\n/**\n * Helper for methods that submit transactions via relayer.\n * Returns the TransactionResult POJO for two-step processing.\n * \n * @internal\n * @param input - Transaction details\n * @param input.hash - Transaction hash\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name\n * @param input.fn - Function name\n * @returns TransactionResult POJO for external waiting\n */\nexport function txForRelayed<C extends Contract, F extends Fn<C>>(\n  input: {\n    hash: `0x${string}`;\n    from: `0x${string}`;\n    contract: C;\n    fn: F;\n  }\n): TransactionResult<C, F> {\n  return tx(input);\n}"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AASA,gCAAmB;AAWnB,eAAsB,WAKpB,SACAA,KACA,QACc;AACd,QAAM,SAAS,MAAM,QAAQA,GAAE;AAC/B,SAAO,OAAO,MAAM;AACtB;AAgBA,eAAsB,aAKpB,SACA,OAMA,QACc;AACd,QAAM,eAAW,8BAAG,KAAK;AACzB,SAAO,WAAW,SAAS,UAAU,MAAM;AAC7C;AAcO,SAAS,aACd,OAMyB;AACzB,aAAO,8BAAG,KAAK;AACjB;","names":["tx"]}

package/dist/utils/withEvents.d.cts

@@ -0,0 +1,63 @@
+import { Contract, Fn, TypedTransactionResult } from '../generated/event-types.cjs';
+import { TransactionResult } from '../types/operations.cjs';
+import 'viem';
+import '../generated/server/server-exports.cjs';
+import '../generated/server/server.cjs';
+
+/**
+ * Internal helper for controllers to wait for transaction events and extract data.
+ * This keeps the POJO system internal while providing simple return values to developers.
+ *
+ * @internal
+ */
+
+/**
+ * Waits for transaction events and transforms them into domain-specific results.
+ *
+ * @internal
+ * @param waitFor - The waitForTransactionEvents function from context
+ * @param tx - The transaction result POJO
+ * @param select - Function to extract domain data from typed events
+ * @returns The domain-specific result
+ */
+declare function withEvents<C extends Contract, F extends Fn<C>, Out>(waitFor: (tx: TransactionResult<C, F>) => Promise<TypedTransactionResult<C, F>>, tx: TransactionResult<C, F>, select: (result: TypedTransactionResult<C, F>) => Out): Promise<Out>;
+/**
+ * Creates a transaction result POJO and immediately waits for events.
+ * Convenience wrapper that combines tx() + withEvents() for cleaner controller code.
+ *
+ * @internal
+ * @param waitFor - The waitForTransactionEvents function from context
+ * @param input - Transaction details (hash, from, contract, fn)
+ * @param input.hash - Transaction hash
+ * @param input.from - Transaction sender address
+ * @param input.contract - Contract name
+ * @param input.fn - Function name
+ * @param select - Function to extract domain data from typed events
+ * @returns The domain-specific result
+ */
+declare function txWithEvents<C extends Contract, F extends Fn<C>, Out>(waitFor: (tx: TransactionResult<C, F>) => Promise<TypedTransactionResult<C, F>>, input: {
+    hash: `0x${string}`;
+    from: `0x${string}`;
+    contract: C;
+    fn: F;
+}, select: (result: TypedTransactionResult<C, F>) => Out): Promise<Out>;
+/**
+ * Helper for methods that submit transactions via relayer.
+ * Returns the TransactionResult POJO for two-step processing.
+ *
+ * @internal
+ * @param input - Transaction details
+ * @param input.hash - Transaction hash
+ * @param input.from - Transaction sender address
+ * @param input.contract - Contract name
+ * @param input.fn - Function name
+ * @returns TransactionResult POJO for external waiting
+ */
+declare function txForRelayed<C extends Contract, F extends Fn<C>>(input: {
+    hash: `0x${string}`;
+    from: `0x${string}`;
+    contract: C;
+    fn: F;
+}): TransactionResult<C, F>;
+
+export { txForRelayed, txWithEvents, withEvents };

package/dist/utils/withEvents.d.ts

@@ -0,0 +1,63 @@
+import { Contract, Fn, TypedTransactionResult } from '../generated/event-types.js';
+import { TransactionResult } from '../types/operations.js';
+import 'viem';
+import '../generated/server/server-exports.js';
+import '../generated/server/server.js';
+
+/**
+ * Internal helper for controllers to wait for transaction events and extract data.
+ * This keeps the POJO system internal while providing simple return values to developers.
+ *
+ * @internal
+ */
+
+/**
+ * Waits for transaction events and transforms them into domain-specific results.
+ *
+ * @internal
+ * @param waitFor - The waitForTransactionEvents function from context
+ * @param tx - The transaction result POJO
+ * @param select - Function to extract domain data from typed events
+ * @returns The domain-specific result
+ */
+declare function withEvents<C extends Contract, F extends Fn<C>, Out>(waitFor: (tx: TransactionResult<C, F>) => Promise<TypedTransactionResult<C, F>>, tx: TransactionResult<C, F>, select: (result: TypedTransactionResult<C, F>) => Out): Promise<Out>;
+/**
+ * Creates a transaction result POJO and immediately waits for events.
+ * Convenience wrapper that combines tx() + withEvents() for cleaner controller code.
+ *
+ * @internal
+ * @param waitFor - The waitForTransactionEvents function from context
+ * @param input - Transaction details (hash, from, contract, fn)
+ * @param input.hash - Transaction hash
+ * @param input.from - Transaction sender address
+ * @param input.contract - Contract name
+ * @param input.fn - Function name
+ * @param select - Function to extract domain data from typed events
+ * @returns The domain-specific result
+ */
+declare function txWithEvents<C extends Contract, F extends Fn<C>, Out>(waitFor: (tx: TransactionResult<C, F>) => Promise<TypedTransactionResult<C, F>>, input: {
+    hash: `0x${string}`;
+    from: `0x${string}`;
+    contract: C;
+    fn: F;
+}, select: (result: TypedTransactionResult<C, F>) => Out): Promise<Out>;
+/**
+ * Helper for methods that submit transactions via relayer.
+ * Returns the TransactionResult POJO for two-step processing.
+ *
+ * @internal
+ * @param input - Transaction details
+ * @param input.hash - Transaction hash
+ * @param input.from - Transaction sender address
+ * @param input.contract - Contract name
+ * @param input.fn - Function name
+ * @returns TransactionResult POJO for external waiting
+ */
+declare function txForRelayed<C extends Contract, F extends Fn<C>>(input: {
+    hash: `0x${string}`;
+    from: `0x${string}`;
+    contract: C;
+    fn: F;
+}): TransactionResult<C, F>;
+
+export { txForRelayed, txWithEvents, withEvents };

package/dist/utils/withEvents.js

@@ -0,0 +1,18 @@
+import { tx } from "./transactionHelpers";
+async function withEvents(waitFor, tx2, select) {
+  const result = await waitFor(tx2);
+  return select(result);
+}
+async function txWithEvents(waitFor, input, select) {
+  const txResult = tx(input);
+  return withEvents(waitFor, txResult, select);
+}
+function txForRelayed(input) {
+  return tx(input);
+}
+export {
+  txForRelayed,
+  txWithEvents,
+  withEvents
+};
+//# sourceMappingURL=withEvents.js.map

package/dist/utils/withEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/withEvents.ts"],"sourcesContent":["/**\n * Internal helper for controllers to wait for transaction events and extract data.\n * This keeps the POJO system internal while providing simple return values to developers.\n * \n * @internal\n */\n\nimport type { Contract, Fn, TypedTransactionResult } from \"../generated/event-types\";\nimport type { TransactionResult } from \"../types/operations\";\nimport { tx } from \"./transactionHelpers\";\n\n/**\n * Waits for transaction events and transforms them into domain-specific results.\n * \n * @internal\n * @param waitFor - The waitForTransactionEvents function from context\n * @param tx - The transaction result POJO\n * @param select - Function to extract domain data from typed events\n * @returns The domain-specific result\n */\nexport async function withEvents<\n  C extends Contract,\n  F extends Fn<C>,\n  Out\n>(\n  waitFor: (tx: TransactionResult<C, F>) => Promise<TypedTransactionResult<C, F>>,\n  tx: TransactionResult<C, F>,\n  select: (result: TypedTransactionResult<C, F>) => Out\n): Promise<Out> {\n  const result = await waitFor(tx);\n  return select(result);\n}\n\n/**\n * Creates a transaction result POJO and immediately waits for events.\n * Convenience wrapper that combines tx() + withEvents() for cleaner controller code.\n * \n * @internal\n * @param waitFor - The waitForTransactionEvents function from context\n * @param input - Transaction details (hash, from, contract, fn)\n * @param input.hash - Transaction hash\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name\n * @param input.fn - Function name\n * @param select - Function to extract domain data from typed events\n * @returns The domain-specific result\n */\nexport async function txWithEvents<\n  C extends Contract,\n  F extends Fn<C>,\n  Out\n>(\n  waitFor: (tx: TransactionResult<C, F>) => Promise<TypedTransactionResult<C, F>>,\n  input: {\n    hash: `0x${string}`;\n    from: `0x${string}`;\n    contract: C;\n    fn: F;\n  },\n  select: (result: TypedTransactionResult<C, F>) => Out\n): Promise<Out> {\n  const txResult = tx(input);\n  return withEvents(waitFor, txResult, select);\n}\n\n/**\n * Helper for methods that submit transactions via relayer.\n * Returns the TransactionResult POJO for two-step processing.\n * \n * @internal\n * @param input - Transaction details\n * @param input.hash - Transaction hash\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name\n * @param input.fn - Function name\n * @returns TransactionResult POJO for external waiting\n */\nexport function txForRelayed<C extends Contract, F extends Fn<C>>(\n  input: {\n    hash: `0x${string}`;\n    from: `0x${string}`;\n    contract: C;\n    fn: F;\n  }\n): TransactionResult<C, F> {\n  return tx(input);\n}"],"mappings":"AASA,SAAS,UAAU;AAWnB,eAAsB,WAKpB,SACAA,KACA,QACc;AACd,QAAM,SAAS,MAAM,QAAQA,GAAE;AAC/B,SAAO,OAAO,MAAM;AACtB;AAgBA,eAAsB,aAKpB,SACA,OAMA,QACc;AACd,QAAM,WAAW,GAAG,KAAK;AACzB,SAAO,WAAW,SAAS,UAAU,MAAM;AAC7C;AAcO,SAAS,aACd,OAMyB;AACzB,SAAO,GAAG,KAAK;AACjB;","names":["tx"]}