@opendatalabs/vana-sdk 0.1.0-alpha.ffe4659 → 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/tests/multicall.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/transactionHelpers.cjs

@@ -0,0 +1,54 @@
+"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 transactionHelpers_exports = {};
+__export(transactionHelpers_exports, {
+  tx: () => tx,
+  txLiteral: () => txLiteral
+});
+module.exports = __toCommonJS(transactionHelpers_exports);
+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 }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  tx,
+  txLiteral
+});
+//# sourceMappingURL=transactionHelpers.cjs.map

package/dist/utils/transactionHelpers.cjs.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 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

@@ -0,0 +1,80 @@
+/**
+ * Helper functions for creating typed transaction POJOs
+ */
+import type { Hash, Address } from "viem";
+import type { TransactionResult } from "../types/operations";
+import type { Contract, Fn } from "../generated/event-types";
+/**
+ * Creates typed TransactionResult with validation.
+ *
+ * @remarks
+ * Ensures type safety for transaction results.
+ * Reduces boilerplate in transaction handling.
+ *
+ * @param input - Transaction details
+ * @param input.hash - Transaction hash from the blockchain
+ * @param input.from - Transaction sender address
+ * @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
+ * return tx({
+ *   hash,
+ *   from: account.address,
+ *   contract: "DataPortabilityPermissions",
+ *   fn: "revokePermission"
+ * });
+ * ```
+ */
+export 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
+ * ```
+ */
+export 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>;

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 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/typeGuards.cjs

@@ -0,0 +1,109 @@
+"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 typeGuards_exports = {};
+__export(typeGuards_exports, {
+  assertDefined: () => assertDefined,
+  assertHasProperties: () => assertHasProperties,
+  assertNonEmptyString: () => assertNonEmptyString,
+  ensureDefault: () => ensureDefault,
+  ensureError: () => ensureError,
+  hasProperty: () => hasProperty,
+  isArray: () => isArray,
+  isDefined: () => isDefined,
+  isNonEmptyString: () => isNonEmptyString,
+  isObject: () => isObject,
+  safeArrayAccess: () => safeArrayAccess,
+  safeGet: () => safeGet
+});
+module.exports = __toCommonJS(typeGuards_exports);
+function assertDefined(value, message) {
+  if (value === void 0 || value === null) {
+    throw new Error(message);
+  }
+}
+function isDefined(value) {
+  return value !== void 0 && value !== null;
+}
+function assertNonEmptyString(value, message) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(message);
+  }
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function safeGet(obj, key) {
+  return obj?.[key];
+}
+function ensureDefault(value, defaultValue) {
+  return isDefined(value) ? value : defaultValue;
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function isArray(value) {
+  return Array.isArray(value);
+}
+function safeArrayAccess(array, index) {
+  if (!array || index < 0 || index >= array.length) {
+    return void 0;
+  }
+  return array[index];
+}
+function hasProperty(obj, prop) {
+  return isObject(obj) && prop in obj;
+}
+function assertHasProperties(obj, properties, message) {
+  if (!isObject(obj)) {
+    throw new Error(`${message}: Value is not an object`);
+  }
+  for (const prop of properties) {
+    if (!(prop in obj)) {
+      throw new Error(`${message}: Missing required property '${prop}'`);
+    }
+  }
+}
+function ensureError(error, fallbackMessage) {
+  if (error instanceof Error) {
+    return error;
+  }
+  if (typeof error === "string") {
+    return new Error(error);
+  }
+  if (isObject(error) && "message" in error && typeof error.message === "string") {
+    return new Error(error.message);
+  }
+  return new Error(fallbackMessage);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertDefined,
+  assertHasProperties,
+  assertNonEmptyString,
+  ensureDefault,
+  ensureError,
+  hasProperty,
+  isArray,
+  isDefined,
+  isNonEmptyString,
+  isObject,
+  safeArrayAccess,
+  safeGet
+});
+//# sourceMappingURL=typeGuards.cjs.map

package/dist/utils/typeGuards.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/typeGuards.ts"],"sourcesContent":["/**\n * Type guard utilities for runtime type checking and assertions.\n * These utilities provide type-safe alternatives to non-null assertions (!).\n *\n * @module typeGuards\n */\n\n/**\n * Asserts that a value is defined (not null or undefined).\n * Throws an error with a descriptive message if the assertion fails.\n *\n * @param value - The value to check\n * @param message - Error message to throw if value is not defined\n * @throws {Error} If value is null or undefined\n *\n * @example\n * ```typescript\n * const wallet = getWallet();\n * assertDefined(wallet, 'Wallet must be initialized before use');\n * // TypeScript now knows wallet is defined\n * console.log(wallet.address);\n * ```\n */\nexport function assertDefined<T>(\n  value: T | undefined | null,\n  message: string,\n): asserts value is T {\n  if (value === undefined || value === null) {\n    throw new Error(message);\n  }\n}\n\n/**\n * Type guard to check if a value is defined (not null or undefined).\n *\n * @param value - The value to check\n * @returns True if the value is defined, false otherwise\n *\n * @example\n * ```typescript\n * const values = [1, undefined, 3, null, 5];\n * const defined = values.filter(isDefined); // [1, 3, 5]\n * ```\n */\nexport function isDefined<T>(value: T | undefined | null): value is T {\n  return value !== undefined && value !== null;\n}\n\n/**\n * Asserts that a value is a non-empty string.\n *\n * @param value - The value to check\n * @param message - Error message if assertion fails\n * @throws {Error} If value is not a non-empty string\n */\nexport function assertNonEmptyString(\n  value: unknown,\n  message: string,\n): asserts value is string {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new Error(message);\n  }\n}\n\n/**\n * Type guard to check if a value is a non-empty string.\n *\n * @param value - The value to check\n * @returns True if value is a non-empty string\n */\nexport function isNonEmptyString(value: unknown): value is string {\n  return typeof value === \"string\" && value.trim().length > 0;\n}\n\n/**\n * Safely gets a property from an object, returning undefined if the property doesn't exist.\n *\n * @param obj - The object to get the property from\n * @param key - The property key\n * @returns The property value or undefined\n *\n * @example\n * ```typescript\n * const config = { wallet: { address: '0x123' } };\n * const address = safeGet(config, 'wallet')?.address;\n * ```\n */\nexport function safeGet<T, K extends keyof T>(\n  obj: T | undefined | null,\n  key: K,\n): T[K] | undefined {\n  return obj?.[key];\n}\n\n/**\n * Ensures a value is defined or returns a default value.\n *\n * @param value - The value to check\n * @param defaultValue - The default value to use if undefined\n * @returns The value if defined, otherwise the default\n *\n * @example\n * ```typescript\n * const timeout = ensureDefault(config.timeout, 5000);\n * ```\n */\nexport function ensureDefault<T>(\n  value: T | undefined | null,\n  defaultValue: T,\n): T {\n  return isDefined(value) ? value : defaultValue;\n}\n\n/**\n * Type guard for checking if a value is an object (and not null).\n *\n * @param value - The value to check\n * @returns True if value is an object\n */\nexport function isObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n\n/**\n * Type guard for checking if a value is an array.\n *\n * @param value - The value to check\n * @returns True if value is an array\n */\nexport function isArray<T = unknown>(value: unknown): value is T[] {\n  return Array.isArray(value);\n}\n\n/**\n * Safely accesses an array element, returning undefined if out of bounds.\n *\n * @param array - The array to access\n * @param index - The index to access\n * @returns The element at the index or undefined\n *\n * @example\n * ```typescript\n * const items = [1, 2, 3];\n * const item = safeArrayAccess(items, 5); // undefined\n * ```\n */\nexport function safeArrayAccess<T>(\n  array: T[] | undefined | null,\n  index: number,\n): T | undefined {\n  if (!array || index < 0 || index >= array.length) {\n    return undefined;\n  }\n  return array[index];\n}\n\n/**\n * Type guard to check if a value has a specific property.\n *\n * @param obj - The object to check\n * @param prop - The property name\n * @returns True if the object has the property\n *\n * @example\n * ```typescript\n * if (hasProperty(response, 'error')) {\n *   console.error(response.error);\n * }\n * ```\n */\nexport function hasProperty<T extends string>(\n  obj: unknown,\n  prop: T,\n): obj is Record<T, unknown> {\n  return isObject(obj) && prop in obj;\n}\n\n/**\n * Asserts that an object has required properties.\n *\n * @param obj - The object to check\n * @param properties - Array of required property names\n * @param message - Error message if assertion fails\n * @throws {Error} If any required property is missing\n */\nexport function assertHasProperties<T extends string>(\n  obj: unknown,\n  properties: T[],\n  message: string,\n): asserts obj is Record<T, unknown> {\n  if (!isObject(obj)) {\n    throw new Error(`${message}: Value is not an object`);\n  }\n\n  for (const prop of properties) {\n    if (!(prop in obj)) {\n      throw new Error(`${message}: Missing required property '${prop}'`);\n    }\n  }\n}\n\n/**\n * Creates a type-safe error with a guaranteed message.\n *\n * @param error - The error or unknown value\n * @param fallbackMessage - Message to use if error doesn't have one\n * @returns An Error object with a message\n */\nexport function ensureError(error: unknown, fallbackMessage: string): Error {\n  if (error instanceof Error) {\n    return error;\n  }\n  if (typeof error === \"string\") {\n    return new Error(error);\n  }\n  if (\n    isObject(error) &&\n    \"message\" in error &&\n    typeof error.message === \"string\"\n  ) {\n    return new Error(error.message);\n  }\n  return new Error(fallbackMessage);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAuBO,SAAS,cACd,OACA,SACoB;AACpB,MAAI,UAAU,UAAa,UAAU,MAAM;AACzC,UAAM,IAAI,MAAM,OAAO;AAAA,EACzB;AACF;AAcO,SAAS,UAAa,OAAyC;AACpE,SAAO,UAAU,UAAa,UAAU;AAC1C;AASO,SAAS,qBACd,OACA,SACyB;AACzB,MAAI,OAAO,UAAU,YAAY,MAAM,KAAK,EAAE,WAAW,GAAG;AAC1D,UAAM,IAAI,MAAM,OAAO;AAAA,EACzB;AACF;AAQO,SAAS,iBAAiB,OAAiC;AAChE,SAAO,OAAO,UAAU,YAAY,MAAM,KAAK,EAAE,SAAS;AAC5D;AAeO,SAAS,QACd,KACA,KACkB;AAClB,SAAO,MAAM,GAAG;AAClB;AAcO,SAAS,cACd,OACA,cACG;AACH,SAAO,UAAU,KAAK,IAAI,QAAQ;AACpC;AAQO,SAAS,SAAS,OAAkD;AACzE,SAAO,OAAO,UAAU,YAAY,UAAU;AAChD;AAQO,SAAS,QAAqB,OAA8B;AACjE,SAAO,MAAM,QAAQ,KAAK;AAC5B;AAeO,SAAS,gBACd,OACA,OACe;AACf,MAAI,CAAC,SAAS,QAAQ,KAAK,SAAS,MAAM,QAAQ;AAChD,WAAO;AAAA,EACT;AACA,SAAO,MAAM,KAAK;AACpB;AAgBO,SAAS,YACd,KACA,MAC2B;AAC3B,SAAO,SAAS,GAAG,KAAK,QAAQ;AAClC;AAUO,SAAS,oBACd,KACA,YACA,SACmC;AACnC,MAAI,CAAC,SAAS,GAAG,GAAG;AAClB,UAAM,IAAI,MAAM,GAAG,OAAO,0BAA0B;AAAA,EACtD;AAEA,aAAW,QAAQ,YAAY;AAC7B,QAAI,EAAE,QAAQ,MAAM;AAClB,YAAM,IAAI,MAAM,GAAG,OAAO,gCAAgC,IAAI,GAAG;AAAA,IACnE;AAAA,EACF;AACF;AASO,SAAS,YAAY,OAAgB,iBAAgC;AAC1E,MAAI,iBAAiB,OAAO;AAC1B,WAAO;AAAA,EACT;AACA,MAAI,OAAO,UAAU,UAAU;AAC7B,WAAO,IAAI,MAAM,KAAK;AAAA,EACxB;AACA,MACE,SAAS,KAAK,KACd,aAAa,SACb,OAAO,MAAM,YAAY,UACzB;AACA,WAAO,IAAI,MAAM,MAAM,OAAO;AAAA,EAChC;AACA,SAAO,IAAI,MAAM,eAAe;AAClC;","names":[]}

package/dist/utils/typeGuards.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Type guard utilities for runtime type checking and assertions.
+ * These utilities provide type-safe alternatives to non-null assertions (!).
+ *
+ * @module typeGuards
+ */
+/**
+ * Asserts that a value is defined (not null or undefined).
+ * Throws an error with a descriptive message if the assertion fails.
+ *
+ * @param value - The value to check
+ * @param message - Error message to throw if value is not defined
+ * @throws {Error} If value is null or undefined
+ *
+ * @example
+ * ```typescript
+ * const wallet = getWallet();
+ * assertDefined(wallet, 'Wallet must be initialized before use');
+ * // TypeScript now knows wallet is defined
+ * console.log(wallet.address);
+ * ```
+ */
+export declare function assertDefined<T>(value: T | undefined | null, message: string): asserts value is T;
+/**
+ * Type guard to check if a value is defined (not null or undefined).
+ *
+ * @param value - The value to check
+ * @returns True if the value is defined, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const values = [1, undefined, 3, null, 5];
+ * const defined = values.filter(isDefined); // [1, 3, 5]
+ * ```
+ */
+export declare function isDefined<T>(value: T | undefined | null): value is T;
+/**
+ * Asserts that a value is a non-empty string.
+ *
+ * @param value - The value to check
+ * @param message - Error message if assertion fails
+ * @throws {Error} If value is not a non-empty string
+ */
+export declare function assertNonEmptyString(value: unknown, message: string): asserts value is string;
+/**
+ * Type guard to check if a value is a non-empty string.
+ *
+ * @param value - The value to check
+ * @returns True if value is a non-empty string
+ */
+export declare function isNonEmptyString(value: unknown): value is string;
+/**
+ * Safely gets a property from an object, returning undefined if the property doesn't exist.
+ *
+ * @param obj - The object to get the property from
+ * @param key - The property key
+ * @returns The property value or undefined
+ *
+ * @example
+ * ```typescript
+ * const config = { wallet: { address: '0x123' } };
+ * const address = safeGet(config, 'wallet')?.address;
+ * ```
+ */
+export declare function safeGet<T, K extends keyof T>(obj: T | undefined | null, key: K): T[K] | undefined;
+/**
+ * Ensures a value is defined or returns a default value.
+ *
+ * @param value - The value to check
+ * @param defaultValue - The default value to use if undefined
+ * @returns The value if defined, otherwise the default
+ *
+ * @example
+ * ```typescript
+ * const timeout = ensureDefault(config.timeout, 5000);
+ * ```
+ */
+export declare function ensureDefault<T>(value: T | undefined | null, defaultValue: T): T;
+/**
+ * Type guard for checking if a value is an object (and not null).
+ *
+ * @param value - The value to check
+ * @returns True if value is an object
+ */
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Type guard for checking if a value is an array.
+ *
+ * @param value - The value to check
+ * @returns True if value is an array
+ */
+export declare function isArray<T = unknown>(value: unknown): value is T[];
+/**
+ * Safely accesses an array element, returning undefined if out of bounds.
+ *
+ * @param array - The array to access
+ * @param index - The index to access
+ * @returns The element at the index or undefined
+ *
+ * @example
+ * ```typescript
+ * const items = [1, 2, 3];
+ * const item = safeArrayAccess(items, 5); // undefined
+ * ```
+ */
+export declare function safeArrayAccess<T>(array: T[] | undefined | null, index: number): T | undefined;
+/**
+ * Type guard to check if a value has a specific property.
+ *
+ * @param obj - The object to check
+ * @param prop - The property name
+ * @returns True if the object has the property
+ *
+ * @example
+ * ```typescript
+ * if (hasProperty(response, 'error')) {
+ *   console.error(response.error);
+ * }
+ * ```
+ */
+export declare function hasProperty<T extends string>(obj: unknown, prop: T): obj is Record<T, unknown>;
+/**
+ * Asserts that an object has required properties.
+ *
+ * @param obj - The object to check
+ * @param properties - Array of required property names
+ * @param message - Error message if assertion fails
+ * @throws {Error} If any required property is missing
+ */
+export declare function assertHasProperties<T extends string>(obj: unknown, properties: T[], message: string): asserts obj is Record<T, unknown>;
+/**
+ * Creates a type-safe error with a guaranteed message.
+ *
+ * @param error - The error or unknown value
+ * @param fallbackMessage - Message to use if error doesn't have one
+ * @returns An Error object with a message
+ */
+export declare function ensureError(error: unknown, fallbackMessage: string): Error;