0xtrails 0.12.0 → 0.12.2

package/src/widget/hooks/useMeldTransactionHistory.ts

@@ -1,21 +1,20 @@
-import { useState, useCallback, useEffect } from "react"
+import { useMemo } from "react"
 import { useQuery } from "@tanstack/react-query"
 import { useAccount } from "wagmi"
 import { useOnrampClient } from "../../onrampClient.js"
-import { MINUTE_MS, SECOND_MS } from "../../utils/time.js"
-import { logger } from "../../logger.js"
-import { addressEqual, normalizeAddress } from "../../utils/address.js"
+import { SECOND_MS } from "../../utils/time.js"
+import { addressEqual } from "../../utils/address.js"
 import {
   getCurrencySymbol,
   parseCurrencyCode,
   getCountryFlag,
 } from "../../utils.js"
-import { useMeldPaymentMethods } from "../../meld/utils/meld.js"
+import { useMeldPaymentMethods } from "../../query/meld.hooks.js"
+import { meldQueries } from "../../query/meld.queries.js"
 import type {
-  SearchMeldTransactionsRequest,
-  SearchMeldTransactionsResponse,
   MeldTransaction,
-} from "../../onramp-client/trails-onramp.gen.js"
+  MeldPaymentMethod,
+} from "../../query/meld.fetchers.js"
 
 export type MeldTransactionStatus =
   | "PENDING"
@@ -43,7 +42,6 @@ export interface MeldTransactionData {
   transactionHash?: string
   externalSessionId?: string
   externalCustomerId?: string
-  // Additional display data
   countryCode?: string
   exchangeRate?: number
   totalFee?: number
@@ -51,12 +49,10 @@ export interface MeldTransactionData {
   transactionFee?: number
   institutionName?: string
   lowKyc?: boolean
-  // UI enhancement fields
   sourceCurrencySymbol?: string
   destinationCurrencySymbol?: string
   paymentMethodLogo?: string
   currencyFlag?: string
-  // Token info for UI components
   sourceTokenSymbol?: string
   sourceTokenChainId?: number
   sourceTokenAddress?: string
@@ -82,13 +78,10 @@ export interface UseMeldTransactionHistoryReturn {
 
 function parseMeldTransaction(
   transaction: MeldTransaction,
-  paymentMethods?: Array<any>,
+  paymentMethods?: MeldPaymentMethod[],
 ): MeldTransactionData {
-  // Parse the transaction data from the API response
-  // The API currently only defines id, but we expect more fields from the actual response
   const txn = transaction as any
 
-  // Parse source and destination currency information
   const sourceCurrencyCode = txn.sourceCurrencyCode || txn.fiatCurrency
   const destinationCurrencyCode =
     txn.destinationCurrencyCode || txn.cryptoCurrency
@@ -111,7 +104,6 @@ function parseMeldTransaction(
     transactionHash: txn.transactionHash || txn.hash,
     externalSessionId: txn.externalSessionId || txn.sessionId,
     externalCustomerId: txn.externalCustomerId || txn.customerId,
-    // Additional data
     countryCode: txn.countryCode,
     exchangeRate: txn.exchangeRate,
     totalFee: txn.totalFee,
@@ -119,7 +111,6 @@ function parseMeldTransaction(
     transactionFee: txn.transactionFee,
     institutionName: txn.institutionName,
     lowKyc: txn.lowKyc,
-    // UI enhancement fields - we'll populate these
     sourceCurrencySymbol: getCurrencySymbol(sourceToken.symbol),
     destinationCurrencySymbol: getCurrencySymbol(destinationToken.symbol),
     paymentMethodLogo: getPaymentMethodLogo(
@@ -127,24 +118,21 @@ function parseMeldTransaction(
       paymentMethods,
     ),
     currencyFlag: getCountryFlag(txn.countryCode),
-    // Add parsed token info for UI components
     sourceTokenSymbol: sourceToken.symbol,
     sourceTokenChainId: sourceToken.chainId,
-    sourceTokenAddress: undefined, // Token contract address not available from parsed currency code
+    sourceTokenAddress: undefined,
     destinationTokenSymbol: destinationToken.symbol,
     destinationTokenChainId: destinationToken.chainId,
-    destinationTokenAddress: undefined, // Token contract address not available from parsed currency code
+    destinationTokenAddress: undefined,
   }
 }
 
-// Helper function to get payment method logo
 function getPaymentMethodLogo(
   paymentMethod?: string,
-  paymentMethods?: Array<any>,
+  paymentMethods?: MeldPaymentMethod[],
 ): string {
   if (!paymentMethod || !paymentMethods) return ""
 
-  // Find the payment method in the data
   const methodData = paymentMethods.find(
     (method) =>
       addressEqual(method.paymentMethod, paymentMethod) ||
@@ -152,7 +140,6 @@ function getPaymentMethodLogo(
   )
 
   if (methodData?.logos) {
-    // Prefer light logo, fallback to dark
     return methodData.logos.light || methodData.logos.dark || ""
   }
 
@@ -163,85 +150,33 @@ export function useMeldTransactionHistory({
   enabled = true,
   limit = 20,
   autoRefetch = false,
-  refetchInterval = 10 * SECOND_MS, // 10 seconds
+  refetchInterval = 10 * SECOND_MS,
 }: UseMeldTransactionHistoryParams = {}): UseMeldTransactionHistoryReturn {
   const { address: walletAddress } = useAccount()
   const onrampClient = useOnrampClient()
-  const [hasMore, setHasMore] = useState(false)
 
-  // Fetch payment methods for logo data
-  const { paymentMethods } = useMeldPaymentMethods(onrampClient, "USD")
+  const { data: paymentMethods } = useMeldPaymentMethods("USD")
 
   const { data, isLoading, error, refetch, isFetching } = useQuery({
-    queryKey: ["meldTransactionHistory", walletAddress, limit],
-    queryFn: async () => {
-      if (!walletAddress) {
-        throw new Error("Wallet address required")
-      }
-
-      // Use wallet address as the external customer ID
-      const request: SearchMeldTransactionsRequest = {
-        externalCustomerIds: normalizeAddress(walletAddress),
-        limit: limit,
-        // Sort by most recent first (API may support this in the future)
-        // from: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(), // Last 30 days
-      }
-
-      logger.console.log(
-        "[trails-sdk] searchMeldTransactions request:",
-        request,
-      )
-
-      try {
-        const response: SearchMeldTransactionsResponse =
-          await onrampClient.searchMeldTransactions(request)
-
-        logger.console.log("[trails-sdk] searchMeldTransactions response:", {
-          transactionCount: response.transactions?.transactions?.length || 0,
-        })
-
-        // Parse transactions with payment method data for logos
-        const parsedTransactions: MeldTransactionData[] = (
-          response.transactions?.transactions || []
-        ).map((txn) => parseMeldTransaction(txn, paymentMethods))
-
-        // Check if there might be more transactions
-        setHasMore(parsedTransactions.length >= limit)
-
-        return {
-          transactions: parsedTransactions,
-        }
-      } catch (apiError) {
-        logger.console.error(
-          "[trails-sdk] searchMeldTransactions error:",
-          apiError,
-        )
-        throw apiError
-      }
-    },
-    enabled: enabled && !!walletAddress,
-    staleTime: autoRefetch ? 0 : 5 * MINUTE_MS, // 5 minutes if not auto-refetching
+    ...meldQueries.transactionHistoryList(onrampClient, walletAddress, limit),
+    enabled,
+    ...(autoRefetch && { staleTime: 0 }),
     refetchInterval: autoRefetch ? refetchInterval : false,
     placeholderData: (previousData) => previousData,
   })
 
-  const transactions = data?.transactions ?? []
-
-  const refetchTransactions = useCallback(() => {
-    refetch()
-  }, [refetch])
-
-  // Reset hasMore when wallet address changes
-  // biome-ignore lint/correctness/useExhaustiveDependencies: we intentionally want this to run when walletAddress changes
-  useEffect(() => {
-    setHasMore(false)
-  }, [walletAddress])
+  const transactions = useMemo(() => {
+    if (!data?.transactions?.length) return []
+    return data.transactions.map((txn) =>
+      parseMeldTransaction(txn, paymentMethods),
+    )
+  }, [data, paymentMethods])
 
   return {
     transactions,
     loading: isLoading || isFetching,
     error: error instanceof Error ? error.message : null,
-    refetch: refetchTransactions,
-    hasMore,
+    refetch,
+    hasMore: data?.hasMore ?? false,
   }
 }

package/src/widget/hooks/useOnRampCountryDefaults.ts

@@ -1,7 +1,7 @@
 import { useQuery } from "@tanstack/react-query"
 import { useCountryCode } from "../../query/geo.hooks.js"
-import { MINUTE_MS } from "../../utils/time.js"
 import { useOnrampClient } from "../../onrampClient.js"
+import { meldQueries } from "../../query/meld.queries.js"
 
 export interface OnRampCountryDefaults {
   countryCode: string
@@ -11,32 +11,14 @@ export interface OnRampCountryDefaults {
 }
 
 export interface UseOnRampCountryDefaultsOptions {
-  /**
-   * Whether to enable the hook (defaults to true)
-   */
   enabled?: boolean
 }
 
 export interface UseOnRampCountryDefaultsResult {
-  /**
-   * Detected country code (ISO 2-letter code, e.g., "US", "GB")
-   */
   countryCode: string | null
-  /**
-   * Default fiat currency code for the detected country (e.g., "USD")
-   */
   defaultCurrencyCode: string | null
-  /**
-   * Default payment methods for the detected country
-   */
   defaultPaymentMethods: Array<string>
-  /**
-   * Whether the request is currently loading
-   */
   isLoading: boolean
-  /**
-   * Error object if the request failed, null otherwise
-   */
   error: Error | null
 }
 
@@ -45,49 +27,21 @@ export function useOnRampCountryDefaults(
 ): UseOnRampCountryDefaultsResult {
   const { enabled = true } = options
 
-  // Get country code using the dedicated hook
   const {
     data: countryCode,
     isLoading: isCountryLoading,
     error: countryError,
   } = useCountryCode({ enabled })
 
-  // Get onramp client
   const onrampClient = useOnrampClient()
 
-  // Fetch country defaults once we have the country code
   const {
     data: countryDefaults,
     isLoading: isDefaultsLoading,
     error: defaultsError,
   } = useQuery({
-    queryKey: ["meldCountryDefaults", countryCode],
-    queryFn: async () => {
-      if (!countryCode) {
-        throw new Error("Country code is required")
-      }
-
-      const responseData = await onrampClient.getMeldCountryDefaults({
-        countryCode,
-      })
-
-      // Extract data from response - only use API value; caller will fall back to USD if missing
-      const defaultCurrencyCode =
-        responseData.defaults?.[0]?.defaultCurrencyCode ?? undefined
-      const defaultPaymentMethods =
-        responseData.defaults?.[0]?.defaultPaymentMethods || []
-
-      return {
-        defaultCurrencyCode,
-        defaultPaymentMethods,
-      }
-    },
-    enabled: enabled && !!countryCode && !!onrampClient,
-    staleTime: 10 * MINUTE_MS, // 10 minutes - country defaults don't change frequently
-    gcTime: 30 * MINUTE_MS, // 30 minutes cache time
-    retry: 2,
-    refetchOnWindowFocus: false,
-    refetchOnReconnect: true,
+    ...meldQueries.countryDefaultsByCode(onrampClient, countryCode ?? null),
+    enabled,
   })
 
   const isLoading = isCountryLoading || isDefaultsLoading

package/src/widget/hooks/useOnRampPaymentMethods.ts

@@ -1,18 +1,11 @@
 import { useQuery } from "@tanstack/react-query"
-import { MINUTE_MS } from "../../utils/time.js"
+import type { MeldPaymentMethod } from "../../query/meld.fetchers.js"
 import { useOnRampCountryDefaults } from "./useOnRampCountryDefaults.js"
 import type { TrailsOnramp } from "../../onrampClient.js"
 import { useOnrampClient } from "../../onrampClient.js"
+import { meldQueries } from "../../query/meld.queries.js"
 
-export interface PaymentMethod {
-  paymentMethod: string
-  name: string
-  paymentType: string
-  logos?: {
-    dark?: string
-    light?: string
-  }
-}
+export type PaymentMethod = MeldPaymentMethod
 
 export interface UseOnRampPaymentMethodsOptions {
   trailsClient?: TrailsOnramp | null
@@ -21,28 +14,11 @@ export interface UseOnRampPaymentMethodsOptions {
 }
 
 export interface UseOnRampPaymentMethodsResult {
-  /**
-   * Array of payment methods available for the resolved fiat currency
-   */
   paymentMethods: PaymentMethod[]
-  /**
-   * Whether the request is currently loading
-   */
   isLoading: boolean
-  /**
-   * Error object if the request failed, null otherwise
-   */
   error: Error | null
 }
 
-/**
- * Hook to fetch Meld payment methods for a given fiat currency.
- *
- * Can use either TrailsApi client or direct fetch to localhost API.
- * If fiatCurrency is not provided, will fall back to `defaultCurrencyCode` if given,
- * otherwise it will use "USD".
- */
-// Allowed payment methods to filter from the API response
 const ALLOWED_PAYMENT_METHODS = [
   "CREDIT_DEBIT_CARD",
   "EXCHANGE",
@@ -52,6 +28,13 @@ const ALLOWED_PAYMENT_METHODS = [
   "SEPA",
 ] as const
 
+const selectAllowedPaymentMethods = (methods: MeldPaymentMethod[]) =>
+  methods.filter((method) =>
+    ALLOWED_PAYMENT_METHODS.includes(
+      method.paymentMethod as (typeof ALLOWED_PAYMENT_METHODS)[number],
+    ),
+  )
+
 export function useOnRampPaymentMethods(
   options: UseOnRampPaymentMethodsOptions,
 ): UseOnRampPaymentMethodsResult {
@@ -59,88 +42,26 @@ export function useOnRampPaymentMethods(
 
   const defaultOnrampClient = useOnrampClient()
 
-  const {
-    countryCode,
-    defaultCurrencyCode,
-    isLoading: isLoadingCountryDefaults,
-  } = useOnRampCountryDefaults({
-    enabled: enabled,
-  })
+  const { defaultCurrencyCode, isLoading: isLoadingCountryDefaults } =
+    useOnRampCountryDefaults({ enabled })
 
   const currencyToUse = fiatCurrency || defaultCurrencyCode || null
 
-  // Determine if query should be enabled
-  const isQueryEnabled = () => {
-    if (!enabled) return false
-    if (trailsClient !== undefined && !trailsClient) return false
-    if (!currencyToUse) return false
-    if (!fiatCurrency && isLoadingCountryDefaults) return false
-    return true
-  }
+  const client = trailsClient !== undefined ? trailsClient : defaultOnrampClient
+
+  const factoryOptions = meldQueries.paymentMethodList(client, currencyToUse)
+
+  const isQueryEnabled =
+    enabled && !(fiatCurrency === undefined && isLoadingCountryDefaults)
 
-  // Use React Query for automatic caching based on countryCode and currency
   const {
     data: paymentMethods = [],
     isLoading,
     error,
   } = useQuery({
-    queryKey: [
-      "meldPaymentMethods",
-      countryCode || "unknown",
-      currencyToUse,
-      "onrampClient",
-    ],
-    queryFn: async () => {
-      if (!currencyToUse) {
-        throw new Error("Currency is required but not available")
-      }
-
-      const client = trailsClient || defaultOnrampClient
-      const response = await client.getMeldPaymentMethods({
-        fiatCurrency: currencyToUse,
-      })
-
-      // Parse payment methods from response
-      const responseMethods = Array.isArray(response.paymentMethods)
-        ? response.paymentMethods
-        : []
-
-      const methods = responseMethods.map(
-        (method: {
-          paymentMethod?: string
-          payment_method?: string
-          name?: string
-          paymentType?: string
-          payment_type?: string
-          logos?: { dark?: string; light?: string }
-        }) => ({
-          paymentMethod: method.paymentMethod || method.payment_method || "",
-          name: method.name || "",
-          paymentType: method.paymentType || method.payment_type || "",
-          logos: method.logos
-            ? {
-                dark: method.logos.dark,
-                light: method.logos.light,
-              }
-            : undefined,
-        }),
-      )
-
-      // Filter to only include allowed payment methods
-      const filteredMethods = methods.filter((method) =>
-        ALLOWED_PAYMENT_METHODS.includes(
-          method.paymentMethod as (typeof ALLOWED_PAYMENT_METHODS)[number],
-        ),
-      )
-
-      return filteredMethods
-    },
-    enabled: isQueryEnabled(),
-    staleTime: 5 * MINUTE_MS, // 5 minutes - payment methods don't change frequently
-    gcTime: 30 * MINUTE_MS, // 30 minutes cache time
-    retry: 2,
-    refetchOnWindowFocus: false,
-    refetchOnReconnect: true,
+    ...factoryOptions,
+    enabled: isQueryEnabled,
+    select: selectAllowedPaymentMethods,
   })
 
   return {

package/src/widget/hooks/useOnRampQuote.ts

@@ -1,5 +1,6 @@
 import { useMemo } from "react"
 import { useQuery } from "@tanstack/react-query"
+import { isValidStringAmount } from "../../utils/validation.js"
 import { logger } from "../../logger.js"
 import { SECOND_MS, MINUTE_MS } from "../../utils/time.js"
 import type { MeldQuote } from "../../meld/utils/meld.js"
@@ -70,11 +71,7 @@ export function useOnRampQuote(
   // Check if all required params are present
   const hasRequiredParams = useMemo(() => {
     // Validate amount is present and is a valid positive number
-    const isValidAmount =
-      Boolean(amount) &&
-      amount !== "0" &&
-      !Number.isNaN(Number(amount)) &&
-      Number(amount) > 0
+    const isValidAmount = isValidStringAmount(amount ?? "")
 
     return (
       isValidAmount &&

package/src/widget/hooks/useQuote.ts

@@ -82,6 +82,10 @@ export type UseQuoteProps = {
   swapProvider?: RouteProvider | null
   /** Optional quote bridge provider ID to use. If not specified, the best available provider will be selected. */
   bridgeProvider?: RouteProvider | null
+  /** Optional swap provider fallback flag passed to QuoteIntent request options. */
+  swapProviderFallback?: boolean
+  /** Optional bridge provider fallback flag passed to QuoteIntent request options. */
+  bridgeProviderFallback?: boolean
   /**
    * Optional checkout event handlers for tracking the states of a Trails transaction.
    *
@@ -439,6 +443,8 @@ export function useQuote({
   checkoutOnHandlers,
   swapProvider,
   bridgeProvider,
+  swapProviderFallback,
+  bridgeProviderFallback,
   paymasterUrl,
   selectedFeeOption,
   nodeGatewayEnv,
@@ -675,6 +681,8 @@ export function useQuote({
       slippageTolerance,
       swapProvider,
       bridgeProvider,
+      swapProviderFallback,
+      bridgeProviderFallback,
       apiKey,
       isSmartWallet,
       fundMethod,
@@ -913,18 +921,6 @@ export function useQuote({
               ? parseUnits("100", sourceTokenDecimals).toString()
               : originTokenBalanceAmount
 
-          // Validate effectiveOriginTokenBalance for EXACT_INPUT trade type
-          if (
-            tradeType === TradeType.EXACT_INPUT &&
-            (!effectiveOriginTokenBalance ||
-              effectiveOriginTokenBalance === "0")
-          ) {
-            logger.console.log(
-              "[trails-sdk] [useQuote] Skipping quote for EXACT_INPUT with zero effectiveOriginTokenBalance",
-            )
-            return null
-          }
-
           const options: PrepareSendOptions = {
             queryClient,
             account: walletClient.account!,
@@ -948,6 +944,8 @@ export function useQuote({
             slippageTolerance: slippageTolerance?.toString(),
             swapProvider: effectiveSwapProvider,
             bridgeProvider: effectiveBridgeProvider,
+            swapProviderFallback,
+            bridgeProviderFallback,
             paymasterUrl: paymasterUrl,
             selectedFeeOption: selectedFeeOption ?? null,
             abortSignal: combinedAbortSignal,

package/src/widget/hooks/useSendForm.ts

@@ -104,6 +104,8 @@ export type UseSendProps = {
   tradeType?: TradeType
   swapProvider?: string
   bridgeProvider?: string
+  swapProviderFallback?: boolean
+  bridgeProviderFallback?: boolean
   fundMethod?: FundMethod
   mode?: "pay" | "fund" | "earn" | "swap" | "withdraw"
   checkoutOnHandlers?: CheckoutOnHandlers
@@ -206,6 +208,8 @@ export function useSendForm({
   tradeType = TradeType.EXACT_OUTPUT,
   swapProvider,
   bridgeProvider,
+  swapProviderFallback,
+  bridgeProviderFallback,
   fundMethod,
   mode,
   checkoutOnHandlers,
@@ -888,6 +892,8 @@ export function useSendForm({
     onStatusUpdate: handleTransactionStateChange,
     swapProvider: swapProvider as RouteProvider | null | undefined,
     bridgeProvider: bridgeProvider as RouteProvider | null | undefined,
+    swapProviderFallback,
+    bridgeProviderFallback,
     checkoutOnHandlers,
     paymasterUrl,
     selectedFeeOption: selectedFeeOption ?? null,

package/src/widget/hooks/useTokenList.ts

@@ -12,6 +12,7 @@ import {
   isNativeToken as isNativeTokenUtil,
   normalizeAddress,
 } from "../../utils/address.js"
+import { isValidDecimals } from "../../utils/validation.js"
 import {
   useAccountTotalBalanceUsd,
   useHasSufficientBalanceUsd,
@@ -433,9 +434,7 @@ export function useTokenList({
 
     return chainFilteredTokenList.tokens
       .filter((tokenInfo: ApiTokenInfo) => {
-        // Validate decimals - must be between 1 and 18
-        const decimals = tokenInfo.decimals
-        if (!Number.isInteger(decimals) || decimals < 1 || decimals > 18) {
+        if (!isValidDecimals(tokenInfo.decimals)) {
           logger.console.warn(
             "[trails-sdk] Skipping token with invalid decimals:",
             {
@@ -685,9 +684,7 @@ export function useTokenList({
 
     return searchTokensResult.tokens
       .filter((tokenInfo: ApiTokenInfo) => {
-        // Validate decimals - must be between 1 and 18 (formatRawAmount requires 1-18)
-        const decimals = tokenInfo.decimals
-        if (!Number.isInteger(decimals) || decimals < 1 || decimals > 18) {
+        if (!isValidDecimals(tokenInfo.decimals)) {
           logger.console.warn(
             "[trails-sdk] Skipping token with invalid decimals:",
             {