thirdweb 5.102.7-nightly-3f747601135809eedf86a150752f4b5f12c99776-20250617000426 → 5.103.0

package/src/exports/react.ts

@@ -130,6 +130,22 @@ export type { AutoConnectProps } from "../wallets/connection/types.js";
 // auth
 export type { SiweAuthOptions } from "../react/core/hooks/auth/useSiweAuth.js";
 
+export {
+  BuyWidget,
+  type BuyWidgetProps,
+} from "../react/web/ui/Bridge/BuyWidget.js";
+export {
+  CheckoutWidget,
+  type CheckoutWidgetProps,
+} from "../react/web/ui/Bridge/CheckoutWidget.js";
+export {
+  TransactionWidget,
+  type TransactionWidgetProps,
+} from "../react/web/ui/Bridge/TransactionWidget.js";
+export {
+  useBridgeRoutes,
+  type UseBridgeRoutesParams,
+} from "../react/core/hooks/useBridgeRoutes.js";
 export {
   PayEmbed,
   type PayEmbedProps,

package/src/pay/buyWithFiat/getQuote.ts

@@ -291,9 +291,9 @@ export async function getBuyWithFiatQuote(
       provider?: FiatProvider,
     ): "stripe" | "coinbase" | "transak" => {
       switch (provider) {
-        case "STRIPE":
+        case "stripe":
           return "stripe";
-        case "TRANSAK":
+        case "transak":
           return "transak";
         default: // default to coinbase when undefined or any other value
           return "coinbase";

package/src/pay/convert/cryptoToFiat.ts

@@ -2,7 +2,7 @@ import type { Address } from "abitype";
 import type { Chain } from "../../chains/types.js";
 import type { ThirdwebClient } from "../../client/client.js";
 import { isAddress } from "../../utils/address.js";
-import { getTokenPrice } from "./get-token.js";
+import { getToken } from "./get-token.js";
 import type { SupportedFiatCurrency } from "./type.js";
 
 /**
@@ -73,11 +73,11 @@ export async function convertCryptoToFiat(
       "Invalid fromTokenAddress. Expected a valid EVM contract address",
     );
   }
-  const price = await getTokenPrice(client, fromTokenAddress, chain.id);
-  if (!price) {
+  const token = await getToken(client, fromTokenAddress, chain.id);
+  if (token.priceUsd === 0) {
     throw new Error(
       `Error: Failed to fetch price for token ${fromTokenAddress} on chainId: ${chain.id}`,
     );
   }
-  return { result: price * fromAmount };
+  return { result: token.priceUsd * fromAmount };
 }

package/src/pay/convert/fiatToCrypto.ts

@@ -2,7 +2,7 @@ import type { Address } from "abitype";
 import type { Chain } from "../../chains/types.js";
 import type { ThirdwebClient } from "../../client/client.js";
 import { isAddress } from "../../utils/address.js";
-import { getTokenPrice } from "./get-token.js";
+import { getToken } from "./get-token.js";
 import type { SupportedFiatCurrency } from "./type.js";
 
 /**
@@ -72,11 +72,11 @@ export async function convertFiatToCrypto(
   if (!isAddress(to)) {
     throw new Error("Invalid `to`. Expected a valid EVM contract address");
   }
-  const price = await getTokenPrice(client, to, chain.id);
-  if (!price || price === 0) {
+  const token = await getToken(client, to, chain.id);
+  if (!token || token.priceUsd === 0) {
     throw new Error(
       `Error: Failed to fetch price for token ${to} on chainId: ${chain.id}`,
     );
   }
-  return { result: fromAmount / price };
+  return { result: fromAmount / token.priceUsd };
 }

package/src/pay/convert/get-token.ts

@@ -1,12 +1,13 @@
-import { tokens } from "../../bridge/Token.js";
+import { add, tokens } from "../../bridge/Token.js";
+import type { Token } from "../../bridge/types/Token.js";
 import type { ThirdwebClient } from "../../client/client.js";
 import { withCache } from "../../utils/promise/withCache.js";
 
-export async function getTokenPrice(
+export async function getToken(
   client: ThirdwebClient,
   tokenAddress: string,
   chainId: number,
-) {
+): Promise<Token> {
   return withCache(
     async () => {
       const result = await tokens({
@@ -14,7 +15,19 @@ export async function getTokenPrice(
         tokenAddress,
         chainId,
       });
-      return result[0]?.priceUsd;
+      const token = result[0];
+      if (!token) {
+        // Attempt to add the token
+        const tokenResult = await add({
+          client,
+          chainId,
+          tokenAddress,
+        }).catch(() => {
+          throw new Error("Token not supported");
+        });
+        return tokenResult;
+      }
+      return token;
     },
     {
       cacheKey: `get-token-price-${tokenAddress}-${chainId}`,

package/src/pay/utils/commonTypes.ts

@@ -19,4 +19,4 @@ export type PayOnChainTransactionDetails = {
 
 export type FiatProvider = (typeof FiatProviders)[number];
 
-export const FiatProviders = ["COINBASE", "STRIPE", "TRANSAK"] as const;
+export const FiatProviders = ["coinbase", "stripe", "transak"] as const;

package/src/react/components.md

@@ -0,0 +1,134 @@
+# Web UI Components Catalog
+
+This document catalogs the UI components found within `packages/thirdweb/src/react/web/ui`.
+
+## Core Components (`packages/thirdweb/src/react/web/ui/components`)
+
+| Component           | Occurrences |
+| ------------------- | ----------- |
+| Container           | 100+        |
+| Text                | 93          |
+| Spacer              | 85          |
+| Button              | 58          |
+| Skeleton            | 40          |
+| ModalHeader         | 40          |
+| Spinner             | 31          |
+| Img                 | 31          |
+| Line                | 28          |
+| ChainIcon           | 19          |
+| TokenIcon           | 16          |
+| Input               | 11          |
+| SwitchNetworkButton | 10          |
+| WalletImage         | 11          |
+| ToolTip             | 6           |
+| Drawer              | 5           |
+| QRCode              | 5           |
+| CopyIcon            | 4           |
+| ChainActiveDot      | 3           |
+| Label               | 3           |
+| ModalTitle          | 3           |
+| TextDivider         | 3           |
+| DynamicHeight       | 3           |
+| StepBar             | 2           |
+| IconContainer       | 2           |
+| OTPInput            | 2           |
+| ChainName           | 1           |
+| BackButton          | 1           |
+| IconButton          | 1           |
+| ButtonLink          | 1           |
+| Overlay             | 1           |
+| Tabs                | 1           |
+| FadeIn              | 0           |
+| InputContainer      | 0           |
+
+## Prebuilt Components (`packages/thirdweb/src/react/web/ui/prebuilt`)
+
+### NFT
+
+| Component      | Occurrences (internal) |
+| -------------- | ---------------------- |
+| NFTName        | 0                      |
+| NFTMedia       | 0                      |
+| NFTDescription | 0                      |
+| NFTProvider    | 0                      |
+
+### Account
+
+| Component      | Occurrences (internal) |
+| -------------- | ---------------------- |
+| AccountBalance | 6                      |
+| AccountAvatar  | 2                      |
+| AccountBlobbie | 4                      |
+| AccountName    | 2                      |
+| AccountAddress | 4                      |
+
+### Chain
+
+| Component     | Occurrences (internal) |
+| ------------- | ---------------------- |
+| ChainName     | 5                      |
+| ChainIcon     | 7                      |
+| ChainProvider | 2                      |
+
+### Token
+
+| Component     | Occurrences (internal) |
+| ------------- | ---------------------- |
+| TokenName     | 0                      |
+| TokenSymbol   | 12                     |
+| TokenIcon     | 7                      |
+| TokenProvider | 0                      |
+
+### Wallet
+
+| Component  | Occurrences (internal) |
+| ---------- | ---------------------- |
+| WalletName | 0                      |
+| WalletIcon | 0                      |
+
+### Thirdweb
+
+| Component                 | Occurrences (internal) |
+| ------------------------- | ---------------------- |
+| ClaimButton               | 0                      |
+| BuyDirectListingButton    | 0                      |
+| CreateDirectListingButton | 0                      |
+
+## Re-used Components (`packages/thirdweb/src/react/web/ui`)
+
+### Non-Core/Non-Prebuilt Components (ConnectWallet folder analysis)
+
+| Component                      | Occurrences | Source/Type                  |
+| ------------------------------ | ----------- | ---------------------------- |
+| LoadingScreen                  | 19          | Wallets shared component     |
+| Suspense                       | 8           | React built-in               |
+| WalletRow                      | 8           | Buy/swap utility component   |
+| PoweredByThirdweb              | 6           | Custom branding component    |
+| Modal                          | 5           | Core UI component            |
+| WalletUIStatesProvider         | 4           | Wallet state management      |
+| NetworkSelectorContent         | 4           | Network selection component  |
+| PayTokenIcon                   | 3           | Buy screen utility component |
+| FiatValue                      | 3           | Buy/swap utility component   |
+| TOS                            | 3           | Terms of service component   |
+| ErrorState                     | 3           | Error handling component     |
+| AnimatedButton                 | 3           | Animation component          |
+| ConnectModalContent            | 3           | Modal content layout         |
+| AnyWalletConnectUI             | 2           | Wallet connection screen     |
+| SmartConnectUI                 | 2           | Smart wallet connection UI   |
+| WalletEntryButton              | 2           | Wallet selection button      |
+| TokenSelector                  | 2           | Token selection component    |
+| SignatureScreen                | 2           | Wallet signature screen      |
+| WalletSwitcherConnectionScreen | 2           | Wallet switching UI          |
+| ErrorText                      | 2           | Error display component      |
+| SwapSummary                    | 2           | Swap transaction summary     |
+| EstimatedTimeAndFees           | 2           | Transaction info component   |
+
+### Other Re-used Components
+
+| Component | Occurrences |
+| --------- | ----------- |
+| PayEmbed  | 1           |
+| SiteEmbed | 0           |
+| SiteLink  | 0           |
+
+**Note:** Occurrences are based on direct import and usage (e.g., `<ComponentName`). This count excludes test files and documentation examples, counting only internal usage within the src/react/web folder. The analysis focuses on commonly used components that are NOT from the core components or prebuilt folders, revealing key reusable components for state management, error handling, animations, and branding.

package/src/react/core/adapters/.keep

@@ -0,0 +1,2 @@
+# Placeholder file to maintain directory structure
+# This directory will contain dependency inversion interfaces and default implementations 

package/src/react/core/adapters/WindowAdapter.ts

@@ -0,0 +1,13 @@
+/**
+ * WindowAdapter interface for platform-specific window/URL opening functionality.
+ * This allows dependency inversion so core logic doesn't directly depend on platform APIs.
+ */
+export interface WindowAdapter {
+  /**
+   * Opens a URL in a new window/tab or appropriate platform mechanism.
+   *
+   * @param url - The URL to open
+   * @returns Promise that resolves when the operation is initiated
+   */
+  open(url: string, title?: string, options?: string): Promise<void>;
+}

package/src/react/core/errors/.keep

@@ -0,0 +1,2 @@
+# Placeholder file to maintain directory structure
+# This directory will contain error mapping and normalization utilities 

package/src/react/core/errors/mapBridgeError.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { ApiError } from "../../../bridge/types/Errors.js";
+import { isRetryable, mapBridgeError } from "./mapBridgeError.js";
+
+describe("mapBridgeError", () => {
+  it("should return the same error for INVALID_INPUT", () => {
+    const error = new ApiError({
+      code: "INVALID_INPUT",
+      message: "Invalid input provided",
+      statusCode: 400,
+      correlationId: "test-correlation-id",
+    });
+
+    const result = mapBridgeError(error);
+
+    expect(result).toBe(error);
+    expect(result.code).toBe("INVALID_INPUT");
+    expect(result.message).toBe("Invalid input provided");
+    expect(result.statusCode).toBe(400);
+    expect(result.correlationId).toBe("test-correlation-id");
+  });
+
+  it("should return the same error for INTERNAL_SERVER_ERROR", () => {
+    const error = new ApiError({
+      code: "INTERNAL_SERVER_ERROR",
+      message: "Internal server error occurred",
+      statusCode: 500,
+      correlationId: "internal-error-id",
+    });
+
+    const result = mapBridgeError(error);
+
+    expect(result).toBe(error);
+    expect(result.code).toBe("INTERNAL_SERVER_ERROR");
+    expect(result.message).toBe("Internal server error occurred");
+    expect(result.statusCode).toBe(500);
+    expect(result.correlationId).toBe("internal-error-id");
+  });
+
+  it("should return the same error for ROUTE_NOT_FOUND", () => {
+    const error = new ApiError({
+      code: "ROUTE_NOT_FOUND",
+      message: "No route found for the requested parameters",
+      statusCode: 404,
+    });
+
+    const result = mapBridgeError(error);
+
+    expect(result).toBe(error);
+    expect(result.code).toBe("ROUTE_NOT_FOUND");
+    expect(result.message).toBe("No route found for the requested parameters");
+    expect(result.statusCode).toBe(404);
+    expect(result.correlationId).toBeUndefined();
+  });
+
+  it("should return the same error for AMOUNT_TOO_LOW", () => {
+    const error = new ApiError({
+      code: "AMOUNT_TOO_LOW",
+      message: "Amount is below minimum threshold",
+      statusCode: 400,
+      correlationId: "amount-validation-id",
+    });
+
+    const result = mapBridgeError(error);
+
+    expect(result).toBe(error);
+    expect(result.code).toBe("AMOUNT_TOO_LOW");
+    expect(result.message).toBe("Amount is below minimum threshold");
+    expect(result.statusCode).toBe(400);
+    expect(result.correlationId).toBe("amount-validation-id");
+  });
+});
+
+describe("isRetryable", () => {
+  it("should return true for INTERNAL_SERVER_ERROR", () => {
+    expect(isRetryable("INTERNAL_SERVER_ERROR")).toBe(true);
+  });
+
+  it("should return true for UNKNOWN_ERROR", () => {
+    expect(isRetryable("UNKNOWN_ERROR")).toBe(true);
+  });
+
+  it("should return false for INVALID_INPUT", () => {
+    expect(isRetryable("INVALID_INPUT")).toBe(false);
+  });
+
+  it("should return false for ROUTE_NOT_FOUND", () => {
+    expect(isRetryable("ROUTE_NOT_FOUND")).toBe(false);
+  });
+
+  it("should return false for AMOUNT_TOO_LOW", () => {
+    expect(isRetryable("AMOUNT_TOO_LOW")).toBe(false);
+  });
+
+  it("should return false for AMOUNT_TOO_HIGH", () => {
+    expect(isRetryable("AMOUNT_TOO_HIGH")).toBe(false);
+  });
+});

package/src/react/core/errors/mapBridgeError.ts

@@ -0,0 +1,25 @@
+import type { ApiError } from "../../../bridge/types/Errors.js";
+
+/**
+ * Maps raw ApiError instances from the Bridge SDK into UI-friendly domain errors.
+ * Currently returns the same error; will evolve to provide better user-facing messages.
+ *
+ * @param e - The raw ApiError from the Bridge SDK
+ * @returns The mapped ApiError (currently unchanged)
+ */
+export function mapBridgeError(e: ApiError): ApiError {
+  // For now, return the same error
+  // TODO: This will evolve to provide better user-facing error messages
+  return e;
+}
+
+/**
+ * Determines if an error code represents a retryable error condition.
+ *
+ * @param code - The error code from ApiError
+ * @returns true if the error is retryable, false otherwise
+ */
+export function isRetryable(code: ApiError["code"]): boolean {
+  // Treat INTERNAL_SERVER_ERROR & UNKNOWN_ERROR as retryable
+  return code === "INTERNAL_SERVER_ERROR" || code === "UNKNOWN_ERROR";
+}

package/src/react/core/hooks/connection/ConnectButtonProps.ts

@@ -25,40 +25,42 @@ import type {
 } from "../../utils/defaultTokens.js";
 import type { SiweAuthOptions } from "../auth/useSiweAuth.js";
 
-export type PaymentInfo = {
-  /**
-   * The chain to receive the payment on.
-   */
-  chain: Chain;
-  /**
-   * The address of the seller wallet to receive the payment on.
-   */
-  sellerAddress: string;
-  /**
-   * Optional ERC20 token to receive the payment on.
-   * If not provided, the native token will be used.
-   */
-  token?: TokenInfo;
-  /**
-   * For direct transfers, specify who will pay the transfer fee. Can be "sender" or "receiver".
-   */
-  feePayer?: "sender" | "receiver";
-} & (
-  | {
-      /**
-       * The amount of tokens to receive in ETH or tokens.
-       * ex: 0.1 ETH or 100 USDC
-       */
-      amount: string;
-    }
-  | {
-      /**
-       * The amount of tokens to receive in wei.
-       * ex: 1000000000000000000 wei
-       */
-      amountWei: bigint;
-    }
-);
+export type PaymentInfo = Prettify<
+  {
+    /**
+     * The chain to receive the payment on.
+     */
+    chain: Chain;
+    /**
+     * The address of the seller wallet to receive the payment on.
+     */
+    sellerAddress: string;
+    /**
+     * Optional ERC20 token to receive the payment on.
+     * If not provided, the native token will be used.
+     */
+    token?: Partial<TokenInfo> & { address: string };
+    /**
+     * For direct transfers, specify who will pay the transfer fee. Can be "sender" or "receiver".
+     */
+    feePayer?: "sender" | "receiver";
+  } & (
+    | {
+        /**
+         * The amount of tokens to receive in ETH or tokens.
+         * ex: 0.1 ETH or 100 USDC
+         */
+        amount: string;
+      }
+    | {
+        /**
+         * The amount of tokens to receive in wei.
+         * ex: 1000000000000000000 wei
+         */
+        amountWei: bigint;
+      }
+  )
+>;
 
 export type PayUIOptions = Prettify<
   {
@@ -78,7 +80,7 @@ export type PayUIOptions = Prettify<
           testMode?: boolean;
           prefillSource?: {
             chain: Chain;
-            token?: TokenInfo;
+            token?: Partial<TokenInfo> & { address: string };
             allowEdits?: {
               token: boolean;
               chain: boolean;
@@ -115,7 +117,8 @@ export type PayUIOptions = Prettify<
      * Callback to be called when the user successfully completes the purchase.
      */
     onPurchaseSuccess?: (
-      info:
+      // TODO: remove this type from the callback entirely or adapt it from the new format
+      info?:
         | {
             type: "crypto";
             status: BuyWithCryptoStatus;
@@ -135,6 +138,7 @@ export type PayUIOptions = Prettify<
      */
     metadata?: {
       name?: string;
+      description?: string;
       image?: string;
     };
 
@@ -160,13 +164,14 @@ export type FundWalletOptions = {
    */
   prefillBuy?: {
     chain: Chain;
-    token?: TokenInfo;
+    token?: Partial<TokenInfo> & { address: string };
     amount?: string;
     allowEdits?: {
       amount: boolean;
       token: boolean;
       chain: boolean;
     };
+    presetOptions?: [number, number, number];
   };
 };
 

package/src/react/core/hooks/others/useChainQuery.ts

@@ -137,7 +137,7 @@ export function useChainExplorers(chain?: Chain) {
 
 function getQueryOptions(chain?: Chain) {
   return {
-    queryKey: ["chain", chain],
+    queryKey: ["chain", chain?.id],
     enabled: !!chain,
     staleTime: 1000 * 60 * 60, // 1 hour
   } as const;

package/src/react/core/hooks/pay/useBuyWithFiatQuotesForProviders.ts

@@ -0,0 +1,100 @@
+import { type UseQueryOptions, useQueries } from "@tanstack/react-query";
+import { prepare as prepareOnramp } from "../../../../bridge/Onramp.js";
+import type { ThirdwebClient } from "../../../../client/client.js";
+import { getToken } from "../../../../pay/convert/get-token.js";
+import type { Address } from "../../../../utils/address.js";
+import { toUnits } from "../../../../utils/units.js";
+
+/**
+ * @internal
+ */
+type UseBuyWithFiatQuotesForProvidersParams = {
+  /**
+   * A client is the entry point to the thirdweb SDK.
+   */
+  client: ThirdwebClient;
+  /**
+   * The destination chain ID.
+   */
+  chainId: number;
+  /**
+   * The destination token address.
+   */
+  tokenAddress: Address;
+  /**
+   * The address that will receive the tokens.
+   */
+  receiver: Address;
+  /**
+   * The desired token amount in wei.
+   */
+  amount: string;
+  /**
+   * The fiat currency (e.g., "USD"). Defaults to "USD".
+   */
+  currency?: string;
+};
+
+/**
+ * @internal
+ */
+type OnrampQuoteQueryOptions = Omit<
+  UseQueryOptions<Awaited<ReturnType<typeof prepareOnramp>>>,
+  "queryFn" | "queryKey" | "enabled"
+>;
+
+/**
+ * @internal
+ */
+type UseBuyWithFiatQuotesForProvidersResult = {
+  data: Awaited<ReturnType<typeof prepareOnramp>> | undefined;
+  isLoading: boolean;
+  error: Error | null;
+  isError: boolean;
+  isSuccess: boolean;
+}[];
+
+/**
+ * @internal
+ * Hook to get prepared onramp quotes from Coinbase, Stripe, and Transak providers.
+ */
+export function useBuyWithFiatQuotesForProviders(
+  params?: UseBuyWithFiatQuotesForProvidersParams,
+  queryOptions?: OnrampQuoteQueryOptions,
+): UseBuyWithFiatQuotesForProvidersResult {
+  const providers = ["coinbase", "stripe", "transak"] as const;
+
+  const queries = useQueries({
+    queries: providers.map((provider) => ({
+      ...queryOptions,
+      queryKey: ["onramp-prepare", provider, params],
+      queryFn: async () => {
+        if (!params) {
+          throw new Error("No params provided");
+        }
+
+        const token = await getToken(
+          params.client,
+          params.tokenAddress,
+          params.chainId,
+        );
+
+        const amountWei = toUnits(params.amount, token.decimals);
+
+        return prepareOnramp({
+          client: params.client,
+          onramp: provider,
+          chainId: params.chainId,
+          tokenAddress: params.tokenAddress,
+          receiver: params.receiver,
+          amount: amountWei,
+          currency: params.currency || "USD",
+        });
+      },
+      enabled: !!params,
+      retry: false,
+    })),
+  });
+
+  return queries;
+}

package/src/react/core/hooks/transaction/useSendTransaction.ts

@@ -70,7 +70,7 @@ export type SendTransactionPayModalConfig =
        * Callback to be called when the user successfully completes the purchase.
        */
       onPurchaseSuccess?: (
-        info:
+        info?:
           | {
               type: "crypto";
               status: BuyWithCryptoStatus;