thirdweb 5.102.7-nightly-3f747601135809eedf86a150752f4b5f12c99776-20250617000426 → 5.103.1-nightly-bb09e20bcb1662c088bf8b61486df7d0d92da8d0-20250618000421

package/src/react/core/hooks/useBridgeError.ts

@@ -0,0 +1,149 @@
+import { ApiError } from "../../../bridge/types/Errors.js";
+import { isRetryable, mapBridgeError } from "../errors/mapBridgeError.js";
+
+/**
+ * Parameters for the useBridgeError hook
+ */
+interface UseBridgeErrorParams {
+  /**
+   * The error to process. Can be an ApiError or generic Error.
+   */
+  error: Error | ApiError | null | undefined;
+}
+
+/**
+ * Result returned by the useBridgeError hook
+ */
+interface UseBridgeErrorResult {
+  /**
+   * The mapped/normalized error, null if no error provided
+   */
+  mappedError: ApiError | null;
+
+  /**
+   * Whether this error can be retried
+   */
+  isRetryable: boolean;
+
+  /**
+   * User-friendly error message
+   */
+  userMessage: string;
+
+  /**
+   * Technical error code for debugging
+   */
+  errorCode: string | null;
+
+  /**
+   * HTTP status code if available
+   */
+  statusCode: number | null;
+
+  /**
+   * Whether this is a client-side error (4xx)
+   */
+  isClientError: boolean;
+
+  /**
+   * Whether this is a server-side error (5xx)
+   */
+  isServerError: boolean;
+}
+
+/**
+ * Hook that processes bridge errors using mapBridgeError and isRetryable
+ *
+ * @param params - Parameters containing the error to process
+ * @returns Processed error information with retry logic and user-friendly messages
+ *
+ * @example
+ * ```tsx
+ * const { data, error } = useBridgeRoutes({ client, originChainId: 1 });
+ * const {
+ *   mappedError,
+ *   isRetryable,
+ *   userMessage,
+ *   isClientError
+ * } = useBridgeError({ error });
+ *
+ * if (error) {
+ *   return (
+ *     <div>
+ *       <p>{userMessage}</p>
+ *       {isRetryable && <button onClick={retry}>Try Again</button>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useBridgeError(
+  params: UseBridgeErrorParams,
+): UseBridgeErrorResult {
+  const { error } = params;
+
+  // No error case
+  if (!error) {
+    return {
+      mappedError: null,
+      isRetryable: false,
+      userMessage: "",
+      errorCode: null,
+      statusCode: null,
+      isClientError: false,
+      isServerError: false,
+    };
+  }
+
+  // Convert to ApiError if it's not already
+  let apiError: ApiError;
+  if (error instanceof ApiError) {
+    apiError = mapBridgeError(error);
+  } else {
+    // Create ApiError from generic Error
+    apiError = new ApiError({
+      code: "UNKNOWN_ERROR",
+      message: error.message || "An unknown error occurred",
+      statusCode: 500, // Default for generic errors
+    });
+  }
+
+  const statusCode = apiError.statusCode || null;
+  const isClientError =
+    statusCode !== null && statusCode >= 400 && statusCode < 500;
+  const isServerError = statusCode !== null && statusCode >= 500;
+
+  // Generate user-friendly message based on error code
+  const userMessage = getUserFriendlyMessage(apiError);
+
+  return {
+    mappedError: apiError,
+    isRetryable: isRetryable(apiError.code),
+    userMessage,
+    errorCode: apiError.code,
+    statusCode,
+    isClientError,
+    isServerError,
+  };
+}
+
+/**
+ * Converts technical error codes to user-friendly messages
+ */
+function getUserFriendlyMessage(error: ApiError): string {
+  switch (error.code) {
+    case "INVALID_INPUT":
+      return "Invalid input provided. Please check your parameters and try again.";
+    case "ROUTE_NOT_FOUND":
+      return "No route found for this transaction. Please try a different token pair or amount.";
+    case "AMOUNT_TOO_LOW":
+      return "The amount is too low for this transaction. Please increase the amount.";
+    case "AMOUNT_TOO_HIGH":
+      return "The amount is too high for this transaction. Please decrease the amount.";
+    case "INTERNAL_SERVER_ERROR":
+      return "A temporary error occurred. Please try again in a moment.";
+    default:
+      // Fallback to the original error message if available
+      return error.message || "An unexpected error occurred. Please try again.";
+  }
+}

package/src/react/core/hooks/useBridgePrepare.test.ts

@@ -0,0 +1,161 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ThirdwebClient } from "../../../client/client.js";
+import type {
+  BridgePrepareRequest,
+  UseBridgePrepareParams,
+} from "./useBridgePrepare.js";
+
+// Mock client
+const mockClient = { clientId: "test" } as ThirdwebClient;
+
+describe("useBridgePrepare", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should have correct type structure for buy prepare request", () => {
+    const buyRequest: BridgePrepareRequest = {
+      type: "buy",
+      client: mockClient,
+      originChainId: 1,
+      originTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+      destinationChainId: 137,
+      destinationTokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+      amount: 1000000n,
+      sender: "0x1234567890123456789012345678901234567890",
+      receiver: "0x1234567890123456789012345678901234567890",
+    };
+
+    expect(buyRequest.type).toBe("buy");
+    expect(buyRequest.amount).toBe(1000000n);
+    expect(buyRequest.client).toBe(mockClient);
+  });
+
+  it("should have correct type structure for transfer prepare request", () => {
+    const transferRequest: BridgePrepareRequest = {
+      type: "transfer",
+      client: mockClient,
+      chainId: 1,
+      tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+      amount: 1000000n,
+      sender: "0x1234567890123456789012345678901234567890",
+      receiver: "0x1234567890123456789012345678901234567890",
+    };
+
+    expect(transferRequest.type).toBe("transfer");
+    expect(transferRequest.amount).toBe(1000000n);
+    expect(transferRequest.client).toBe(mockClient);
+  });
+
+  it("should have correct type structure for sell prepare request", () => {
+    const sellRequest: BridgePrepareRequest = {
+      type: "sell",
+      client: mockClient,
+      originChainId: 1,
+      originTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+      destinationChainId: 137,
+      destinationTokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+      amount: 1000000n,
+      sender: "0x1234567890123456789012345678901234567890",
+      receiver: "0x1234567890123456789012345678901234567890",
+    };
+
+    expect(sellRequest.type).toBe("sell");
+    expect(sellRequest.amount).toBe(1000000n);
+    expect(sellRequest.client).toBe(mockClient);
+  });
+
+  it("should have correct type structure for onramp prepare request", () => {
+    const onrampRequest: BridgePrepareRequest = {
+      type: "onramp",
+      client: mockClient,
+      onramp: "stripe",
+      chainId: 137,
+      tokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+      receiver: "0x1234567890123456789012345678901234567890",
+      amount: 1000000n,
+    };
+
+    expect(onrampRequest.type).toBe("onramp");
+    expect(onrampRequest.amount).toBe(1000000n);
+    expect(onrampRequest.client).toBe(mockClient);
+  });
+
+  it("should handle UseBridgePrepareParams with enabled option", () => {
+    const params: UseBridgePrepareParams = {
+      type: "buy",
+      client: mockClient,
+      originChainId: 1,
+      originTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+      destinationChainId: 137,
+      destinationTokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+      amount: 1000000n,
+      sender: "0x1234567890123456789012345678901234567890",
+      receiver: "0x1234567890123456789012345678901234567890",
+      enabled: false,
+    };
+
+    expect(params.enabled).toBe(false);
+    expect(params.type).toBe("buy");
+  });
+
+  it("should have optional enabled parameter", () => {
+    const paramsWithoutEnabled: UseBridgePrepareParams = {
+      type: "transfer",
+      client: mockClient,
+      chainId: 1,
+      tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+      amount: 1000000n,
+      sender: "0x1234567890123456789012345678901234567890",
+      receiver: "0x1234567890123456789012345678901234567890",
+    };
+
+    expect(paramsWithoutEnabled.enabled).toBeUndefined(); // Should be optional
+    expect(paramsWithoutEnabled.type).toBe("transfer");
+  });
+
+  it("should correctly discriminate between different prepare request types", () => {
+    const buyRequest: BridgePrepareRequest = {
+      type: "buy",
+      client: mockClient,
+      originChainId: 1,
+      originTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+      destinationChainId: 137,
+      destinationTokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+      amount: 1000000n,
+      sender: "0x1234567890123456789012345678901234567890",
+      receiver: "0x1234567890123456789012345678901234567890",
+    };
+
+    // Type narrowing should work
+    if (buyRequest.type === "buy") {
+      expect(buyRequest.sender).toBe(
+        "0x1234567890123456789012345678901234567890",
+      );
+      expect(buyRequest.receiver).toBe(
+        "0x1234567890123456789012345678901234567890",
+      );
+    }
+
+    const onrampRequest: BridgePrepareRequest = {
+      type: "onramp",
+      client: mockClient,
+      onramp: "stripe",
+      chainId: 137,
+      tokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+      receiver: "0x1234567890123456789012345678901234567890",
+      amount: 1000000n,
+    };
+
+    // Type narrowing should work for onramp
+    if (onrampRequest.type === "onramp") {
+      expect(onrampRequest.receiver).toBe(
+        "0x1234567890123456789012345678901234567890",
+      );
+      expect(onrampRequest.tokenAddress).toBe(
+        "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+      );
+      expect(onrampRequest.onramp).toBe("stripe");
+    }
+  });
+});

package/src/react/core/hooks/useBridgePrepare.ts

@@ -0,0 +1,133 @@
+import { useQuery } from "@tanstack/react-query";
+import type { prepare as BuyPrepare } from "../../../bridge/Buy.js";
+import type { prepare as OnrampPrepare } from "../../../bridge/Onramp.js";
+import type { prepare as SellPrepare } from "../../../bridge/Sell.js";
+import type { prepare as TransferPrepare } from "../../../bridge/Transfer.js";
+import * as Bridge from "../../../bridge/index.js";
+import { ApiError } from "../../../bridge/types/Errors.js";
+import { stringify } from "../../../utils/json.js";
+import { mapBridgeError } from "../errors/mapBridgeError.js";
+
+/**
+ * Union type for different Bridge prepare request types
+ */
+export type BridgePrepareRequest =
+  | ({ type: "buy" } & BuyPrepare.Options)
+  | ({ type: "sell" } & SellPrepare.Options)
+  | ({ type: "transfer" } & TransferPrepare.Options)
+  | ({ type: "onramp" } & OnrampPrepare.Options);
+
+/**
+ * Union type for different Bridge prepare result types
+ */
+export type BridgePrepareResult =
+  | ({ type: "buy" } & BuyPrepare.Result)
+  | ({ type: "sell" } & SellPrepare.Result)
+  | ({ type: "transfer" } & TransferPrepare.Result)
+  | ({ type: "onramp" } & OnrampPrepare.Result);
+
+/**
+ * Parameters for the useBridgePrepare hook
+ */
+export type UseBridgePrepareParams = BridgePrepareRequest & {
+  /**
+   * Whether to enable the query. Useful for conditional fetching.
+   * @default true
+   */
+  enabled?: boolean;
+};
+
+/**
+ * Hook that prepares bridge transactions with caching and retry logic
+ *
+ * @param params - Parameters for preparing bridge transactions including type and specific options
+ * @returns React Query result with prepared transaction data, loading state, and error handling
+ *
+ * @example
+ * ```tsx
+ * // Buy preparation
+ * const { data: preparedBuy, isLoading, error } = useBridgePrepare({
+ *   type: "buy",
+ *   client: thirdwebClient,
+ *   originChainId: 1,
+ *   originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+ *   destinationChainId: 137,
+ *   destinationTokenAddress: "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619",
+ *   amount: parseEther("1"),
+ *   sender: "0x...",
+ *   receiver: "0x..."
+ * });
+ *
+ * // Transfer preparation
+ * const { data: preparedTransfer } = useBridgePrepare({
+ *   type: "transfer",
+ *   client: thirdwebClient,
+ *   originChainId: 1,
+ *   originTokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ *   destinationChainId: 137,
+ *   destinationTokenAddress: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+ *   amount: 1000000n,
+ *   sender: "0x...",
+ *   receiver: "0x..."
+ * });
+ * ```
+ */
+export function useBridgePrepare(params: UseBridgePrepareParams) {
+  const { enabled = true, type, ...prepareParams } = params;
+
+  return useQuery({
+    queryKey: ["bridge-prepare", type, stringify(prepareParams)],
+    queryFn: async (): Promise<BridgePrepareResult> => {
+      switch (type) {
+        case "buy": {
+          const result = await Bridge.Buy.prepare(
+            prepareParams as BuyPrepare.Options,
+          );
+          return { type: "buy", ...result };
+        }
+        case "sell": {
+          const result = await Bridge.Sell.prepare(
+            prepareParams as SellPrepare.Options,
+          );
+          return { type: "sell", ...result };
+        }
+        case "transfer": {
+          const result = await Bridge.Transfer.prepare(
+            prepareParams as TransferPrepare.Options,
+          );
+          return { type: "transfer", ...result };
+        }
+        case "onramp": {
+          const result = await Bridge.Onramp.prepare(
+            prepareParams as OnrampPrepare.Options,
+          );
+          return { type: "onramp", ...result };
+        }
+        default:
+          throw new Error(`Unsupported bridge prepare type: ${type}`);
+      }
+    },
+    enabled: enabled && !!prepareParams.client,
+    staleTime: 2 * 60 * 1000, // 2 minutes - prepared quotes have shorter validity
+    gcTime: 5 * 60 * 1000, // 5 minutes garbage collection
+    retry: (failureCount, error) => {
+      // Handle both ApiError and generic Error instances
+      if (error instanceof ApiError) {
+        const bridgeError = mapBridgeError(error);
+
+        // Don't retry on client-side errors (4xx)
+        if (
+          bridgeError.statusCode &&
+          bridgeError.statusCode >= 400 &&
+          bridgeError.statusCode < 500
+        ) {
+          return false;
+        }
+      }
+
+      // Retry up to 2 times for prepared quotes (they're more time-sensitive)
+      return failureCount < 2;
+    },
+    retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 10000), // Exponential backoff, max 10s
+  });
+}

package/src/react/core/hooks/useBridgeQuote.ts

@@ -0,0 +1,67 @@
+"use client";
+import { useQuery } from "@tanstack/react-query";
+import * as Buy from "../../../bridge/Buy.js";
+import * as Transfer from "../../../bridge/Transfer.js";
+import type { Token } from "../../../bridge/types/Token.js";
+import type { ThirdwebClient } from "../../../client/client.js";
+import { checksumAddress } from "../../../utils/address.js";
+
+interface UseBridgeQuoteParams {
+  originToken: Token;
+  destinationToken: Token;
+  destinationAmount: bigint;
+  client: ThirdwebClient;
+  enabled?: boolean;
+}
+
+export function useBridgeQuote({
+  originToken,
+  destinationToken,
+  destinationAmount,
+  client,
+  enabled = true,
+}: UseBridgeQuoteParams) {
+  return useQuery({
+    queryKey: [
+      "bridge-quote",
+      originToken.chainId,
+      originToken.address,
+      destinationToken.chainId,
+      destinationToken.address,
+      destinationAmount.toString(),
+    ],
+    queryFn: async () => {
+      // if ssame token and chain, use transfer
+      if (
+        checksumAddress(originToken.address) ===
+          checksumAddress(destinationToken.address) &&
+        originToken.chainId === destinationToken.chainId
+      ) {
+        const transfer = await Transfer.prepare({
+          client,
+          chainId: originToken.chainId,
+          tokenAddress: originToken.address,
+          sender: originToken.address,
+          receiver: destinationToken.address,
+          amount: destinationAmount,
+        });
+        return transfer;
+      }
+      const quote = await Buy.quote({
+        originChainId: originToken.chainId,
+        originTokenAddress: originToken.address,
+        destinationChainId: destinationToken.chainId,
+        destinationTokenAddress: destinationToken.address,
+        amount: destinationAmount,
+        client,
+      });
+
+      return quote;
+    },
+    enabled:
+      enabled && !!originToken && !!destinationToken && !!destinationAmount,
+    staleTime: 30000, // 30 seconds
+    refetchInterval: 60000, // 1 minute
+    retry: 3,
+  });
+}

package/src/react/core/hooks/useBridgeRoutes.test.ts

@@ -0,0 +1,137 @@
+import {
+  type MockedFunction,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+import { routes } from "../../../bridge/Routes.js";
+import { ApiError } from "../../../bridge/types/Errors.js";
+import type { Route } from "../../../bridge/types/Route.js";
+import type { ThirdwebClient } from "../../../client/client.js";
+import type { UseBridgeRoutesParams } from "./useBridgeRoutes.js";
+
+// Mock the Bridge routes function
+vi.mock("../../../bridge/Routes.js", () => ({
+  routes: vi.fn(),
+}));
+
+const mockRoutes = routes as MockedFunction<typeof routes>;
+
+// Mock client
+const mockClient = { clientId: "test" } as ThirdwebClient;
+
+// Mock route data
+const mockRouteData: Route[] = [
+  {
+    originToken: {
+      chainId: 1,
+      address: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+      symbol: "ETH",
+      name: "Ethereum",
+      decimals: 18,
+      priceUsd: 2000.0,
+    },
+    destinationToken: {
+      chainId: 137,
+      address: "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619",
+      symbol: "WETH",
+      name: "Wrapped Ethereum",
+      decimals: 18,
+      priceUsd: 2000.0,
+    },
+  },
+];
+
+describe("useBridgeRoutes", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should export correct hook parameters type", () => {
+    // Type-only test to verify UseBridgeRoutesParams interface
+    const params: UseBridgeRoutesParams = {
+      client: mockClient,
+      originChainId: 1,
+      destinationChainId: 137,
+      enabled: true,
+    };
+
+    expect(params).toBeDefined();
+    expect(params.client).toBe(mockClient);
+    expect(params.originChainId).toBe(1);
+    expect(params.destinationChainId).toBe(137);
+    expect(params.enabled).toBe(true);
+  });
+
+  it("should handle different parameter combinations", () => {
+    const fullParams: UseBridgeRoutesParams = {
+      client: mockClient,
+      originChainId: 1,
+      originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
+      destinationChainId: 137,
+      destinationTokenAddress: "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619",
+      maxSteps: 3,
+      sortBy: "popularity",
+      limit: 10,
+      offset: 0,
+      enabled: false,
+    };
+
+    expect(fullParams).toBeDefined();
+    expect(fullParams.sortBy).toBe("popularity");
+    expect(fullParams.maxSteps).toBe(3);
+    expect(fullParams.limit).toBe(10);
+    expect(fullParams.offset).toBe(0);
+  });
+
+  it("should have optional enabled parameter defaulting to true", () => {
+    const paramsWithoutEnabled: UseBridgeRoutesParams = {
+      client: mockClient,
+      originChainId: 1,
+      destinationChainId: 137,
+    };
+
+    expect(paramsWithoutEnabled.enabled).toBeUndefined(); // Should be optional
+  });
+
+  it("should validate that Bridge.routes would be called with correct parameters", async () => {
+    const testParams = {
+      client: mockClient,
+      originChainId: 1,
+      destinationChainId: 137,
+      originTokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE" as const,
+    };
+
+    // Mock the routes function to return our test data
+    mockRoutes.mockResolvedValue(mockRouteData);
+
+    // Directly call the routes function to verify it works with our parameters
+    const result = await routes(testParams);
+
+    expect(mockRoutes).toHaveBeenCalledWith(testParams);
+    expect(result).toEqual(mockRouteData);
+  });
+
+  it("should handle API errors properly", async () => {
+    const apiError = new ApiError({
+      code: "INVALID_INPUT",
+      message: "Invalid parameters",
+      statusCode: 400,
+    });
+
+    mockRoutes.mockRejectedValue(apiError);
+
+    try {
+      await routes({
+        client: mockClient,
+        originChainId: 1,
+        destinationChainId: 137,
+      });
+    } catch (error) {
+      expect(error).toBe(apiError);
+      expect(error).toBeInstanceOf(ApiError);
+    }
+  });
+});