0xtrails 0.13.0 → 0.13.2

package/src/query/price.fetchers.ts

@@ -0,0 +1,53 @@
+import type { Token, TokenPrice } from "@0xtrails/api"
+import { zeroAddress } from "viem"
+import type { TrailsClient } from "../trailsClient.js"
+import { logger } from "../logger.js"
+
+export type FetchTokenPricesParams = {
+  trailsClient: TrailsClient
+  tokens: Token[]
+}
+
+export function normalizeToken(
+  token: Token & {
+    tokenID?: string
+    symbol?: string
+    contractAddress?: string
+    tokenId?: string
+  },
+): Token {
+  return {
+    chainId: token.chainId,
+    tokenAddress: token.tokenAddress || token.contractAddress || zeroAddress,
+    tokenSymbol:
+      token.tokenSymbol || token.tokenId || token.tokenID || token.symbol,
+  }
+}
+
+export function createTokenCacheKey(token: Token): string {
+  const tokenAddress = (token.tokenAddress || zeroAddress).toLowerCase()
+  const chainId = Number(token.chainId || 0)
+  const tokenSymbol = (token.tokenSymbol || "").toUpperCase()
+  return `${tokenAddress}-${chainId}-${tokenSymbol}`
+}
+
+export async function fetchTokenPrices(
+  trailsClient: TrailsClient,
+  tokens: Token[],
+): Promise<TokenPrice[]> {
+  if (!trailsClient) {
+    throw new Error("Trails client is required")
+  }
+
+  if (tokens.length === 0) {
+    return []
+  }
+
+  try {
+    const res = await trailsClient.getTokenPrices({ tokens })
+    return res?.tokenPrices || []
+  } catch (error) {
+    logger.console.error("[trails-sdk] Failed to fetch token prices:", error)
+    throw error
+  }
+}

package/src/query/price.hooks.ts

@@ -0,0 +1,46 @@
+import type { Token } from "@0xtrails/api"
+import { useQuery, useQueryClient } from "@tanstack/react-query"
+import { SECOND_MS } from "../utils/time.js"
+import { useTrailsClient } from "../trailsClient.js"
+import { useUserActivityContext } from "../widget/providers/UserActivityProvider.js"
+import { getTokenPriceSeedFromBatches, priceQueries } from "./price.queries.js"
+
+const PRICE_REFETCH_INTERVAL = 90 * SECOND_MS
+
+export function useTokenPrices(tokens: Token[], disabled?: boolean) {
+  const trailsClient = useTrailsClient()
+  const queryClient = useQueryClient()
+  const { isUserActive } = useUserActivityContext()
+
+  const query = useQuery({
+    ...priceQueries.byTokens(tokens, trailsClient, queryClient),
+    enabled: !disabled,
+    refetchInterval: isUserActive ? PRICE_REFETCH_INTERVAL : false,
+  })
+
+  return {
+    ...query,
+    tokenPrices: query.data,
+    isLoadingTokenPrices: query.isLoading,
+  }
+}
+
+export function useTokenPrice(token?: Token | null) {
+  const trailsClient = useTrailsClient()
+  const queryClient = useQueryClient()
+  const { isUserActive } = useUserActivityContext()
+  const seed = getTokenPriceSeedFromBatches(queryClient, token ?? null)
+
+  const query = useQuery({
+    ...priceQueries.byToken(token ?? null, trailsClient, queryClient),
+    initialData: seed.price,
+    initialDataUpdatedAt: seed.updatedAt,
+    refetchInterval: isUserActive ? PRICE_REFETCH_INTERVAL : false,
+  })
+
+  return {
+    ...query,
+    tokenPrice: query.data,
+    isLoadingTokenPrice: query.isLoading,
+  }
+}

package/src/query/price.queries.ts

@@ -0,0 +1,364 @@
+import {
+  queryOptions,
+  skipToken,
+  type QueryClient,
+  type QueryKey,
+} from "@tanstack/react-query"
+import type { Token, TokenPrice } from "@0xtrails/api"
+import type { TrailsClient } from "../trailsClient.js"
+import { SECOND_MS } from "../utils/time.js"
+import { queryClient as defaultQueryClient } from "./client.js"
+import { createRetry, retryDelay } from "./helpers.js"
+import { queryPersister } from "./persister.js"
+import {
+  createTokenCacheKey,
+  fetchTokenPrices,
+  normalizeToken,
+} from "./price.fetchers.js"
+
+const PRICE_SCOPE = "tokenPrices"
+const PRICE_BATCH_SCOPE = "batch"
+const PRICE_SINGLE_SCOPE = "single"
+
+const PRICE_STALE_MS = 90 * SECOND_MS
+const PRICE_GC_MS = 90 * SECOND_MS
+
+type TokenPriceSeed = {
+  price: TokenPrice | null | undefined
+  updatedAt?: number
+}
+
+type MatchingBatchQuery = {
+  queryKey: QueryKey
+  tokens: Token[]
+  data?: TokenPrice[]
+  dataUpdatedAt: number
+  fetchStatus: string
+}
+
+function normalizeTokensForQuery(tokens: Token[]): Token[] {
+  const uniqueTokens = new Map<string, Token>()
+
+  for (const token of tokens) {
+    const normalized = normalizeToken(token)
+    const tokenKey = createTokenCacheKey(normalized)
+
+    if (!uniqueTokens.has(tokenKey)) {
+      uniqueTokens.set(tokenKey, normalized)
+    }
+  }
+
+  return Array.from(uniqueTokens.values()).sort((left, right) =>
+    createTokenCacheKey(left).localeCompare(createTokenCacheKey(right)),
+  )
+}
+
+function isTokenLike(value: unknown): value is Token {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "chainId" in value &&
+    typeof value.chainId === "number" &&
+    "tokenAddress" in value &&
+    typeof value.tokenAddress === "string" &&
+    (!("tokenSymbol" in value) || typeof value.tokenSymbol === "string")
+  )
+}
+
+function getBatchQueryTokens(queryKey: QueryKey): Token[] | null {
+  if (queryKey[0] !== PRICE_SCOPE || queryKey[1] !== PRICE_BATCH_SCOPE) {
+    return null
+  }
+
+  const tokens = queryKey[2]
+  if (!Array.isArray(tokens) || !tokens.every(isTokenLike)) {
+    return null
+  }
+
+  return [...tokens]
+}
+
+function isFreshBatchData(dataUpdatedAt: number): boolean {
+  if (!dataUpdatedAt) {
+    return false
+  }
+
+  return Date.now() - dataUpdatedAt < PRICE_STALE_MS
+}
+
+function findTokenPrice(
+  prices: TokenPrice[] | undefined,
+  tokenKey: string,
+): TokenPrice | null | undefined {
+  if (!prices) {
+    return undefined
+  }
+
+  return (
+    prices.find(
+      (price) => createTokenCacheKey(normalizeToken(price.token)) === tokenKey,
+    ) ?? null
+  )
+}
+
+function getMatchingBatchQueries(
+  queryClient: QueryClient,
+  tokenKey: string,
+): MatchingBatchQuery[] {
+  return queryClient
+    .getQueryCache()
+    .findAll({ queryKey: priceQueries.batch() })
+    .flatMap((query) => {
+      const tokens = getBatchQueryTokens(query.queryKey)
+
+      if (
+        !tokens ||
+        !tokens.some((token) => createTokenCacheKey(token) === tokenKey)
+      ) {
+        return []
+      }
+
+      return [
+        {
+          queryKey: query.queryKey,
+          tokens,
+          data: Array.isArray(query.state.data)
+            ? (query.state.data as TokenPrice[])
+            : undefined,
+          dataUpdatedAt: query.state.dataUpdatedAt,
+          fetchStatus: query.state.fetchStatus,
+        },
+      ]
+    })
+}
+
+function seedSingleTokenPriceQueries({
+  queryClient,
+  trailsClient,
+  tokens,
+  prices,
+}: {
+  queryClient: QueryClient
+  trailsClient: TrailsClient
+  tokens: Token[]
+  prices: TokenPrice[]
+}) {
+  const priceMap = new Map(
+    prices.map((price) => [
+      createTokenCacheKey(normalizeToken(price.token)),
+      price,
+    ]),
+  )
+
+  for (const token of tokens) {
+    const tokenKey = createTokenCacheKey(token)
+    queryClient.setQueryData<TokenPrice | null>(
+      priceQueries.byToken(token, trailsClient, queryClient).queryKey,
+      priceMap.get(tokenKey) ?? null,
+    )
+  }
+}
+
+export function getTokenPriceSeedFromBatches(
+  queryClient: QueryClient,
+  token: Token | null | undefined,
+): TokenPriceSeed {
+  if (!token) {
+    return {
+      price: undefined,
+      updatedAt: undefined,
+    }
+  }
+
+  const normalizedToken = normalizeToken(token)
+  const tokenKey = createTokenCacheKey(normalizedToken)
+
+  const freshestMatch = getMatchingBatchQueries(queryClient, tokenKey)
+    .filter((match) => match.data !== undefined)
+    .sort((left, right) => right.dataUpdatedAt - left.dataUpdatedAt)[0]
+
+  if (!freshestMatch?.data) {
+    return {
+      price: undefined,
+      updatedAt: undefined,
+    }
+  }
+
+  return {
+    price: findTokenPrice(freshestMatch.data, tokenKey),
+    updatedAt: freshestMatch.dataUpdatedAt || undefined,
+  }
+}
+
+async function fetchTokenPriceWithBatchReuse({
+  queryClient,
+  trailsClient,
+  token,
+}: {
+  queryClient: QueryClient
+  trailsClient: TrailsClient
+  token: Token
+}): Promise<TokenPrice | null> {
+  const tokenKey = createTokenCacheKey(token)
+
+  const fetchingMatch = getMatchingBatchQueries(queryClient, tokenKey)
+    .filter((match) => match.fetchStatus === "fetching")
+    .sort((left, right) => left.tokens.length - right.tokens.length)[0]
+
+  if (fetchingMatch) {
+    try {
+      const prices = await queryClient.fetchQuery(
+        priceQueries.byTokens(fetchingMatch.tokens, trailsClient, queryClient),
+      )
+
+      return findTokenPrice(prices, tokenKey) ?? null
+    } catch {
+      // Fall through to an isolated single-token fetch.
+    }
+  }
+
+  const freshestBatchMatch = getMatchingBatchQueries(queryClient, tokenKey)
+    .filter(
+      (match) =>
+        match.data !== undefined && isFreshBatchData(match.dataUpdatedAt),
+    )
+    .sort((left, right) => right.dataUpdatedAt - left.dataUpdatedAt)[0]
+
+  if (freshestBatchMatch?.data) {
+    return findTokenPrice(freshestBatchMatch.data, tokenKey) ?? null
+  }
+
+  const prices = await fetchTokenPrices(trailsClient, [token])
+  return prices[0] ?? null
+}
+
+function matchesTokenPriceQuery(queryKey: QueryKey, tokenKey: string): boolean {
+  if (queryKey[0] !== PRICE_SCOPE) {
+    return false
+  }
+
+  if (queryKey[1] === PRICE_SINGLE_SCOPE) {
+    return queryKey[2] === tokenKey
+  }
+
+  const batchTokens = getBatchQueryTokens(queryKey)
+  return (
+    batchTokens?.some(
+      (batchToken) => createTokenCacheKey(batchToken) === tokenKey,
+    ) ?? false
+  )
+}
+
+export const priceQueries = {
+  all: [PRICE_SCOPE] as const,
+  batch: () => [...priceQueries.all, PRICE_BATCH_SCOPE] as const,
+  single: () => [...priceQueries.all, PRICE_SINGLE_SCOPE] as const,
+  byTokens: (
+    tokens: Token[],
+    trailsClient: TrailsClient | null | undefined,
+    queryClient: QueryClient = defaultQueryClient,
+  ) => {
+    const normalizedTokens = normalizeTokensForQuery(tokens)
+    const canFetch = normalizedTokens.length > 0 && !!trailsClient
+
+    return queryOptions<TokenPrice[]>({
+      queryKey: [...priceQueries.batch(), normalizedTokens] as const,
+      queryFn: canFetch
+        ? async () => {
+            if (!trailsClient) {
+              throw new Error("Trails client is required")
+            }
+
+            const prices = await fetchTokenPrices(
+              trailsClient,
+              normalizedTokens,
+            )
+
+            seedSingleTokenPriceQueries({
+              queryClient,
+              trailsClient,
+              tokens: normalizedTokens,
+              prices,
+            })
+
+            return prices
+          }
+        : skipToken,
+      staleTime: PRICE_STALE_MS,
+      gcTime: PRICE_GC_MS,
+      retry: createRetry(2),
+      retryDelay,
+      persister: queryPersister.persisterFn,
+    })
+  },
+  byToken: (
+    token: Token | null | undefined,
+    trailsClient: TrailsClient | null | undefined,
+    queryClient: QueryClient = defaultQueryClient,
+  ) => {
+    const normalizedToken = token ? normalizeToken(token) : null
+    const tokenKey = normalizedToken
+      ? createTokenCacheKey(normalizedToken)
+      : null
+    const canFetch = !!normalizedToken && !!trailsClient
+
+    return queryOptions<TokenPrice | null>({
+      queryKey: [...priceQueries.single(), tokenKey] as const,
+      queryFn: canFetch
+        ? async () => {
+            if (!normalizedToken || !trailsClient) {
+              throw new Error(
+                "Token price query requires a token and Trails client",
+              )
+            }
+
+            return fetchTokenPriceWithBatchReuse({
+              queryClient,
+              trailsClient,
+              token: normalizedToken,
+            })
+          }
+        : skipToken,
+      staleTime: PRICE_STALE_MS,
+      gcTime: PRICE_GC_MS,
+      retry: createRetry(2),
+      retryDelay,
+      persister: queryPersister.persisterFn,
+    })
+  },
+}
+
+export function invalidateTokenPricesCache(token?: Token, qc?: QueryClient) {
+  const client = qc ?? defaultQueryClient
+
+  if (!token) {
+    return client.invalidateQueries({
+      queryKey: priceQueries.all,
+    })
+  }
+
+  const tokenKey = createTokenCacheKey(normalizeToken(token))
+
+  return client.invalidateQueries({
+    predicate: (query) => matchesTokenPriceQuery(query.queryKey, tokenKey),
+  })
+}
+
+export async function getTokenPrice(
+  trailsClient: TrailsClient,
+  token: Token,
+): Promise<TokenPrice | null> {
+  return defaultQueryClient.ensureQueryData(
+    priceQueries.byToken(token, trailsClient, defaultQueryClient),
+  )
+}
+
+export async function getTokenPrices(
+  trailsClient: TrailsClient,
+  tokens: Token[],
+): Promise<TokenPrice[]> {
+  if (tokens.length === 0) return []
+  return defaultQueryClient.ensureQueryData(
+    priceQueries.byTokens(tokens, trailsClient, defaultQueryClient),
+  )
+}

package/src/query/tokenList.queries.ts

@@ -0,0 +1,118 @@
+import { queryOptions, skipToken } from "@tanstack/react-query"
+import type { TrailsClient } from "../trailsClient.js"
+import { DAY_MS, MINUTE_MS, SECOND_MS } from "../utils/time.js"
+import { createRetry, retryDelay, STATIC_QUERY_OPTIONS } from "./helpers.js"
+
+type TokenListResult = {
+  tokens: unknown[]
+}
+
+const EMPTY_RESULT: TokenListResult = { tokens: [] }
+
+export const tokenListQueries = {
+  all: ["tokenList"] as const,
+
+  catalog: (
+    trailsClient: TrailsClient | null | undefined,
+    config: { trailsApiUrl?: string; trailsApiKey?: string },
+    params: { chainIds: number[]; includeAllListed?: boolean; limit?: number },
+  ) => {
+    const hasChains = params.chainIds.length > 0
+    const canFetch = !!trailsClient && !!config.trailsApiKey && hasChains
+    return queryOptions<TokenListResult>({
+      queryKey: [
+        ...tokenListQueries.all,
+        "catalog",
+        [...params.chainIds].sort((a, b) => a - b).join(","),
+        params.includeAllListed ?? true,
+        params.limit ?? null,
+      ] as const,
+      queryFn: canFetch
+        ? async () => {
+            return (await trailsClient.getTokenList({
+              chainIds: params.chainIds,
+              includeAllListed: params.includeAllListed ?? true,
+              limit: params.limit,
+            })) as TokenListResult
+          }
+        : skipToken,
+      staleTime: DAY_MS,
+      gcTime: DAY_MS,
+      retry: createRetry(2),
+      retryDelay,
+      ...STATIC_QUERY_OPTIONS,
+    })
+  },
+
+  search: (
+    trailsClient: TrailsClient | null | undefined,
+    config: { trailsApiUrl?: string; trailsApiKey?: string },
+    params: { searchQuery: string; chainIds: number[]; limit?: number },
+  ) => {
+    const searchQuery = params.searchQuery.trim()
+    const canFetch =
+      !!trailsClient &&
+      !!config.trailsApiKey &&
+      searchQuery.length > 0 &&
+      params.chainIds.length > 0
+
+    return queryOptions<TokenListResult>({
+      queryKey: [
+        ...tokenListQueries.all,
+        "search",
+        searchQuery,
+        [...params.chainIds].sort((a, b) => a - b).join(","),
+        params.limit ?? 30,
+      ] as const,
+      queryFn: canFetch
+        ? async () => {
+            return (await trailsClient.getTokenList({
+              searchQuery,
+              chainIds: params.chainIds,
+              includeAllListed: true,
+              limit: params.limit ?? 30,
+            })) as TokenListResult
+          }
+        : skipToken,
+      staleTime: 30 * SECOND_MS,
+      gcTime: 5 * MINUTE_MS,
+      retry: createRetry(1),
+      retryDelay,
+      refetchOnWindowFocus: false,
+      refetchOnReconnect: false,
+    })
+  },
+
+  byChain: (
+    trailsClient: TrailsClient | null | undefined,
+    config: { trailsApiUrl?: string; trailsApiKey?: string },
+    params: { chainId: number | null; limit?: number },
+  ) => {
+    const canFetch =
+      !!trailsClient && !!config.trailsApiKey && params.chainId != null
+    return queryOptions<TokenListResult>({
+      queryKey: [
+        ...tokenListQueries.all,
+        "byChain",
+        params.chainId,
+        params.limit ?? 100,
+      ] as const,
+      queryFn: canFetch
+        ? async () => {
+            return (await trailsClient.getTokenList({
+              chainIds: [params.chainId as number],
+              includeAllListed: true,
+              limit: params.limit ?? 100,
+            })) as TokenListResult
+          }
+        : skipToken,
+      staleTime: DAY_MS,
+      gcTime: DAY_MS,
+      retry: createRetry(2),
+      retryDelay,
+      ...STATIC_QUERY_OPTIONS,
+    })
+  },
+
+  empty: EMPTY_RESULT,
+}