0xtrails 0.13.1 → 0.14.0

package/src/query/balance.hooks.ts

@@ -1,298 +0,0 @@
-import { SECOND_MS } from "../utils/time.js"
-import type {
-  NativeTokenBalance,
-  SequenceIndexerGateway,
-  TokenBalance,
-} from "@0xsequence/indexer"
-import { useQuery, skipToken } from "@tanstack/react-query"
-import type { Address } from "ox"
-import { zeroAddress } from "viem"
-import { useIndexerGatewayClient } from "../indexerClient.js"
-import type { Token } from "../tokens.js"
-import { useTrailsClient, type TrailsClient } from "../trailsClient.js"
-import { addressEqual } from "../utils/address.js"
-import { useUserActivityContext } from "../widget/providers/UserActivityProvider.js"
-import { useSkipBalanceFetch } from "../widget/hooks/useSelectedFundMethod.js"
-import { balanceQueries } from "./balance.queries.js"
-import { useSupportedChains } from "./chains.hooks.js"
-import {
-  sortTokensByPriority,
-  type FlatTokenBalancesData,
-  type GetTokenBalancesForMultipleAccountsReturn,
-  type GetTokenBalancesWithPriceReturn,
-} from "./balance.fetchers.js"
-
-export type { NativeTokenBalance, TokenBalance }
-
-export const WIDGET_REFRESH_INTERVAL = 5 * SECOND_MS
-
-export const MIN_REFETCH_INTERVAL = 5 * SECOND_MS
-
-/** Clamp a caller-supplied refetchInterval to the minimum allowed value. */
-function clampRefetchInterval(
-  interval: number | false | undefined,
-): number | false {
-  if (interval === false || interval === undefined) return false
-  return Math.max(interval, MIN_REFETCH_INTERVAL)
-}
-
-export type UseTokenBalancesOptions = {
-  disabled?: boolean
-  page?: number
-  pageSize?: number
-  refetchInterval?: number | false
-}
-
-export function useTokenBalances(
-  address: Address.Address | null,
-  _tokenAddress?: string | null | undefined,
-  options?: UseTokenBalancesOptions,
-): {
-  isLoadingBalances: boolean
-  isLoadingPrices: boolean
-  isLoadingSortedTokens: boolean
-  balanceError: Error | null
-  sortedTokens: Token[]
-  refetch: () => Promise<void>
-} {
-  const indexerClient = useIndexerGatewayClient()
-  const trailsClient = useTrailsClient()
-  const { isUserActive } = useUserActivityContext()
-  const { shouldSkipBalanceFetch } = useSkipBalanceFetch()
-  const { data: supportedChains = [] } = useSupportedChains()
-
-  const isDisabled =
-    options?.disabled !== undefined ? options.disabled : shouldSkipBalanceFetch
-
-  // Pass null when disabled → balancesWithPricesOptions uses skipToken
-  const effectiveAddress = isDisabled ? null : address
-
-  const refetchInterval = isUserActive
-    ? clampRefetchInterval(options?.refetchInterval)
-    : false
-  const supportedChainIds =
-    supportedChains.length > 0
-      ? new Set(supportedChains.map((chain) => chain.id))
-      : null
-
-  const {
-    data: sortedTokens = [],
-    isLoading,
-    error: balanceError,
-    refetch,
-  } = useQuery({
-    ...balanceQueries.withPrices(effectiveAddress, indexerClient, trailsClient),
-    select: ({ balances }: GetTokenBalancesWithPriceReturn) => {
-      const nonZeroBalanceTokens = balances.filter((token) => {
-        try {
-          return token.balance && BigInt(token.balance) > 0n
-        } catch {
-          return false
-        }
-      })
-
-      if (!supportedChainIds) {
-        return nonZeroBalanceTokens.sort(sortTokensByPriority)
-      }
-
-      const supportedTokens = nonZeroBalanceTokens.filter((token) =>
-        supportedChainIds.has(token.chainId || 0),
-      )
-
-      // Fail open: if chain filtering yields nothing, keep the user's full
-      // non-zero token list instead of showing empty balances.
-      if (supportedTokens.length === 0) {
-        return nonZeroBalanceTokens.sort(sortTokensByPriority)
-      }
-
-      return supportedTokens.sort(sortTokensByPriority)
-    },
-    refetchOnWindowFocus: true,
-    refetchOnReconnect: true,
-    refetchInterval,
-    refetchIntervalInBackground: false,
-    refetchOnMount: true,
-  })
-
-  return {
-    isLoadingBalances: isLoading,
-    isLoadingPrices: isLoading,
-    isLoadingSortedTokens: isLoading,
-    balanceError,
-    sortedTokens,
-    refetch: async () => {
-      await refetch()
-    },
-  }
-}
-
-export type TokenBalancesForAccount = {
-  tokenBalancesData: FlatTokenBalancesData | undefined
-  isLoading: boolean
-  error: Error | null
-}
-
-export type UseTokenBalancesForMultipleAccountsReturn = {
-  /** Per-account token balances data, keyed by lowercase address */
-  balancesByAccount: { [account: string]: TokenBalancesForAccount }
-  /** Combined loading state - true if any account is loading */
-  isLoading: boolean
-  /** Combined error - first error encountered */
-  error: Error | null
-  /** Refetch function to manually trigger balance updates */
-  refetch: () => Promise<void>
-}
-
-/**
- * Hook to fetch token balances for multiple accounts in a single API call
- * This is more efficient than calling useTokenBalances multiple times
- */
-export function useTokenBalancesForMultipleAccounts(
-  addresses: (Address.Address | null)[],
-  options?: {
-    page?: number
-    pageSize?: number
-    refetchInterval?: number
-    staleTime?: number
-  },
-): UseTokenBalancesForMultipleAccountsReturn {
-  const indexerClient = useIndexerGatewayClient()
-  const { isUserActive } = useUserActivityContext()
-
-  const refetchInterval = isUserActive
-    ? clampRefetchInterval(options?.refetchInterval)
-    : false
-  const staleTime = options?.staleTime
-
-  // Filter out null addresses and normalize to lowercase
-  const validAddresses = addresses
-    .filter((addr): addr is Address.Address => addr !== null && addr.length > 0)
-    .map((addr) => addr.toLowerCase())
-
-  const {
-    data: multiAccountData,
-    isLoading,
-    error,
-    refetch,
-  } = useQuery<GetTokenBalancesForMultipleAccountsReturn>({
-    ...balanceQueries.multiAccount(validAddresses, indexerClient, {
-      page: options?.page,
-      pageSize: options?.pageSize,
-    }),
-    staleTime: staleTime,
-    refetchOnWindowFocus: true,
-    refetchOnReconnect: true,
-    refetchInterval,
-    refetchIntervalInBackground: true,
-    refetchOnMount: true,
-  })
-
-  // Build the per-account result structure
-  const balancesByAccount: { [account: string]: TokenBalancesForAccount } = {}
-  for (const addr of validAddresses) {
-    balancesByAccount[addr] = {
-      tokenBalancesData: multiAccountData?.[addr],
-      isLoading,
-      error,
-    }
-  }
-
-  return {
-    balancesByAccount,
-    isLoading,
-    error,
-    refetch: async () => {
-      await refetch()
-    },
-  }
-}
-
-export type UseAccountTokenBalanceParams = {
-  account?: string | null
-  token?: string | null
-  chainId?: number | null
-  indexerGatewayClient?: SequenceIndexerGateway | null
-  trailsClient?: TrailsClient | null
-}
-
-export function useAccountTokenBalance({
-  account,
-  token,
-  chainId,
-  indexerGatewayClient,
-  trailsClient,
-}: UseAccountTokenBalanceParams) {
-  const base = balanceQueries.withPrices(
-    account,
-    indexerGatewayClient,
-    trailsClient,
-  )
-  const canCheck = !!token && chainId != null
-
-  return useQuery({
-    ...base,
-    queryFn: canCheck ? base.queryFn : skipToken,
-    select: ({ balances }: GetTokenBalancesWithPriceReturn) =>
-      balances.find(
-        (b) =>
-          (b.chainId ?? 0) === chainId &&
-          (addressEqual(b.contractAddress, token!) ||
-            (!b.contractAddress && token === zeroAddress)),
-      ) ?? null,
-  })
-}
-
-export function useHasSufficientBalanceToken(
-  account: string,
-  token: string,
-  amount: string,
-  chainId: number,
-) {
-  const indexerGatewayClient = useIndexerGatewayClient()
-  const trailsClient = useTrailsClient()
-
-  return useQuery({
-    ...balanceQueries.sufficientToken(
-      account,
-      token,
-      amount,
-      chainId,
-      indexerGatewayClient,
-      trailsClient,
-    ),
-    refetchOnWindowFocus: false,
-  })
-}
-
-export function useHasSufficientBalanceUsd(
-  account: string | null,
-  targetAmountUsd?: number | string | null,
-) {
-  const indexerGatewayClient = useIndexerGatewayClient()
-  const trailsClient = useTrailsClient()
-
-  return useQuery({
-    ...balanceQueries.sufficientUsd(
-      account,
-      targetAmountUsd,
-      indexerGatewayClient,
-      trailsClient,
-    ),
-    refetchOnWindowFocus: false,
-  })
-}
-
-export function useAccountTotalBalanceUsd(account: string | null) {
-  const indexerGatewayClient = useIndexerGatewayClient()
-  const trailsClient = useTrailsClient()
-  const { isUserActive } = useUserActivityContext()
-
-  return useQuery({
-    ...balanceQueries.totalUsd(account, indexerGatewayClient, trailsClient),
-    refetchOnWindowFocus: false,
-    refetchOnReconnect: true,
-    refetchInterval: isUserActive ? WIDGET_REFRESH_INTERVAL : false,
-    refetchIntervalInBackground: false,
-    refetchOnMount: true,
-  })
-}

package/src/query/balance.queries.ts

@@ -1,244 +0,0 @@
-import {
-  queryOptions,
-  skipToken,
-  type QueryClient,
-} from "@tanstack/react-query"
-import type { SequenceIndexerGateway } from "@0xsequence/indexer"
-import type { TrailsClient } from "../trailsClient.js"
-import { SECOND_MS } from "../utils/time.js"
-import { createRetry, retryDelay } from "./helpers.js"
-import {
-  fetchMultiAccountBalances,
-  fetchBalancesWithPrices,
-  checkSufficientToken,
-  type GetTokenBalancesForMultipleAccountsReturn,
-  type GetTokenBalancesWithPriceReturn,
-} from "./balance.fetchers.js"
-import { queryClient as defaultQueryClient } from "./client.js"
-import { logger } from "../logger.js"
-
-const BALANCE_STALE_MS = 5 * SECOND_MS
-const BALANCE_GC_MS = 30 * SECOND_MS
-
-// ============================================================================
-// Balance Query Factory
-//
-// Single factory following the TanStack Query v5 canonical pattern.
-// Key-only entries (all, multiAccounts, details) enable hierarchical
-// invalidation. Leaf entries return full queryOptions objects.
-//
-// Usage:
-//   useQuery(balanceQueries.withPrices(account, indexer, trails))
-//   queryClient.invalidateQueries({ queryKey: balanceQueries.all })
-//   balanceQueries.withPrices(account, indexer, trails).queryKey
-// ============================================================================
-
-export const balanceQueries = {
-  // ── invalidation roots (key-only) ──
-  all: ["balances"] as const,
-
-  // ── multi-account summaries ──
-  multiAccounts: () => [...balanceQueries.all, "multiAccount"] as const,
-
-  multiAccount: (
-    accounts: string[],
-    indexerClient: SequenceIndexerGateway | null | undefined,
-    opts?: { page?: number; pageSize?: number },
-  ) => {
-    const sorted = [...accounts].sort()
-    const canFetch = accounts.length > 0 && !!indexerClient
-    return queryOptions<GetTokenBalancesForMultipleAccountsReturn>({
-      queryKey: [
-        ...balanceQueries.multiAccounts(),
-        sorted.join(","),
-        opts?.page ?? null,
-        opts?.pageSize ?? null,
-      ] as const,
-      queryFn: canFetch
-        ? () =>
-            fetchMultiAccountBalances({
-              accounts: sorted,
-              indexerGatewayClient: indexerClient,
-              page: opts?.page,
-              pageSize: opts?.pageSize,
-            })
-        : skipToken,
-      staleTime: BALANCE_STALE_MS,
-      gcTime: BALANCE_GC_MS,
-      retry: createRetry(3),
-      retryDelay,
-    })
-  },
-
-  // ── single-account detail ──
-  details: () => [...balanceQueries.all, "detail"] as const,
-
-  withPrices: (
-    account: string | null | undefined,
-    indexerClient: SequenceIndexerGateway | null | undefined,
-    trailsClient: TrailsClient | null | undefined,
-  ) => {
-    const canFetch = !!account && !!indexerClient && !!trailsClient
-    return queryOptions<GetTokenBalancesWithPriceReturn>({
-      queryKey: [...balanceQueries.details(), account ?? null] as const,
-      queryFn: canFetch
-        ? () =>
-            fetchBalancesWithPrices({
-              account,
-              indexerGatewayClient: indexerClient,
-              trailsClient,
-            })
-        : skipToken,
-      staleTime: BALANCE_STALE_MS,
-      gcTime: BALANCE_GC_MS,
-      retry: createRetry(2),
-      retryDelay,
-    })
-  },
-
-  totalUsd: (
-    account: string | null | undefined,
-    indexerClient: SequenceIndexerGateway | null | undefined,
-    trailsClient: TrailsClient | null | undefined,
-  ) => {
-    return queryOptions({
-      ...balanceQueries.withPrices(account, indexerClient, trailsClient),
-      select: ({ balances }: GetTokenBalancesWithPriceReturn) =>
-        balances.reduce((acc, b) => acc + (b.balanceUsd ?? 0), 0),
-    })
-  },
-
-  sufficientToken: (
-    account: string | null | undefined,
-    token: string | null | undefined,
-    amount: string | null | undefined,
-    chainId: number | null | undefined,
-    indexerClient: SequenceIndexerGateway | null | undefined,
-    trailsClient: TrailsClient | null | undefined,
-  ) => {
-    const base = balanceQueries.withPrices(account, indexerClient, trailsClient)
-    const canCheck = !!account && !!token && !!amount && !!chainId
-    return queryOptions({
-      ...base,
-      queryFn: canCheck ? base.queryFn : skipToken,
-      select: ({ balances }: GetTokenBalancesWithPriceReturn) => {
-        if (!token || !amount || !chainId) return false
-        return checkSufficientToken(balances, token, amount, chainId)
-      },
-    })
-  },
-
-  sufficientUsd: (
-    account: string | null | undefined,
-    targetAmountUsd: number | string | null | undefined,
-    indexerClient: SequenceIndexerGateway | null | undefined,
-    trailsClient: TrailsClient | null | undefined,
-  ) => {
-    const base = balanceQueries.withPrices(account, indexerClient, trailsClient)
-    return queryOptions({
-      ...base,
-      queryFn: account && targetAmountUsd != null ? base.queryFn : skipToken,
-      select: ({ balances }: GetTokenBalancesWithPriceReturn) =>
-        balances.reduce((acc, b) => acc + (b.balanceUsd ?? 0), 0) >=
-        Number(targetAmountUsd),
-    })
-  },
-}
-
-// ============================================================================
-// Cache Invalidation
-// ============================================================================
-
-export function invalidateTokenBalancesCache(
-  account?: string,
-  queryClient?: QueryClient,
-) {
-  const effectiveQueryClient = queryClient ?? defaultQueryClient
-  const timestamp = new Date().toISOString()
-
-  logger.console.log("[CACHE-FLOW] INVALIDATING cache", {
-    timestamp,
-    account: account || "all",
-    action: "INVALIDATE_START",
-  })
-
-  effectiveQueryClient.invalidateQueries({
-    queryKey: balanceQueries.all,
-    refetchType: "all",
-  })
-
-  logger.console.log(
-    "[CACHE-FLOW] INVALIDATE complete + ALL REFETCH triggered",
-    {
-      timestamp,
-      account: account || "all",
-      action: "INVALIDATE_AND_REFETCH_COMPLETE",
-    },
-  )
-}
-
-// ============================================================================
-// Imperative Helpers (non-React)
-// ============================================================================
-
-export type HasSufficientBalanceParams = {
-  account: string
-  token: string
-  amount: string
-  chainId: number
-  indexerGatewayClient: SequenceIndexerGateway
-  trailsClient: TrailsClient
-}
-
-export async function getHasSufficientBalanceToken({
-  account,
-  token,
-  amount,
-  chainId,
-  indexerGatewayClient,
-  trailsClient,
-}: HasSufficientBalanceParams): Promise<boolean> {
-  const { balances } = await defaultQueryClient.ensureQueryData(
-    balanceQueries.withPrices(account, indexerGatewayClient, trailsClient),
-  )
-  return checkSufficientToken(balances, token, amount, chainId)
-}
-
-export type GetHasSufficientBalanceUsdParams = {
-  account: string
-  targetAmountUsd: number | string
-  indexerGatewayClient: SequenceIndexerGateway
-  trailsClient: TrailsClient
-}
-
-export async function getHasSufficientBalanceUsd({
-  account,
-  targetAmountUsd,
-  indexerGatewayClient,
-  trailsClient,
-}: GetHasSufficientBalanceUsdParams): Promise<boolean> {
-  const { balances } = await defaultQueryClient.ensureQueryData(
-    balanceQueries.withPrices(account, indexerGatewayClient, trailsClient),
-  )
-  return (
-    balances.reduce((acc, b) => acc + (b.balanceUsd ?? 0), 0) >=
-    Number(targetAmountUsd)
-  )
-}
-
-export type GetAccountTotalBalanceUsdParams = {
-  account: string
-  indexerGatewayClient: SequenceIndexerGateway
-  trailsClient: TrailsClient
-}
-
-export async function getAccountTotalBalanceUsd({
-  account,
-  indexerGatewayClient,
-  trailsClient,
-}: GetAccountTotalBalanceUsdParams): Promise<number> {
-  const { balances } = await defaultQueryClient.ensureQueryData(
-    balanceQueries.withPrices(account, indexerGatewayClient, trailsClient),
-  )
-  return balances.reduce((acc, b) => acc + (b.balanceUsd ?? 0), 0)
-}

package/src/query/chains.hooks.ts

@@ -1,45 +0,0 @@
-import { useQuery } from "@tanstack/react-query"
-import type { PublicClient } from "viem"
-import { createPublicClient } from "viem"
-import React from "react"
-import { useTrails } from "../widget/providers/TrailsProvider.js"
-import { getChainInfo, getChainTransport } from "../chains.js"
-import { logger } from "../logger.js"
-import { chainQueries } from "./chains.queries.js"
-
-export function useSupportedChains() {
-  const { trailsApiUrl, trailsApiKey } = useTrails()
-  return useQuery(
-    chainQueries.supported({
-      trailsApiUrl,
-      trailsApiKey,
-    }),
-  )
-}
-
-export function useChainRpcClient(chainId?: number): PublicClient | null {
-  const { trailsApiKey, sequenceNodeGatewayUrl } = useTrails()
-
-  return React.useMemo(() => {
-    if (!chainId) {
-      return null
-    }
-    const chainInfo = getChainInfo(chainId, {
-      sequenceProjectAccessKey: trailsApiKey,
-      sequenceNodeGatewayUrl: sequenceNodeGatewayUrl,
-    })
-    if (!chainInfo) {
-      logger.console.warn(
-        `[trails-sdk] Chain ${chainId} not found. Returning null RPC client.`,
-      )
-      return null
-    }
-    return createPublicClient({
-      chain: chainInfo,
-      transport: getChainTransport(chainId, {
-        trailsApiKey,
-        sequenceNodeGatewayUrl,
-      }),
-    })
-  }, [chainId, trailsApiKey, sequenceNodeGatewayUrl])
-}

package/src/query/chains.queries.ts

@@ -1,22 +0,0 @@
-import { queryOptions } from "@tanstack/react-query"
-import { HOUR_MS, DAY_MS } from "../utils/time.js"
-import { getSupportedChains, type Chain } from "../chains.js"
-import { STATIC_QUERY_OPTIONS } from "./helpers.js"
-
-export const chainQueries = {
-  all: ["chains"] as const,
-
-  supported: (config?: { trailsApiUrl?: string; trailsApiKey?: string }) =>
-    queryOptions<Chain[]>({
-      queryKey: [
-        ...chainQueries.all,
-        "supported",
-        config?.trailsApiUrl || "default",
-        config?.trailsApiKey || "",
-      ] as const,
-      queryFn: () => getSupportedChains(config),
-      staleTime: HOUR_MS,
-      gcTime: DAY_MS,
-      ...STATIC_QUERY_OPTIONS,
-    }),
-}

package/src/query/client.ts

@@ -1,20 +0,0 @@
-import { QueryClient } from "@tanstack/react-query"
-import { MINUTE_MS, retryDelay, SECOND_MS } from "../utils/time.js"
-
-/** Shared default options reused by all QueryClient instances in the SDK. */
-export const defaultQueryOptions = {
-  queries: {
-    staleTime: 5 * SECOND_MS,
-    gcTime: 5 * MINUTE_MS,
-    retry: 2,
-    retryDelay,
-    refetchOnWindowFocus: false,
-    refetchIntervalInBackground: false,
-    refetchOnReconnect: true,
-  },
-} as const
-
-/** Singleton QueryClient for the SDK — shared cache for all queries and invalidations. */
-export const queryClient = new QueryClient({
-  defaultOptions: defaultQueryOptions,
-})

package/src/query/fiat.fetchers.ts

@@ -1,33 +0,0 @@
-/**
- * Pure async fetcher functions and helpers for fiat/currency queries.
- * This is a leaf module — NO React imports, NO queryClient.
- */
-import type { ExchangeRate, FiatCurrency } from "@0xtrails/api"
-import type { TrailsClient } from "../trailsClient.js"
-
-// ============================================================================
-// Fetchers
-// ============================================================================
-
-/**
- * Fetch the list of supported fiat currencies from the API.
- */
-export async function getFiatCurrencyList(
-  trailsClient: TrailsClient,
-): Promise<FiatCurrency[]> {
-  const response = await trailsClient.getFiatCurrencyList()
-  return response.currencies || []
-}
-
-/**
- * Fetch the exchange rate from USD to a target currency.
- */
-export async function getExchangeRate(
-  trailsClient: TrailsClient,
-  targetCurrency: string,
-): Promise<ExchangeRate> {
-  const response = await trailsClient.getExchangeRate({
-    toCurrency: targetCurrency,
-  })
-  return response.exchangeRate
-}