thirdweb 5.102.7-nightly-9f6c1a4820e37428dec6427cf77a12ab463f119d-20250616000412 → 5.103.0

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

@@ -0,0 +1,172 @@
+import { describe, expect, it } from "vitest";
+import { ApiError } from "../../../bridge/types/Errors.js";
+import { useBridgeError } from "./useBridgeError.js";
+
+describe("useBridgeError", () => {
+  it("should handle null error", () => {
+    const result = useBridgeError({ error: null });
+
+    expect(result).toEqual({
+      mappedError: null,
+      isRetryable: false,
+      userMessage: "",
+      errorCode: null,
+      statusCode: null,
+      isClientError: false,
+      isServerError: false,
+    });
+  });
+
+  it("should handle undefined error", () => {
+    const result = useBridgeError({ error: undefined });
+
+    expect(result).toEqual({
+      mappedError: null,
+      isRetryable: false,
+      userMessage: "",
+      errorCode: null,
+      statusCode: null,
+      isClientError: false,
+      isServerError: false,
+    });
+  });
+
+  it("should process ApiError correctly", () => {
+    const apiError = new ApiError({
+      code: "INVALID_INPUT",
+      message: "Invalid parameters provided",
+      statusCode: 400,
+    });
+
+    const result = useBridgeError({ error: apiError });
+
+    expect(result.mappedError).toBeInstanceOf(ApiError);
+    expect(result.errorCode).toBe("INVALID_INPUT");
+    expect(result.statusCode).toBe(400);
+    expect(result.isClientError).toBe(true);
+    expect(result.isServerError).toBe(false);
+    expect(result.isRetryable).toBe(false); // INVALID_INPUT is not retryable
+    expect(result.userMessage).toBe(
+      "Invalid input provided. Please check your parameters and try again.",
+    );
+  });
+
+  it("should convert generic Error to ApiError", () => {
+    const genericError = new Error("Network connection failed");
+
+    const result = useBridgeError({ error: genericError });
+
+    expect(result.mappedError).toBeInstanceOf(ApiError);
+    expect(result.errorCode).toBe("UNKNOWN_ERROR");
+    expect(result.statusCode).toBe(500);
+    expect(result.isClientError).toBe(false);
+    expect(result.isServerError).toBe(true);
+    expect(result.isRetryable).toBe(true);
+    expect(result.userMessage).toBe(
+      "An unexpected error occurred. Please try again.",
+    );
+  });
+
+  it("should identify server errors correctly", () => {
+    const serverError = new ApiError({
+      code: "INTERNAL_SERVER_ERROR",
+      message: "Server error",
+      statusCode: 500,
+    });
+
+    const result = useBridgeError({ error: serverError });
+
+    expect(result.statusCode).toBe(500);
+    expect(result.isClientError).toBe(false);
+    expect(result.isServerError).toBe(true);
+    expect(result.isRetryable).toBe(true); // INTERNAL_SERVER_ERROR is retryable
+    expect(result.userMessage).toBe(
+      "A temporary error occurred. Please try again in a moment.",
+    );
+  });
+
+  it("should provide user-friendly messages for known error codes", () => {
+    // Test INVALID_INPUT
+    const invalidInputError = new ApiError({
+      code: "INVALID_INPUT",
+      message: "Technical error message",
+      statusCode: 400,
+    });
+    const invalidInputResult = useBridgeError({ error: invalidInputError });
+    expect(invalidInputResult.userMessage).toBe(
+      "Invalid input provided. Please check your parameters and try again.",
+    );
+
+    // Test INTERNAL_SERVER_ERROR
+    const serverError = new ApiError({
+      code: "INTERNAL_SERVER_ERROR",
+      message: "Technical error message",
+      statusCode: 500,
+    });
+    const serverResult = useBridgeError({ error: serverError });
+    expect(serverResult.userMessage).toBe(
+      "A temporary error occurred. Please try again in a moment.",
+    );
+  });
+
+  it("should use original error message for unknown error codes", () => {
+    const unknownError = new ApiError({
+      code: "UNKNOWN_ERROR",
+      message: "Custom error message",
+      statusCode: 418,
+    });
+
+    const result = useBridgeError({ error: unknownError });
+
+    expect(result.userMessage).toBe(
+      "An unexpected error occurred. Please try again.",
+    );
+    expect(result.errorCode).toBe("UNKNOWN_ERROR");
+  });
+
+  it("should detect client vs server errors correctly", () => {
+    // Client error (4xx)
+    const clientError = new ApiError({
+      code: "INVALID_INPUT",
+      message: "Bad request",
+      statusCode: 400,
+    });
+
+    const clientResult = useBridgeError({ error: clientError });
+    expect(clientResult.isClientError).toBe(true);
+    expect(clientResult.isServerError).toBe(false);
+
+    // Server error (5xx)
+    const serverError = new ApiError({
+      code: "INTERNAL_SERVER_ERROR",
+      message: "Internal error",
+      statusCode: 503,
+    });
+
+    const serverResult = useBridgeError({ error: serverError });
+    expect(serverResult.isClientError).toBe(false);
+    expect(serverResult.isServerError).toBe(true);
+
+    // No status code
+    const noStatusError = new ApiError({
+      code: "UNKNOWN_ERROR",
+      message: "Unknown error",
+      statusCode: 500,
+    });
+
+    const noStatusResult = useBridgeError({ error: noStatusError });
+    expect(noStatusResult.isClientError).toBe(false);
+    expect(noStatusResult.isServerError).toBe(true); // 500 is a server error
+  });
+
+  it("should handle Error without message", () => {
+    const errorWithoutMessage = new Error();
+
+    const result = useBridgeError({ error: errorWithoutMessage });
+
+    expect(result.userMessage).toBe(
+      "An unexpected error occurred. Please try again.",
+    );
+    expect(result.errorCode).toBe("UNKNOWN_ERROR");
+  });
+});

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,
+  });
+}