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

package/dist/utils/subgraphPagination.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @file Utilities for handling paginated subgraph queries
+ * @module vana-sdk/utils/subgraphPagination
+ */
+import { type DocumentNode } from "graphql";
+import type { PaginationOptions } from "../types/options";
+/**
+ * Generic subgraph response structure
+ */
+export interface SubgraphResponse<T> {
+    data?: T;
+    errors?: Array<{
+        message: string;
+    }>;
+}
+/**
+ * Configuration for paginated subgraph queries
+ */
+export interface PaginatedQueryConfig<TData, TItem, TRawItem = any> {
+    /** The GraphQL endpoint URL */
+    endpoint: string;
+    /** The GraphQL document to execute */
+    document: DocumentNode;
+    /** Base variables for the query (e.g., userId) */
+    baseVariables: Record<string, any>;
+    /** Pagination options from the user */
+    options?: PaginationOptions;
+    /** Function to extract items from the response */
+    extractItems: (data: TData) => TRawItem[] | undefined;
+    /** Function to transform items if needed */
+    transformItem?: (item: TRawItem) => TItem;
+    /** Maximum items per GraphQL query (default: 1000) */
+    maxPerQuery?: number;
+}
+/**
+ * Generic paginated query executor for subgraph queries
+ *
+ * @remarks
+ * Handles pagination, fetchAll, and proper GraphQL query construction.
+ * Abstracts the common pattern of paginated subgraph queries.
+ *
+ * @param config - Configuration for the paginated query
+ * @returns Array of items from all pages
+ *
+ * @example
+ * ```typescript
+ * const files = await executePaginatedQuery({
+ *   endpoint: subgraphUrl,
+ *   document: GetUserFilesPaginatedDocument,
+ *   baseVariables: { userId: owner.toLowerCase() },
+ *   options: { limit: 50, orderBy: 'addedAtBlock' },
+ *   extractItems: (data) => data?.user?.files,
+ *   transformItem: (file) => ({
+ *     id: parseInt(file.id),
+ *     url: file.url,
+ *     // ... transform to UserFile
+ *   })
+ * });
+ * ```
+ */
+export declare function executePaginatedQuery<TData, TItem, TRawItem = any>(config: PaginatedQueryConfig<TData, TItem, TRawItem>): Promise<TItem[]>;
+/**
+ * Helper to map string orderBy values to GraphQL enums
+ *
+ * @param orderBy - String orderBy value from options
+ * @param enumMap - Map of string values to GraphQL enum values
+ * @returns The mapped enum value or undefined
+ */
+export declare function mapOrderByToEnum<T>(orderBy: string | undefined, enumMap: Record<string, T>, defaultValue?: T): T | undefined;
+/**
+ * Helper to map string orderDirection to GraphQL enum
+ *
+ * @param direction - Direction string ('asc' or 'desc')
+ * @param ascValue - The GraphQL enum value for ascending
+ * @param descValue - The GraphQL enum value for descending
+ * @returns The mapped enum value
+ */
+export declare function mapOrderDirection<T>(direction: "asc" | "desc" | undefined, ascValue: T, descValue: T, defaultValue?: T): T;

package/dist/utils/subgraphPagination.js

@@ -0,0 +1,78 @@
+import { print } from "graphql";
+async function executePaginatedQuery(config) {
+  const {
+    endpoint,
+    document,
+    baseVariables,
+    options,
+    extractItems,
+    transformItem,
+    maxPerQuery = 1e3
+  } = config;
+  const limit = options?.fetchAll ? Number.MAX_SAFE_INTEGER : options?.limit ?? 100;
+  const offset = options?.offset ?? 0;
+  const orderBy = options?.orderBy;
+  const orderDirection = options?.orderDirection;
+  const allItems = [];
+  let currentOffset = offset;
+  const pageSize = Math.min(limit, maxPerQuery);
+  while (true) {
+    const currentLimit = options?.fetchAll ? pageSize : Math.min(pageSize, limit - allItems.length);
+    const variables = {
+      ...baseVariables,
+      first: currentLimit,
+      skip: currentOffset,
+      ...orderBy && { orderBy },
+      ...orderDirection && { orderDirection }
+    };
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        query: print(document),
+        variables
+      })
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Subgraph request failed: ${response.status} ${response.statusText}`
+      );
+    }
+    const result = await response.json();
+    if (result.errors) {
+      throw new Error(
+        `Subgraph errors: ${result.errors.map((e) => e.message).join(", ")}`
+      );
+    }
+    const items = extractItems(result.data);
+    if (!items || items.length === 0) {
+      break;
+    }
+    const transformedItems = transformItem ? items.map(transformItem) : items;
+    allItems.push(...transformedItems);
+    if (!options?.fetchAll && allItems.length >= limit) {
+      return allItems.slice(0, limit);
+    }
+    if (items.length < currentLimit) {
+      break;
+    }
+    currentOffset += items.length;
+  }
+  return allItems;
+}
+function mapOrderByToEnum(orderBy, enumMap, defaultValue) {
+  if (!orderBy) return defaultValue;
+  return enumMap[orderBy] ?? defaultValue;
+}
+function mapOrderDirection(direction, ascValue, descValue, defaultValue) {
+  if (!direction) return defaultValue ?? descValue;
+  return direction === "asc" ? ascValue : descValue;
+}
+export {
+  executePaginatedQuery,
+  mapOrderByToEnum,
+  mapOrderDirection
+};
+//# sourceMappingURL=subgraphPagination.js.map

package/dist/utils/subgraphPagination.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/subgraphPagination.ts"],"sourcesContent":["/**\n * @file Utilities for handling paginated subgraph queries\n * @module vana-sdk/utils/subgraphPagination\n */\n\nimport { print, type DocumentNode } from \"graphql\";\nimport type { PaginationOptions } from \"../types/options\";\n\n/**\n * Generic subgraph response structure\n */\nexport interface SubgraphResponse<T> {\n  data?: T;\n  errors?: Array<{ message: string }>;\n}\n\n/**\n * Configuration for paginated subgraph queries\n */\nexport interface PaginatedQueryConfig<TData, TItem, TRawItem = any> {\n  /** The GraphQL endpoint URL */\n  endpoint: string;\n\n  /** The GraphQL document to execute */\n  document: DocumentNode;\n\n  /** Base variables for the query (e.g., userId) */\n  baseVariables: Record<string, any>;\n\n  /** Pagination options from the user */\n  options?: PaginationOptions;\n\n  /** Function to extract items from the response */\n  extractItems: (data: TData) => TRawItem[] | undefined;\n\n  /** Function to transform items if needed */\n  transformItem?: (item: TRawItem) => TItem;\n\n  /** Maximum items per GraphQL query (default: 1000) */\n  maxPerQuery?: number;\n}\n\n/**\n * Generic paginated query executor for subgraph queries\n *\n * @remarks\n * Handles pagination, fetchAll, and proper GraphQL query construction.\n * Abstracts the common pattern of paginated subgraph queries.\n *\n * @param config - Configuration for the paginated query\n * @returns Array of items from all pages\n *\n * @example\n * ```typescript\n * const files = await executePaginatedQuery({\n *   endpoint: subgraphUrl,\n *   document: GetUserFilesPaginatedDocument,\n *   baseVariables: { userId: owner.toLowerCase() },\n *   options: { limit: 50, orderBy: 'addedAtBlock' },\n *   extractItems: (data) => data?.user?.files,\n *   transformItem: (file) => ({\n *     id: parseInt(file.id),\n *     url: file.url,\n *     // ... transform to UserFile\n *   })\n * });\n * ```\n */\nexport async function executePaginatedQuery<TData, TItem, TRawItem = any>(\n  config: PaginatedQueryConfig<TData, TItem, TRawItem>,\n): Promise<TItem[]> {\n  const {\n    endpoint,\n    document,\n    baseVariables,\n    options,\n    extractItems,\n    transformItem,\n    maxPerQuery = 1000,\n  } = config;\n\n  // Set pagination defaults\n  const limit = options?.fetchAll\n    ? Number.MAX_SAFE_INTEGER\n    : (options?.limit ?? 100);\n  const offset = options?.offset ?? 0;\n  const orderBy = options?.orderBy;\n  const orderDirection = options?.orderDirection;\n\n  const allItems: TItem[] = [];\n  let currentOffset = offset;\n  const pageSize = Math.min(limit, maxPerQuery);\n\n  // Handle fetchAll by making multiple queries if needed\n  while (true) {\n    const currentLimit = options?.fetchAll\n      ? pageSize\n      : Math.min(pageSize, limit - allItems.length);\n\n    // Build query variables\n    const variables = {\n      ...baseVariables,\n      first: currentLimit,\n      skip: currentOffset,\n      ...(orderBy && { orderBy }),\n      ...(orderDirection && { orderDirection }),\n    };\n\n    // Execute query\n    const response = await fetch(endpoint, {\n      method: \"POST\",\n      headers: {\n        \"Content-Type\": \"application/json\",\n      },\n      body: JSON.stringify({\n        query: print(document),\n        variables,\n      }),\n    });\n\n    if (!response.ok) {\n      throw new Error(\n        `Subgraph request failed: ${response.status} ${response.statusText}`,\n      );\n    }\n\n    const result = (await response.json()) as SubgraphResponse<TData>;\n\n    if (result.errors) {\n      throw new Error(\n        `Subgraph errors: ${result.errors.map((e) => e.message).join(\", \")}`,\n      );\n    }\n\n    // Extract items from response\n    const items = extractItems(result.data as TData);\n\n    if (!items || items.length === 0) {\n      // No more items\n      break;\n    }\n\n    // Transform items if transformer provided\n    const transformedItems: TItem[] = transformItem\n      ? items.map(transformItem)\n      : (items as unknown as TItem[]);\n\n    allItems.push(...transformedItems);\n\n    // Check if we have enough items or should continue\n    if (!options?.fetchAll && allItems.length >= limit) {\n      // We have enough items\n      return allItems.slice(0, limit); // Trim to exact limit\n    }\n\n    if (items.length < currentLimit) {\n      // No more items available\n      break;\n    }\n\n    // Continue to next page\n    currentOffset += items.length;\n  }\n\n  return allItems;\n}\n\n/**\n * Helper to map string orderBy values to GraphQL enums\n *\n * @param orderBy - String orderBy value from options\n * @param enumMap - Map of string values to GraphQL enum values\n * @returns The mapped enum value or undefined\n */\nexport function mapOrderByToEnum<T>(\n  orderBy: string | undefined,\n  enumMap: Record<string, T>,\n  defaultValue?: T,\n): T | undefined {\n  if (!orderBy) return defaultValue;\n  return enumMap[orderBy] ?? defaultValue;\n}\n\n/**\n * Helper to map string orderDirection to GraphQL enum\n *\n * @param direction - Direction string ('asc' or 'desc')\n * @param ascValue - The GraphQL enum value for ascending\n * @param descValue - The GraphQL enum value for descending\n * @returns The mapped enum value\n */\nexport function mapOrderDirection<T>(\n  direction: \"asc\" | \"desc\" | undefined,\n  ascValue: T,\n  descValue: T,\n  defaultValue?: T,\n): T {\n  if (!direction) return defaultValue ?? descValue;\n  return direction === \"asc\" ? ascValue : descValue;\n}\n"],"mappings":"AAKA,SAAS,aAAgC;AA+DzC,eAAsB,sBACpB,QACkB;AAClB,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,cAAc;AAAA,EAChB,IAAI;AAGJ,QAAM,QAAQ,SAAS,WACnB,OAAO,mBACN,SAAS,SAAS;AACvB,QAAM,SAAS,SAAS,UAAU;AAClC,QAAM,UAAU,SAAS;AACzB,QAAM,iBAAiB,SAAS;AAEhC,QAAM,WAAoB,CAAC;AAC3B,MAAI,gBAAgB;AACpB,QAAM,WAAW,KAAK,IAAI,OAAO,WAAW;AAG5C,SAAO,MAAM;AACX,UAAM,eAAe,SAAS,WAC1B,WACA,KAAK,IAAI,UAAU,QAAQ,SAAS,MAAM;AAG9C,UAAM,YAAY;AAAA,MAChB,GAAG;AAAA,MACH,OAAO;AAAA,MACP,MAAM;AAAA,MACN,GAAI,WAAW,EAAE,QAAQ;AAAA,MACzB,GAAI,kBAAkB,EAAE,eAAe;AAAA,IACzC;AAGA,UAAM,WAAW,MAAM,MAAM,UAAU;AAAA,MACrC,QAAQ;AAAA,MACR,SAAS;AAAA,QACP,gBAAgB;AAAA,MAClB;AAAA,MACA,MAAM,KAAK,UAAU;AAAA,QACnB,OAAO,MAAM,QAAQ;AAAA,QACrB;AAAA,MACF,CAAC;AAAA,IACH,CAAC;AAED,QAAI,CAAC,SAAS,IAAI;AAChB,YAAM,IAAI;AAAA,QACR,4BAA4B,SAAS,MAAM,IAAI,SAAS,UAAU;AAAA,MACpE;AAAA,IACF;AAEA,UAAM,SAAU,MAAM,SAAS,KAAK;AAEpC,QAAI,OAAO,QAAQ;AACjB,YAAM,IAAI;AAAA,QACR,oBAAoB,OAAO,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;AAAA,MACpE;AAAA,IACF;AAGA,UAAM,QAAQ,aAAa,OAAO,IAAa;AAE/C,QAAI,CAAC,SAAS,MAAM,WAAW,GAAG;AAEhC;AAAA,IACF;AAGA,UAAM,mBAA4B,gBAC9B,MAAM,IAAI,aAAa,IACtB;AAEL,aAAS,KAAK,GAAG,gBAAgB;AAGjC,QAAI,CAAC,SAAS,YAAY,SAAS,UAAU,OAAO;AAElD,aAAO,SAAS,MAAM,GAAG,KAAK;AAAA,IAChC;AAEA,QAAI,MAAM,SAAS,cAAc;AAE/B;AAAA,IACF;AAGA,qBAAiB,MAAM;AAAA,EACzB;AAEA,SAAO;AACT;AASO,SAAS,iBACd,SACA,SACA,cACe;AACf,MAAI,CAAC,QAAS,QAAO;AACrB,SAAO,QAAQ,OAAO,KAAK;AAC7B;AAUO,SAAS,kBACd,WACA,UACA,WACA,cACG;AACH,MAAI,CAAC,UAAW,QAAO,gBAAgB;AACvC,SAAO,cAAc,QAAQ,WAAW;AAC1C;","names":[]}

package/dist/utils/transactionHelpers.cjs.map

@@ -1 +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}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;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":[]}
+{"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 typed TransactionResult with validation.\n *\n * @remarks\n * Ensures type safety for transaction results.\n * Reduces boilerplate in transaction handling.\n *\n * @param input - Transaction details\n * @param input.hash - Transaction hash from the blockchain\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name being called\n * @param input.fn - Function name being executed\n * @param input.chainId - Optional chain ID for network identification\n * @param input.value - Optional transaction value in wei\n * @param input.nonce - Optional transaction nonce for ordering\n * @param input.to - Optional recipient address for the transaction\n * @returns Typed TransactionResult POJO\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}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;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/transactionHelpers.d.ts

@@ -5,22 +5,22 @@ import type { Hash, Address } from "viem";
 import type { TransactionResult } from "../types/operations";
 import type { Contract, Fn } from "../generated/event-types";
 /**
- * Creates a strongly-typed TransactionResult POJO.
+ * Creates typed TransactionResult with validation.
  *
  * @remarks
- * This helper ensures all required fields are present and typed correctly,
- * reducing boilerplate and preventing mistakes.
+ * Ensures type safety for transaction results.
+ * Reduces boilerplate in transaction handling.
  *
  * @param input - Transaction details
- * @param input.hash - Transaction hash
+ * @param input.hash - Transaction hash from the blockchain
  * @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
+ * @param input.contract - Contract name being called
+ * @param input.fn - Function name being executed
+ * @param input.chainId - Optional chain ID for network identification
+ * @param input.value - Optional transaction value in wei
+ * @param input.nonce - Optional transaction nonce for ordering
+ * @param input.to - Optional recipient address for the transaction
+ * @returns Typed TransactionResult POJO
  *
  * @example
  * ```typescript
@@ -28,7 +28,7 @@ import type { Contract, Fn } from "../generated/event-types";
  *   hash,
  *   from: account.address,
  *   contract: "DataPortabilityPermissions",
- *   fn: "revokePermission",
+ *   fn: "revokePermission"
  * });
  * ```
  */

package/dist/utils/transactionHelpers.js.map

@@ -1 +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}\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":[]}
+{"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 typed TransactionResult with validation.\n *\n * @remarks\n * Ensures type safety for transaction results.\n * Reduces boilerplate in transaction handling.\n *\n * @param input - Transaction details\n * @param input.hash - Transaction hash from the blockchain\n * @param input.from - Transaction sender address\n * @param input.contract - Contract name being called\n * @param input.fn - Function name being executed\n * @param input.chainId - Optional chain ID for network identification\n * @param input.value - Optional transaction value in wei\n * @param input.nonce - Optional transaction nonce for ordering\n * @param input.to - Optional recipient address for the transaction\n * @returns Typed TransactionResult POJO\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}\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.map

@@ -1 +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":[]}
+{"version":3,"sources":["../../src/utils/typedDataConverter.ts"],"sourcesContent":["/**\n * Provides type-safe conversion between Vana and viem typed data formats.\n *\n * @remarks\n * This module bridges the gap between Vana's generic typed data structure\n * and viem's strict TypedDataDefinition format, ensuring compatibility\n * for EIP-712 signature operations.\n *\n * @category Utilities\n * @module typedDataConverter\n */\n\nimport type { TypedDataDefinition } from \"viem\";\nimport type { GenericTypedData } from \"../types/permissions\";\n\n/**\n * Converts a GenericTypedData object to a viem-compatible TypedDataDefinition.\n *\n * @remarks\n * Transforms Vana's flexible typed data format into viem's strict format\n * with readonly arrays. This ensures type safety when passing typed data\n * to viem's `signTypedData` method for EIP-712 signatures.\n *\n * @param typedData - The typed data object to convert.\n *   Obtain from permission operations or server responses.\n * @returns A properly typed TypedDataDefinition for use with viem\n *\n * @example\n * ```typescript\n * const vanTypedData: GenericTypedData = {\n *   domain: { name: 'Vana', version: '1', chainId: 14800 },\n *   types: {\n *     Permission: [\n *       { name: 'grantee', type: 'address' },\n *       { name: 'operation', type: 'string' }\n *     ]\n *   },\n *   primaryType: 'Permission',\n *   message: { grantee: '0x...', operation: 'read' }\n * };\n *\n * const viemTypedData = toViemTypedDataDefinition(vanaTypedData);\n * const signature = await walletClient.signTypedData(viemTypedData);\n * ```\n *\n * @category Utilities\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;AA+CO,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.ts

@@ -1,10 +1,46 @@
+/**
+ * Provides type-safe conversion between Vana and viem typed data formats.
+ *
+ * @remarks
+ * This module bridges the gap between Vana's generic typed data structure
+ * and viem's strict TypedDataDefinition format, ensuring compatibility
+ * for EIP-712 signature operations.
+ *
+ * @category Utilities
+ * @module typedDataConverter
+ */
 import type { TypedDataDefinition } from "viem";
 import type { GenericTypedData } from "../types/permissions";
 /**
- * Converts a GenericTypedData object to a Viem-compatible TypedDataDefinition.
- * This function ensures type safety when passing typed data to viem's signTypedData method.
+ * Converts a GenericTypedData object to a viem-compatible TypedDataDefinition.
  *
- * @param typedData - The typed data object to convert
+ * @remarks
+ * Transforms Vana's flexible typed data format into viem's strict format
+ * with readonly arrays. This ensures type safety when passing typed data
+ * to viem's `signTypedData` method for EIP-712 signatures.
+ *
+ * @param typedData - The typed data object to convert.
+ *   Obtain from permission operations or server responses.
  * @returns A properly typed TypedDataDefinition for use with viem
+ *
+ * @example
+ * ```typescript
+ * const vanTypedData: GenericTypedData = {
+ *   domain: { name: 'Vana', version: '1', chainId: 14800 },
+ *   types: {
+ *     Permission: [
+ *       { name: 'grantee', type: 'address' },
+ *       { name: 'operation', type: 'string' }
+ *     ]
+ *   },
+ *   primaryType: 'Permission',
+ *   message: { grantee: '0x...', operation: 'read' }
+ * };
+ *
+ * const viemTypedData = toViemTypedDataDefinition(vanaTypedData);
+ * const signature = await walletClient.signTypedData(viemTypedData);
+ * ```
+ *
+ * @category Utilities
  */
 export declare function toViemTypedDataDefinition(typedData: GenericTypedData): TypedDataDefinition;

package/dist/utils/typedDataConverter.js.map

@@ -1 +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":[]}
+{"version":3,"sources":["../../src/utils/typedDataConverter.ts"],"sourcesContent":["/**\n * Provides type-safe conversion between Vana and viem typed data formats.\n *\n * @remarks\n * This module bridges the gap between Vana's generic typed data structure\n * and viem's strict TypedDataDefinition format, ensuring compatibility\n * for EIP-712 signature operations.\n *\n * @category Utilities\n * @module typedDataConverter\n */\n\nimport type { TypedDataDefinition } from \"viem\";\nimport type { GenericTypedData } from \"../types/permissions\";\n\n/**\n * Converts a GenericTypedData object to a viem-compatible TypedDataDefinition.\n *\n * @remarks\n * Transforms Vana's flexible typed data format into viem's strict format\n * with readonly arrays. This ensures type safety when passing typed data\n * to viem's `signTypedData` method for EIP-712 signatures.\n *\n * @param typedData - The typed data object to convert.\n *   Obtain from permission operations or server responses.\n * @returns A properly typed TypedDataDefinition for use with viem\n *\n * @example\n * ```typescript\n * const vanTypedData: GenericTypedData = {\n *   domain: { name: 'Vana', version: '1', chainId: 14800 },\n *   types: {\n *     Permission: [\n *       { name: 'grantee', type: 'address' },\n *       { name: 'operation', type: 'string' }\n *     ]\n *   },\n *   primaryType: 'Permission',\n *   message: { grantee: '0x...', operation: 'read' }\n * };\n *\n * const viemTypedData = toViemTypedDataDefinition(vanaTypedData);\n * const signature = await walletClient.signTypedData(viemTypedData);\n * ```\n *\n * @category Utilities\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":"AA+CO,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

@@ -24,6 +24,13 @@ __export(urlResolver_exports, {
 module.exports = __toCommonJS(urlResolver_exports);
 var import_download = require("./download");
 class UrlResolutionError extends Error {
+  /**
+   * Creates a new URL resolution error.
+   *
+   * @param message - Description of what went wrong
+   * @param url - The URL that failed to resolve
+   * @param cause - The underlying error that caused the failure
+   */
   constructor(message, url, cause) {
     super(message);
     this.url = url;

package/dist/utils/urlResolver.cjs.map

@@ -1 +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 { universalFetch } 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 universalFetch(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,sBAA+B;AAKxB,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,gCAAe,KAAK,eAAe;AAE1D,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":[]}
+{"version":3,"sources":["../../src/utils/urlResolver.ts"],"sourcesContent":["/**\n * Provides universal URL resolution across multiple protocols.\n *\n * @remarks\n * This module enables fetching data from various protocols including IPFS,\n * HTTP/HTTPS, and Arweave through a unified interface. It handles protocol\n * conversion, gateway selection, and fallback strategies automatically.\n *\n * @category Utilities\n * @module utils/urlResolver\n */\n\nimport { universalFetch } from \"./download\";\n\n/**\n * Indicates that URL resolution or data fetching failed.\n *\n * @remarks\n * This error provides context about which URL failed and why,\n * making it easier to debug issues with external resources.\n *\n * @category Errors\n */\nexport class UrlResolutionError extends Error {\n  /**\n   * Creates a new URL resolution error.\n   *\n   * @param message - Description of what went wrong\n   * @param url - The URL that failed to resolve\n   * @param cause - The underlying error that caused the failure\n   */\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 universalFetch(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;AAYA,sBAA+B;AAWxB,MAAM,2BAA2B,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQ5C,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,gCAAe,KAAK,eAAe;AAE1D,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.ts

@@ -1,15 +1,33 @@
 /**
- * Universal URL resolver for the Vana SDK
+ * Provides universal URL resolution across multiple protocols.
  *
- * Handles fetching data from various protocols (IPFS, HTTP, Arweave, etc.)
- * in a consistent, reliable way.
+ * @remarks
+ * This module enables fetching data from various protocols including IPFS,
+ * HTTP/HTTPS, and Arweave through a unified interface. It handles protocol
+ * conversion, gateway selection, and fallback strategies automatically.
+ *
+ * @category Utilities
+ * @module utils/urlResolver
  */
 /**
- * Error thrown when URL resolution fails
+ * Indicates that URL resolution or data fetching failed.
+ *
+ * @remarks
+ * This error provides context about which URL failed and why,
+ * making it easier to debug issues with external resources.
+ *
+ * @category Errors
  */
 export declare class UrlResolutionError extends Error {
     readonly url: string;
     readonly cause?: Error | undefined;
+    /**
+     * Creates a new URL resolution error.
+     *
+     * @param message - Description of what went wrong
+     * @param url - The URL that failed to resolve
+     * @param cause - The underlying error that caused the failure
+     */
     constructor(message: string, url: string, cause?: Error | undefined);
 }
 /**

package/dist/utils/urlResolver.js

@@ -1,5 +1,12 @@
 import { universalFetch } from "./download";
 class UrlResolutionError extends Error {
+  /**
+   * Creates a new URL resolution error.
+   *
+   * @param message - Description of what went wrong
+   * @param url - The URL that failed to resolve
+   * @param cause - The underlying error that caused the failure
+   */
   constructor(message, url, cause) {
     super(message);
     this.url = url;

package/dist/utils/urlResolver.js.map

@@ -1 +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 { universalFetch } 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 universalFetch(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,sBAAsB;AAKxB,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,eAAe,KAAK,eAAe;AAE1D,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":[]}
+{"version":3,"sources":["../../src/utils/urlResolver.ts"],"sourcesContent":["/**\n * Provides universal URL resolution across multiple protocols.\n *\n * @remarks\n * This module enables fetching data from various protocols including IPFS,\n * HTTP/HTTPS, and Arweave through a unified interface. It handles protocol\n * conversion, gateway selection, and fallback strategies automatically.\n *\n * @category Utilities\n * @module utils/urlResolver\n */\n\nimport { universalFetch } from \"./download\";\n\n/**\n * Indicates that URL resolution or data fetching failed.\n *\n * @remarks\n * This error provides context about which URL failed and why,\n * making it easier to debug issues with external resources.\n *\n * @category Errors\n */\nexport class UrlResolutionError extends Error {\n  /**\n   * Creates a new URL resolution error.\n   *\n   * @param message - Description of what went wrong\n   * @param url - The URL that failed to resolve\n   * @param cause - The underlying error that caused the failure\n   */\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 universalFetch(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":"AAYA,SAAS,sBAAsB;AAWxB,MAAM,2BAA2B,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQ5C,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,eAAe,KAAK,eAAe;AAE1D,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/wallet.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/wallet.ts"],"sourcesContent":["import type { Account, Address } from \"viem\";\n\n/**\n * Extracts an Ethereum address from various account formats.\n *\n * Viem's Account type can be:\n * - A string address directly\n * - An object with an address property\n * - A LocalAccount with address property\n *\n * This utility provides a single source of truth for address extraction,\n * eliminating duplicate logic throughout the codebase.\n *\n * @param account - The account to extract address from\n * @returns The extracted Ethereum address\n * @throws Error if account is undefined or address cannot be determined\n */\nexport function extractAddress(\n  account: Account | Address | undefined | null,\n): Address {\n  if (!account) {\n    throw new Error(\"No account provided\");\n  }\n\n  // Handle string address directly\n  if (typeof account === \"string\") {\n    return account as Address;\n  }\n\n  // Handle object with address property\n  if (typeof account === \"object\" && \"address\" in account && account.address) {\n    return account.address;\n  }\n\n  throw new Error(\"Unable to determine wallet address from account\");\n}\n\n/**\n * Safely extracts an address, returning undefined instead of throwing.\n * Useful for optional address resolution.\n *\n * @param account - The account to extract address from\n * @returns The extracted address or undefined\n */\nexport function extractAddressSafe(\n  account: Account | Address | undefined | null,\n): Address | undefined {\n  try {\n    return extractAddress(account);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Type guard to check if an account has a valid address.\n *\n * @param account - The account to check\n * @returns True if account has a valid address\n */\nexport function hasAddress(account: unknown): account is Account | Address {\n  if (!account) return false;\n\n  if (typeof account === \"string\") {\n    // Basic check for Ethereum address format\n    return /^0x[a-fA-F0-9]{40}$/.test(account);\n  }\n\n  if (typeof account === \"object\" && \"address\" in account) {\n    const accountWithAddress = account as { address: unknown };\n    const addr = accountWithAddress.address;\n    return typeof addr === \"string\" && /^0x[a-fA-F0-9]{40}$/.test(addr);\n  }\n\n  return false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiBO,SAAS,eACd,SACS;AACT,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,qBAAqB;AAAA,EACvC;AAGA,MAAI,OAAO,YAAY,UAAU;AAC/B,WAAO;AAAA,EACT;AAGA,MAAI,OAAO,YAAY,YAAY,aAAa,WAAW,QAAQ,SAAS;AAC1E,WAAO,QAAQ;AAAA,EACjB;AAEA,QAAM,IAAI,MAAM,iDAAiD;AACnE;AASO,SAAS,mBACd,SACqB;AACrB,MAAI;AACF,WAAO,eAAe,OAAO;AAAA,EAC/B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAQO,SAAS,WAAW,SAAgD;AACzE,MAAI,CAAC,QAAS,QAAO;AAErB,MAAI,OAAO,YAAY,UAAU;AAE/B,WAAO,sBAAsB,KAAK,OAAO;AAAA,EAC3C;AAEA,MAAI,OAAO,YAAY,YAAY,aAAa,SAAS;AACvD,UAAM,qBAAqB;AAC3B,UAAM,OAAO,mBAAmB;AAChC,WAAO,OAAO,SAAS,YAAY,sBAAsB,KAAK,IAAI;AAAA,EACpE;AAEA,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../src/utils/wallet.ts"],"sourcesContent":["import type { Account, Address } from \"viem\";\n\n/**\n * Extracts an Ethereum address from various account formats.\n *\n * @remarks\n * Handles viem's polymorphic Account type which can be a string address,\n * an object with an address property, or a LocalAccount. This utility\n * provides consistent address extraction across the SDK, eliminating\n * duplicate logic and potential inconsistencies.\n *\n * @param account - The account to extract address from.\n *   Can be a hex string address, Account object, or LocalAccount.\n * @returns The extracted Ethereum address as a `0x`-prefixed string\n *\n * @throws {Error} When account is undefined or null.\n *   Provide a valid account from wallet connection.\n * @throws {Error} When address cannot be determined from account structure.\n *   Ensure account has a valid address property.\n *\n * @example\n * ```typescript\n * // String address\n * const addr1 = extractAddress('0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb');\n *\n * // Account object\n * const addr2 = extractAddress({ address: '0x742d...' });\n *\n * // LocalAccount from viem\n * const account = privateKeyToAccount('0x...');\n * const addr3 = extractAddress(account);\n * ```\n *\n * @category Utilities\n */\nexport function extractAddress(\n  account: Account | Address | undefined | null,\n): Address {\n  if (!account) {\n    throw new Error(\"No account provided\");\n  }\n\n  // Handle string address directly\n  if (typeof account === \"string\") {\n    return account as Address;\n  }\n\n  // Handle object with address property\n  if (typeof account === \"object\" && \"address\" in account && account.address) {\n    return account.address;\n  }\n\n  throw new Error(\"Unable to determine wallet address from account\");\n}\n\n/**\n * Safely extracts an address without throwing errors.\n *\n * @remarks\n * Non-throwing version of `extractAddress` for optional address resolution.\n * Use when address extraction failure is acceptable and should be handled\n * gracefully without exception handling.\n *\n * @param account - The account to extract address from.\n *   Can be a hex string address, Account object, LocalAccount, or nullish.\n * @returns The extracted Ethereum address or `undefined` if extraction fails\n *\n * @example\n * ```typescript\n * const address = extractAddressSafe(potentialAccount);\n *\n * if (address) {\n *   console.log(`Using address: ${address}`);\n * } else {\n *   console.log('No valid address available');\n * }\n *\n * // Useful in optional chaining\n * const userAddress = extractAddressSafe(user?.wallet) ?? DEFAULT_ADDRESS;\n * ```\n *\n * @category Utilities\n */\nexport function extractAddressSafe(\n  account: Account | Address | undefined | null,\n): Address | undefined {\n  try {\n    return extractAddress(account);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Validates whether a value contains a valid Ethereum address.\n *\n * @remarks\n * Type guard that performs runtime validation of Ethereum address format.\n * Checks for proper `0x` prefix and 40 hexadecimal characters. Works with\n * string addresses, Account objects, and LocalAccount instances.\n *\n * @param account - The value to validate for address presence\n * @returns `true` if account contains a valid Ethereum address, `false` otherwise\n *\n * @example\n * ```typescript\n * const maybeAccount: unknown = getUserInput();\n *\n * if (hasAddress(maybeAccount)) {\n *   // TypeScript knows maybeAccount is Account | Address\n *   const address = extractAddress(maybeAccount);\n *   await vana.data.getUserFiles({ owner: address });\n * } else {\n *   console.error('Invalid address format');\n * }\n *\n * // Filter valid addresses from mixed array\n * const addresses = mixedArray.filter(hasAddress).map(extractAddress);\n * ```\n *\n * @category Utilities\n */\nexport function hasAddress(account: unknown): account is Account | Address {\n  if (!account) return false;\n\n  if (typeof account === \"string\") {\n    // Basic check for Ethereum address format\n    return /^0x[a-fA-F0-9]{40}$/.test(account);\n  }\n\n  if (typeof account === \"object\" && \"address\" in account) {\n    const accountWithAddress = account as { address: unknown };\n    const addr = accountWithAddress.address;\n    return typeof addr === \"string\" && /^0x[a-fA-F0-9]{40}$/.test(addr);\n  }\n\n  return false;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAmCO,SAAS,eACd,SACS;AACT,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,qBAAqB;AAAA,EACvC;AAGA,MAAI,OAAO,YAAY,UAAU;AAC/B,WAAO;AAAA,EACT;AAGA,MAAI,OAAO,YAAY,YAAY,aAAa,WAAW,QAAQ,SAAS;AAC1E,WAAO,QAAQ;AAAA,EACjB;AAEA,QAAM,IAAI,MAAM,iDAAiD;AACnE;AA8BO,SAAS,mBACd,SACqB;AACrB,MAAI;AACF,WAAO,eAAe,OAAO;AAAA,EAC/B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AA+BO,SAAS,WAAW,SAAgD;AACzE,MAAI,CAAC,QAAS,QAAO;AAErB,MAAI,OAAO,YAAY,UAAU;AAE/B,WAAO,sBAAsB,KAAK,OAAO;AAAA,EAC3C;AAEA,MAAI,OAAO,YAAY,YAAY,aAAa,SAAS;AACvD,UAAM,qBAAqB;AAC3B,UAAM,OAAO,mBAAmB;AAChC,WAAO,OAAO,SAAS,YAAY,sBAAsB,KAAK,IAAI;AAAA,EACpE;AAEA,SAAO;AACT;","names":[]}

package/dist/utils/wallet.d.ts

@@ -2,31 +2,93 @@ import type { Account, Address } from "viem";
 /**
  * Extracts an Ethereum address from various account formats.
  *
- * Viem's Account type can be:
- * - A string address directly
- * - An object with an address property
- * - A LocalAccount with address property
+ * @remarks
+ * Handles viem's polymorphic Account type which can be a string address,
+ * an object with an address property, or a LocalAccount. This utility
+ * provides consistent address extraction across the SDK, eliminating
+ * duplicate logic and potential inconsistencies.
  *
- * This utility provides a single source of truth for address extraction,
- * eliminating duplicate logic throughout the codebase.
+ * @param account - The account to extract address from.
+ *   Can be a hex string address, Account object, or LocalAccount.
+ * @returns The extracted Ethereum address as a `0x`-prefixed string
  *
- * @param account - The account to extract address from
- * @returns The extracted Ethereum address
- * @throws Error if account is undefined or address cannot be determined
+ * @throws {Error} When account is undefined or null.
+ *   Provide a valid account from wallet connection.
+ * @throws {Error} When address cannot be determined from account structure.
+ *   Ensure account has a valid address property.
+ *
+ * @example
+ * ```typescript
+ * // String address
+ * const addr1 = extractAddress('0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb');
+ *
+ * // Account object
+ * const addr2 = extractAddress({ address: '0x742d...' });
+ *
+ * // LocalAccount from viem
+ * const account = privateKeyToAccount('0x...');
+ * const addr3 = extractAddress(account);
+ * ```
+ *
+ * @category Utilities
  */
 export declare function extractAddress(account: Account | Address | undefined | null): Address;
 /**
- * Safely extracts an address, returning undefined instead of throwing.
- * Useful for optional address resolution.
+ * Safely extracts an address without throwing errors.
+ *
+ * @remarks
+ * Non-throwing version of `extractAddress` for optional address resolution.
+ * Use when address extraction failure is acceptable and should be handled
+ * gracefully without exception handling.
+ *
+ * @param account - The account to extract address from.
+ *   Can be a hex string address, Account object, LocalAccount, or nullish.
+ * @returns The extracted Ethereum address or `undefined` if extraction fails
+ *
+ * @example
+ * ```typescript
+ * const address = extractAddressSafe(potentialAccount);
  *
- * @param account - The account to extract address from
- * @returns The extracted address or undefined
+ * if (address) {
+ *   console.log(`Using address: ${address}`);
+ * } else {
+ *   console.log('No valid address available');
+ * }
+ *
+ * // Useful in optional chaining
+ * const userAddress = extractAddressSafe(user?.wallet) ?? DEFAULT_ADDRESS;
+ * ```
+ *
+ * @category Utilities
  */
 export declare function extractAddressSafe(account: Account | Address | undefined | null): Address | undefined;
 /**
- * Type guard to check if an account has a valid address.
+ * Validates whether a value contains a valid Ethereum address.
+ *
+ * @remarks
+ * Type guard that performs runtime validation of Ethereum address format.
+ * Checks for proper `0x` prefix and 40 hexadecimal characters. Works with
+ * string addresses, Account objects, and LocalAccount instances.
+ *
+ * @param account - The value to validate for address presence
+ * @returns `true` if account contains a valid Ethereum address, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const maybeAccount: unknown = getUserInput();
+ *
+ * if (hasAddress(maybeAccount)) {
+ *   // TypeScript knows maybeAccount is Account | Address
+ *   const address = extractAddress(maybeAccount);
+ *   await vana.data.getUserFiles({ owner: address });
+ * } else {
+ *   console.error('Invalid address format');
+ * }
+ *
+ * // Filter valid addresses from mixed array
+ * const addresses = mixedArray.filter(hasAddress).map(extractAddress);
+ * ```
  *
- * @param account - The account to check
- * @returns True if account has a valid address
+ * @category Utilities
  */
 export declare function hasAddress(account: unknown): account is Account | Address;

package/dist/utils/wallet.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/wallet.ts"],"sourcesContent":["import type { Account, Address } from \"viem\";\n\n/**\n * Extracts an Ethereum address from various account formats.\n *\n * Viem's Account type can be:\n * - A string address directly\n * - An object with an address property\n * - A LocalAccount with address property\n *\n * This utility provides a single source of truth for address extraction,\n * eliminating duplicate logic throughout the codebase.\n *\n * @param account - The account to extract address from\n * @returns The extracted Ethereum address\n * @throws Error if account is undefined or address cannot be determined\n */\nexport function extractAddress(\n  account: Account | Address | undefined | null,\n): Address {\n  if (!account) {\n    throw new Error(\"No account provided\");\n  }\n\n  // Handle string address directly\n  if (typeof account === \"string\") {\n    return account as Address;\n  }\n\n  // Handle object with address property\n  if (typeof account === \"object\" && \"address\" in account && account.address) {\n    return account.address;\n  }\n\n  throw new Error(\"Unable to determine wallet address from account\");\n}\n\n/**\n * Safely extracts an address, returning undefined instead of throwing.\n * Useful for optional address resolution.\n *\n * @param account - The account to extract address from\n * @returns The extracted address or undefined\n */\nexport function extractAddressSafe(\n  account: Account | Address | undefined | null,\n): Address | undefined {\n  try {\n    return extractAddress(account);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Type guard to check if an account has a valid address.\n *\n * @param account - The account to check\n * @returns True if account has a valid address\n */\nexport function hasAddress(account: unknown): account is Account | Address {\n  if (!account) return false;\n\n  if (typeof account === \"string\") {\n    // Basic check for Ethereum address format\n    return /^0x[a-fA-F0-9]{40}$/.test(account);\n  }\n\n  if (typeof account === \"object\" && \"address\" in account) {\n    const accountWithAddress = account as { address: unknown };\n    const addr = accountWithAddress.address;\n    return typeof addr === \"string\" && /^0x[a-fA-F0-9]{40}$/.test(addr);\n  }\n\n  return false;\n}\n"],"mappings":"AAiBO,SAAS,eACd,SACS;AACT,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,qBAAqB;AAAA,EACvC;AAGA,MAAI,OAAO,YAAY,UAAU;AAC/B,WAAO;AAAA,EACT;AAGA,MAAI,OAAO,YAAY,YAAY,aAAa,WAAW,QAAQ,SAAS;AAC1E,WAAO,QAAQ;AAAA,EACjB;AAEA,QAAM,IAAI,MAAM,iDAAiD;AACnE;AASO,SAAS,mBACd,SACqB;AACrB,MAAI;AACF,WAAO,eAAe,OAAO;AAAA,EAC/B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAQO,SAAS,WAAW,SAAgD;AACzE,MAAI,CAAC,QAAS,QAAO;AAErB,MAAI,OAAO,YAAY,UAAU;AAE/B,WAAO,sBAAsB,KAAK,OAAO;AAAA,EAC3C;AAEA,MAAI,OAAO,YAAY,YAAY,aAAa,SAAS;AACvD,UAAM,qBAAqB;AAC3B,UAAM,OAAO,mBAAmB;AAChC,WAAO,OAAO,SAAS,YAAY,sBAAsB,KAAK,IAAI;AAAA,EACpE;AAEA,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../src/utils/wallet.ts"],"sourcesContent":["import type { Account, Address } from \"viem\";\n\n/**\n * Extracts an Ethereum address from various account formats.\n *\n * @remarks\n * Handles viem's polymorphic Account type which can be a string address,\n * an object with an address property, or a LocalAccount. This utility\n * provides consistent address extraction across the SDK, eliminating\n * duplicate logic and potential inconsistencies.\n *\n * @param account - The account to extract address from.\n *   Can be a hex string address, Account object, or LocalAccount.\n * @returns The extracted Ethereum address as a `0x`-prefixed string\n *\n * @throws {Error} When account is undefined or null.\n *   Provide a valid account from wallet connection.\n * @throws {Error} When address cannot be determined from account structure.\n *   Ensure account has a valid address property.\n *\n * @example\n * ```typescript\n * // String address\n * const addr1 = extractAddress('0x742d35Cc6634C0532925a3b844Bc9e7595f0b0Bb');\n *\n * // Account object\n * const addr2 = extractAddress({ address: '0x742d...' });\n *\n * // LocalAccount from viem\n * const account = privateKeyToAccount('0x...');\n * const addr3 = extractAddress(account);\n * ```\n *\n * @category Utilities\n */\nexport function extractAddress(\n  account: Account | Address | undefined | null,\n): Address {\n  if (!account) {\n    throw new Error(\"No account provided\");\n  }\n\n  // Handle string address directly\n  if (typeof account === \"string\") {\n    return account as Address;\n  }\n\n  // Handle object with address property\n  if (typeof account === \"object\" && \"address\" in account && account.address) {\n    return account.address;\n  }\n\n  throw new Error(\"Unable to determine wallet address from account\");\n}\n\n/**\n * Safely extracts an address without throwing errors.\n *\n * @remarks\n * Non-throwing version of `extractAddress` for optional address resolution.\n * Use when address extraction failure is acceptable and should be handled\n * gracefully without exception handling.\n *\n * @param account - The account to extract address from.\n *   Can be a hex string address, Account object, LocalAccount, or nullish.\n * @returns The extracted Ethereum address or `undefined` if extraction fails\n *\n * @example\n * ```typescript\n * const address = extractAddressSafe(potentialAccount);\n *\n * if (address) {\n *   console.log(`Using address: ${address}`);\n * } else {\n *   console.log('No valid address available');\n * }\n *\n * // Useful in optional chaining\n * const userAddress = extractAddressSafe(user?.wallet) ?? DEFAULT_ADDRESS;\n * ```\n *\n * @category Utilities\n */\nexport function extractAddressSafe(\n  account: Account | Address | undefined | null,\n): Address | undefined {\n  try {\n    return extractAddress(account);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Validates whether a value contains a valid Ethereum address.\n *\n * @remarks\n * Type guard that performs runtime validation of Ethereum address format.\n * Checks for proper `0x` prefix and 40 hexadecimal characters. Works with\n * string addresses, Account objects, and LocalAccount instances.\n *\n * @param account - The value to validate for address presence\n * @returns `true` if account contains a valid Ethereum address, `false` otherwise\n *\n * @example\n * ```typescript\n * const maybeAccount: unknown = getUserInput();\n *\n * if (hasAddress(maybeAccount)) {\n *   // TypeScript knows maybeAccount is Account | Address\n *   const address = extractAddress(maybeAccount);\n *   await vana.data.getUserFiles({ owner: address });\n * } else {\n *   console.error('Invalid address format');\n * }\n *\n * // Filter valid addresses from mixed array\n * const addresses = mixedArray.filter(hasAddress).map(extractAddress);\n * ```\n *\n * @category Utilities\n */\nexport function hasAddress(account: unknown): account is Account | Address {\n  if (!account) return false;\n\n  if (typeof account === \"string\") {\n    // Basic check for Ethereum address format\n    return /^0x[a-fA-F0-9]{40}$/.test(account);\n  }\n\n  if (typeof account === \"object\" && \"address\" in account) {\n    const accountWithAddress = account as { address: unknown };\n    const addr = accountWithAddress.address;\n    return typeof addr === \"string\" && /^0x[a-fA-F0-9]{40}$/.test(addr);\n  }\n\n  return false;\n}\n"],"mappings":"AAmCO,SAAS,eACd,SACS;AACT,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,MAAM,qBAAqB;AAAA,EACvC;AAGA,MAAI,OAAO,YAAY,UAAU;AAC/B,WAAO;AAAA,EACT;AAGA,MAAI,OAAO,YAAY,YAAY,aAAa,WAAW,QAAQ,SAAS;AAC1E,WAAO,QAAQ;AAAA,EACjB;AAEA,QAAM,IAAI,MAAM,iDAAiD;AACnE;AA8BO,SAAS,mBACd,SACqB;AACrB,MAAI;AACF,WAAO,eAAe,OAAO;AAAA,EAC/B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AA+BO,SAAS,WAAW,SAAgD;AACzE,MAAI,CAAC,QAAS,QAAO;AAErB,MAAI,OAAO,YAAY,UAAU;AAE/B,WAAO,sBAAsB,KAAK,OAAO;AAAA,EAC3C;AAEA,MAAI,OAAO,YAAY,YAAY,aAAa,SAAS;AACvD,UAAM,qBAAqB;AAC3B,UAAM,OAAO,mBAAmB;AAChC,WAAO,OAAO,SAAS,YAAY,sBAAsB,KAAK,IAAI;AAAA,EACpE;AAEA,SAAO;AACT;","names":[]}