wagmi-extended 0.5.0 → 1.0.0

package/dist/query-config/index.d.ts

@@ -0,0 +1,8 @@
+export declare const queryConfig: {
+    metadataQueryConfig: {
+        staleTime: number;
+    };
+    sensitiveDataQueryConfig: {
+        staleTime: number;
+    };
+};

package/dist/utils/{errorParser.d.ts → errorParserX.d.ts}

@@ -44,4 +44,4 @@ export declare const getErrorMapping: () => Record<string, string>;
  * const message = getParsedError(someError);
  * console.log(message); // Outputs a custom error message or a default error message.
  */
-export declare const getParsedError: (error: any | BaseError) => string;
+export declare const getParsedErrorX: (error: any | BaseError) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wagmi-extended",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "type": "module",
   "description": "A library providing extended hooks on top of Wagmi with additional features.",
   "main": "dist/index.cjs.js",
@@ -30,7 +30,7 @@
   "license": "MIT",
   "scripts": {
     "clean": "rimraf dist",
-    "build": "npm run clean && npm version minor && rollup -c --bundleConfigAsCjs",
+    "build": "npm run clean && rollup -c --bundleConfigAsCjs",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {

package/src/config/defaults.ts

@@ -0,0 +1,60 @@
+// src/config/defaults.ts
+import { QueryClient } from "@tanstack/react-query";
+import { Config } from "wagmi";
+
+// You can adjust the type for wagmiConfig to match your needs.
+let defaultQueryClient: QueryClient | null = null;
+let defaultWagmiConfig: any = null;
+
+/**
+ * Sets the default configuration values.
+ *
+ * @param queryClient - The default QueryClient instance.
+ * @param wagmiConfig - The default Wagmi configuration.
+ * @example
+ * //In your application initialization (e.g., index.tsx or App.tsx):
+ * import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+ * import { wagmiConfig } from "/path/to/wagmi-config";
+ * import { setDefaults } from "wagmi-extended";
+ *
+ * const queryClient = new QueryClient();
+ *
+ * //Set defaults for the extended library functions.
+ * setDefaults(queryClient, wagmiConfig);
+ *
+ * //Now helper functions like fetchTokenX can use these defaults if no explicit parameters are provided.
+ */
+export function setDefaults(
+  queryClient: QueryClient,
+  wagmiConfig: Config
+): void {
+  defaultQueryClient = queryClient;
+  defaultWagmiConfig = wagmiConfig;
+}
+
+/**
+ * Retrieves the currently set default configurations.
+ *
+ * @throws Will throw an error if defaults are not initialized.
+ * @returns An object containing the default queryClient and wagmiConfig.
+ *
+ * @example
+ * // Usage in a helper function:
+ * import { getDefaults } from "wagmi-extended";
+ *
+ * function exampleFunction() {
+ *   const { queryClient, wagmiConfig } = getDefaults();
+ *   // Use queryClient and wagmiConfig as needed...
+ * }
+ */
+export function getDefaults(): {
+  queryClient: QueryClient;
+  wagmiConfig: Config;
+} {
+  if (!defaultQueryClient || !defaultWagmiConfig) {
+    throw new Error(
+      "Default configuration not set. Please call setDefaults() first."
+    );
+  }
+  return { queryClient: defaultQueryClient, wagmiConfig: defaultWagmiConfig };
+}

package/src/fetch-functions/fetchAllowanceX.ts

@@ -0,0 +1,22 @@
+import { Address, erc20Abi } from "viem";
+import { readContract } from "viem/actions";
+
+export const fetchAllowance = async (
+  asset: Address,
+  spender: Address,
+  userAddress: Address,
+  config: any
+) => {
+  const allowance = await readContract(config, {
+    address: asset,
+    abi: erc20Abi,
+    functionName: "allowance",
+    args: [userAddress, spender],
+  });
+
+  if (allowance == null) {
+    throw new Error("Failed to fetch token data or allowance");
+  }
+
+  return allowance;
+};

package/src/fetch-functions/fetchTokenX.ts

@@ -0,0 +1,134 @@
+import { QueryClient } from "@tanstack/react-query";
+import { readContractQueryOptions } from "wagmi/query";
+import { Address, zeroAddress, erc20Abi } from "viem";
+import { Config } from "wagmi";
+import { getDefaults } from "../config/defaults.js";
+import { queryConfig } from "../query-config/index.js";
+
+export interface Token {
+  symbol: string;
+  decimals: number;
+  name: string;
+}
+
+export const EthTokenData: Token = {
+  symbol: "ETH",
+  decimals: 18,
+  name: "Ethereum",
+};
+
+export async function fetchDecimalsX(
+  token: Address,
+  queryClient?: QueryClient,
+  wagmiConfig?: Config
+): Promise<number | undefined> {
+  if (!queryClient || !wagmiConfig) {
+    ({ queryClient, wagmiConfig } = getDefaults());
+  }
+  if (!queryClient || !wagmiConfig) {
+    throw new Error(
+      "Could not find queryClient or wagmiConfig, either pass them as arguments or set them using setDefaults()"
+    );
+  }
+
+  if (token === zeroAddress) return EthTokenData.decimals;
+
+  const decimals = await queryClient.fetchQuery({
+    ...readContractQueryOptions(wagmiConfig, {
+      address: token,
+      abi: erc20Abi,
+      functionName: "decimals",
+    }),
+    ...queryConfig.metadataQueryConfig,
+  });
+
+  return decimals;
+}
+
+export async function fetchSymbolX(
+  token: Address,
+  queryClient?: QueryClient,
+  wagmiConfig?: Config
+): Promise<string> {
+  if (!queryClient || !wagmiConfig) {
+    ({ queryClient, wagmiConfig } = getDefaults());
+  }
+  if (!queryClient || !wagmiConfig) {
+    throw new Error(
+      "Could not find queryClient or wagmiConfig, either pass them as arguments or set them using setDefaults()"
+    );
+  }
+
+  if (token === zeroAddress) return EthTokenData.symbol;
+
+  const symbol = await queryClient.fetchQuery({
+    ...readContractQueryOptions(wagmiConfig, {
+      address: token,
+      abi: erc20Abi,
+      functionName: "symbol",
+    }),
+    ...queryConfig.metadataQueryConfig,
+  });
+
+  return symbol;
+}
+
+export async function fetchNameX(
+  token: Address,
+  queryClient: any,
+  wagmiConfig: any
+): Promise<string> {
+  if (token === zeroAddress) return EthTokenData.name;
+
+  if (!queryClient || !wagmiConfig) {
+    ({ queryClient, wagmiConfig } = getDefaults());
+  }
+  if (!queryClient || !wagmiConfig) {
+    throw new Error(
+      "Could not find queryClient or wagmiConfig, either pass them as arguments or set them using setDefaults()"
+    );
+  }
+
+  const name = await queryClient.fetchQuery({
+    ...readContractQueryOptions(wagmiConfig, {
+      address: token,
+      abi: erc20Abi,
+      functionName: "name",
+    }),
+    ...queryConfig.metadataQueryConfig,
+  });
+
+  return name;
+}
+
+/**
+ * Fetches the token metadata (symbol, decimals) for the given token address.
+ * Internally calls:
+ *  - `fetchSymbol(token)`   to retrieve the token symbol,
+ *  - `fetchDecimals(token)` to retrieve the token decimals
+ *  - `fetchName(token)`     to retrieve the token name
+ *
+ * @param token - The address of the token.
+ * @returns A `Token` object containing the symbol, decimals.
+ * @throws Will throw an error if symbol or decimals cannot be fetched.
+ */
+export async function fetchTokenX(
+  token: Address,
+  queryClient: any,
+  wagmiConfig: any
+): Promise<Token> {
+  const [symbol, decimals, name] = await Promise.all([
+    fetchSymbolX(token, queryClient, wagmiConfig),
+    fetchDecimalsX(token, queryClient, wagmiConfig),
+    fetchNameX(token, queryClient, wagmiConfig),
+  ]);
+  if (!symbol || !decimals || !name) {
+    throw new Error("Failed to fetch token data");
+  }
+
+  return {
+    symbol,
+    decimals,
+    name,
+  };
+}

package/src/hooks/useContractWriteX.ts

@@ -0,0 +1,84 @@
+import { useWriteContract } from "wagmi";
+import {
+  WriteExtendedAsyncParams,
+  useHandleTransactionMutationX,
+} from "./useHandleTransactionMutationX.js";
+
+/**
+ * Custom hook for writing to a smart contract using Wagmi.
+ *
+ * This hook provides functionality for writing a contract using Wagmi, handling the asynchronous nature of the operation, waiting for the transaction receipt, and error handling.
+ *
+ * @param {WriteExtendedAsyncParams} [settings] - Optional settings for the write operation.
+ * @param {boolean} [settings.disableWaitingForReceipt] - Disables waiting for the transaction receipt.
+ * @param {boolean} [settings.disableLogging] - Disables logging the result of the transaction.
+ * @param {Function} [settings.onSuccess] - Callback function to be called on successful transaction.
+ * @param {Function} [settings.onError] - Callback function to be called on transaction error.
+ * @param {Function} [settings.onSettled] - Callback function to be called after the transaction settles (whether success or failure).
+ * @param {QueryKey[]} [settings.queriesToInvalidate] - Array of query keys to invalidate after the transaction receives a receipt.
+ * @returns {Object} Object containing the following properties:
+ * - {boolean} isPending - Indicates whether the transaction is pending.
+ * - {string|undefined} errorMessage - The error message, if an error occurred during the transaction.
+ * - {Function} writeContractAsync - Function to trigger the write operation.
+ * 
+/**
+ * Custom hook for writing a contract using Wagmi with extended functionality.
+ *
+ * This hook wraps Wagmi’s `useContractWriteX` with additional handling for
+ * waiting for a transaction receipt, logging control, and invalidation of specified queries.
+ *
+ * @param {WriteExtendedAsyncParams} [settings] - Optional settings for handling the transaction.
+ * @returns {Object} An object containing:
+ *   - `isPending`: {boolean} indicating if the transaction is in progress.
+ *   - `errorMessage`: {string|undefined} a potential error message.
+ *   - `writeContractAsync`: {Function} a function to trigger the transaction.
+ *
+ * @example
+ * // In your component:
+ * function MyTransactionComponent() {
+ *   const { writeContractAsync, isPending, errorMessage } = useContractWriteX({
+ *     onSuccess: (txHash) => console.log("Transaction successful:", txHash),
+ *     onError: (error) => console.error("Transaction error:", error),
+ *     queriesToInvalidate: [["userBalance"], ["userActivity"]],
+ *   });
+ *
+ *   const handleWrite = async () => {
+ *     try {
+ *       const txHash = await writeContractAsync({ transaction params here.. });
+ *       console.log("Received txHash:", txHash);
+ *     } catch (err) {
+ *       console.error("Failed writing transaction:", err);`
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleWrite} disabled={isPending}>
+ *         {isPending ? "Processing..." : "Write Transaction"}
+ *       </button>
+ *       {errorMessage && <p>Error: {errorMessage}</p>}
+ *     </div>
+ *   );
+ * }
+ */
+
+export function useContractWriteX(settings?: WriteExtendedAsyncParams) {
+  const { isPending, errorMessage, onMutate, onSettled } =
+    useHandleTransactionMutationX({
+      settings,
+    });
+
+  const { writeContractAsync, ...rest } = useWriteContract({
+    mutation: {
+      onMutate,
+      onSettled,
+    },
+  });
+
+  return {
+    ...rest,
+    isPending,
+    errorMessage,
+    writeContractAsync,
+  };
+}

package/src/hooks/useERC20ApproveX.ts

@@ -0,0 +1,108 @@
+import { useState, useEffect } from "react";
+import { Address, maxUint256, erc20Abi } from "viem";
+import { useFetchAssetAllowanceX } from "./useFetchAssetAllowanceX.js";
+import { useContractWriteX } from "./useContractWriteX.js";
+
+/**
+ * Custom hook for approving ERC20 token transfers.
+ *
+ * This hook provides functionality for approving ERC20 token transfers, checking the current allowance, and handling the approval transaction using Wagmi.
+ *
+ * @param {Address} tokenAddress - The address of the ERC20 token contract (the transfer from).
+ * @param {Address} spenderAddress - The address of the spender to approve the transfer to.
+ * @param {bigint} [amount=BigInt(0)] - The amount to approve for transfer. Defaults to undefined.
+ * @param {boolean} [approveMax=false] - Indicates whether to approve the maximum amount or a specific amount.
+ * @returns {Object} Object containing the following properties:
+ * - {boolean} isApproved - Indicates whether the spender is already approved to transfer the specified amount of tokens.
+ * - {boolean} isApproving - Indicates whether an approval transaction is currently pending.
+ * - {Function} approveAsync - Function to trigger the approval transaction.
+ *
+ * @example
+ * // In your component:
+ * function ApproveTokenButton(amountToApprove) {
+ *   const tokenAddress = "0xTokenAddressExample";
+ *   const spenderAddress = "0xSpenderAddressExample";
+ *
+ *   const { isApproved, isApproving, justApproved, approveAsync } = useERC20ApproveX(
+ *     tokenAddress,
+ *     spenderAddress,
+ *     parseUnits(amountToApprove.toString(), 18),
+ *   );
+ *
+ *   return (
+ *     <button onClick={approveAsync} disabled={isApproving || isApproved}>
+ *       {isApproving ? "Approving..." : isApproved ? "Approved" : "Approve Token"}
+ *     </button>
+ *   );
+ * }
+ */
+
+export const useERC20ApproveX = (
+  tokenAddress?: Address,
+  spenderAddress?: Address,
+  amount?: bigint,
+  approveMax?: boolean
+) => {
+  const [isApproved, setIsApproved] = useState(false);
+  const [justApproved, setJustApproved] = useState(false);
+
+  const { data: allowance, queryKey: allowanceKQ } = useFetchAssetAllowanceX({
+    asset: tokenAddress,
+    spender: spenderAddress,
+  });
+
+  const { writeContractAsync: approveTokenAsync, isPending } =
+    useContractWriteX({
+      queriesToInvalidate: [allowanceKQ],
+    });
+
+  useEffect(() => {
+    if (amount == null) {
+      setIsApproved(false);
+    } else if (allowance && allowance >= amount) {
+      setIsApproved(true);
+    } else {
+      setIsApproved(false);
+    }
+  }, [allowance, amount]);
+
+  const approveAsync = async () => {
+    const amountToApprove = approveMax ? maxUint256 : amount;
+
+    try {
+      if (!spenderAddress) {
+        throw new Error("spenderAddress is undefined!");
+      }
+      if (!tokenAddress) {
+        throw new Error("tokenAddress is undefined!");
+      }
+      if (amountToApprove == null) {
+        throw new Error("amountToApprove is undefined!");
+      }
+
+      await approveTokenAsync(
+        {
+          address: tokenAddress,
+          abi: erc20Abi,
+          functionName: "approve",
+          args: [spenderAddress, amountToApprove],
+        },
+        {
+          onSuccess: () => {
+            setJustApproved(true);
+          },
+        }
+      );
+    } catch (e: any) {
+      console.error("Error approving token:", e);
+      throw e;
+    }
+  };
+
+  return {
+    isApproved,
+    isApproving: isPending,
+    justApproved,
+    approveAsync,
+  };
+};

package/src/hooks/useFetchAssetAllowanceX.ts

@@ -0,0 +1,60 @@
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { Address, erc20Abi } from "viem";
+import { useAccount, useConfig } from "wagmi";
+import { queryConfig } from "../query-config/index.js";
+import { fetchAllowance } from "../fetch-functions/fetchAllowanceX.js";
+
+const HookFetchAssetAllowanceQK = (
+  asset?: Address,
+  spender?: Address,
+  userAddress?: Address
+) => ["HookFetchAllowance", asset, spender, userAddress] as const;
+
+/**
+ * Custom hook for fetching asset allowance.
+ *
+ * @param {Address} asset - The address of the ERC20 token contract.
+ * @param {Address} spender - The address of the spender to check allowance for.
+ *
+ *
+ * @example
+ * // In your component:
+ * function AllowanceDisplay() {
+ *   const { data: allowance, isLoading, error } = useFetchAssetAllowanceX({
+ *     asset: "0xTokenAddressExample",
+ *     spender: "0xSpenderAddressExample",
+ *   });
+ *
+ *   if (isLoading) return <div>Loading allowance...</div>;
+ *   if (error) return <div>Error loading allowance</div>;
+ *
+ *   return (
+ *     <div>
+ *       Current Allowance: {allowance}
+ *     </div>
+ *   );
+ * }
+ */
+export const useFetchAssetAllowanceX = ({
+  asset,
+  spender,
+}: {
+  asset?: Address;
+  spender?: Address;
+}) => {
+  const config = useConfig();
+  const { address: userAddress } = useAccount();
+
+  const { data, ...rest } = useQuery({
+    queryKey: HookFetchAssetAllowanceQK(asset, spender, userAddress),
+    queryFn: () => fetchAllowance(asset!, spender!, userAddress!, config),
+    enabled: Boolean(asset) && Boolean(spender) && Boolean(userAddress),
+    ...queryConfig.sensitiveDataQueryConfig,
+  });
+
+  return {
+    ...rest,
+    data,
+    queryKey: HookFetchAssetAllowanceQK(asset, spender, userAddress),
+  };
+};

package/src/hooks/{useHandleTransactionMutation.ts → useHandleTransactionMutationX.ts}

@@ -1,10 +1,10 @@
 import { waitForTransactionReceipt } from "wagmi/actions";
-import { useInvalidateQueries } from "./useInvalidateQueries";
 import { useConfig } from "wagmi";
 import { QueryKey } from "@tanstack/query-core";
 import { Address } from "viem";
 import { useState } from "react";
-import { getParsedError } from "../utils/errorParser";
+import { getParsedErrorX } from "../utils/errorParserX.js";
+import { useInvalidateQueries } from "./useInvalidateQueries.js";
 
 export type WriteExtendedAsyncParams = {
   onSuccess?: (txHash: Address) => void;
@@ -20,7 +20,7 @@ export type WriteExtendedAsyncParams = {
  *
  * @returns {Function} A shared `onSettled` callback for transaction mutations.
  */
-export function useHandleTransactionMutation({
+export function useHandleTransactionMutationX({
   settings,
 }: {
   settings?: WriteExtendedAsyncParams;
@@ -74,7 +74,7 @@ export function useHandleTransactionMutation({
       // 6. return result
       return txHash;
     } catch (error) {
-      const parsedError = getParsedError(error);
+      const parsedError = getParsedErrorX(error);
 
       if (!settings?.disableLogging) {
         // 1. log error

package/src/hooks/{useSendTransactionExtended.ts → useSendTransactionX.ts}

@@ -1,21 +1,15 @@
-import { Hash } from "viem";
 import { useSendTransaction } from "wagmi";
-import { QueryKey } from "@tanstack/query-core";
-import { useHandleTransactionMutation } from "./useHandleTransactionMutation";
-
-export type SeamlessSendAsyncParams = {
-  onSuccess?: (txHash: Hash) => void;
-  onError?: (e: any) => void;
-  onSettled?: () => void;
-  queriesToInvalidate?: (QueryKey | undefined)[];
-};
+import {
+  useHandleTransactionMutationX,
+  WriteExtendedAsyncParams,
+} from "./useHandleTransactionMutationX.js";
 
 /**
  * Custom hook for sending a transaction using Wagmi.
  *
  * This hook provides functionality for sending a transaction using Wagmi, handling the asynchronous nature of the operation, waiting for the transaction receipt, and error handling.
  *
- * @param {SeamlessWriteAsyncParams} [settings] - Optional settings for the write operation.
+ * @param {WriteExtendedAsyncParams} [settings] - Optional settings for the write operation.
  * @param {boolean} [settings.disableWaitingForReceipt] - Disables waiting for the transaction receipt.
  * @param {boolean} [settings.disableLogging] - Disables logging the result of the transaction.
  * @param {Function} [settings.onSuccess] - Callback function to be called on successful transaction.
@@ -26,11 +20,39 @@ export type SeamlessSendAsyncParams = {
  * - {boolean} isPending - Indicates whether the transaction is pending.
  * - {string|undefined} errorMessage - The error message, if an error occurred during the transaction.
  * - {Function} sendTransactionAsync - Function to trigger the send transaction mutation.
+
+ * @example
+ * // In your component:
+ * function MyTransactionComponent() {
+ *   const { sendTransactionAsync, isPending, errorMessage } = useSendTransactionX({
+ *     onSuccess: (txHash) => console.log("Transaction successful:", txHash),
+ *     onError: (error) => console.error("Transaction error:", error),
+ *     queriesToInvalidate: [["userBalance"], ["userActivity"]],
+ *   });
+ *
+ *   const handleSend = async () => {
+ *     try {
+ *       const txHash = await sendTransactionAsync({ transaction params here.. });
+ *       console.log("Received txHash:", txHash);
+ *     } catch (err) {
+ *       console.error("Failed sending transaction:", err);`
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={handleSend} disabled={isPending}>
+ *         {isPending ? "Processing..." : "Send Transaction"}
+ *       </button>
+ *       {errorMessage && <p>Error: {errorMessage}</p>}
+ *     </div>
+ *   );
+ * }
  */
 
-export function useSendTransactionExtended(settings?: SeamlessSendAsyncParams) {
+export function useSendTransactionX(settings?: WriteExtendedAsyncParams) {
   const { isPending, errorMessage, onMutate, onSettled } =
-    useHandleTransactionMutation({
+    useHandleTransactionMutationX({
       settings,
     });
 

package/src/hooks/useTokenX.ts

@@ -0,0 +1,65 @@
+import { useQueryClient, useQuery } from "@tanstack/react-query";
+import { Address } from "viem";
+import { useConfig } from "wagmi";
+import { fetchTokenX } from "../fetch-functions/fetchTokenX.js";
+
+/**
+ * Returns a query key for fetching token data.
+ *
+ * @param {Address | undefined} asset - The token address.
+ * @returns {Array} A unique query key for the token fetch.
+ *
+ * @example
+ * const queryKey = HookFetchTokenQK("0x123...");
+ */
+export const HookFetchTokenQK = (asset?: Address): any[] => [
+  "HookTokenWagmiExtended",
+  asset,
+];
+
+/**
+ * Custom hook for fetching token metadata using extended Wagmi functionality.
+ *
+ * This hook leverages React Query for data fetching and caching.
+ * It retrieves token metadata (such as symbol, decimals, name, etc.) for a given token address.
+ *
+ * @param {Address} [asset] - The token address.
+ * @returns {Object} An object with the following properties:
+ *   - `data`: The token data (or undefined if not loaded).
+ *   - `isLoading`: Boolean indicating if the data is loading.
+ *   - `error`: Any error encountered during the fetch.
+ *   - `queryKey`: The unique key used for the query.
+ *
+ * @example
+ * // In your component:
+ * function MyTokenComponent() {
+ *   const { data, isLoading, error, queryKey } = useTokenX("0x123456...");
+ *
+ *   if (isLoading) return <div>Loading token data...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       <p>Token Symbol: {data.symbol}</p>
+ *       <p>Decimals: {data.decimals}</p>
+ *       <p>Name: {data.name}</p>
+ *     </div>
+ *   );
+ * }
+ */
+export const useTokenX = (asset?: Address) => {
+  const queryClient = useQueryClient();
+  const config = useConfig();
+
+  const { data, ...rest } = useQuery({
+    queryKey: HookFetchTokenQK(asset),
+    queryFn: () => fetchTokenX(asset!, queryClient, config),
+    enabled: Boolean(asset),
+  });
+
+  return {
+    ...rest,
+    data,
+    queryKey: HookFetchTokenQK(asset),
+  };
+};