@lifi/widget 4.7.1 → 4.8.0

package/src/hooks/useTokenBalancesQueries.ts

@@ -20,7 +20,7 @@ export const useTokenBalancesQueries = (
   isLoading: boolean
   isError: boolean
 } => {
-  const { keyPrefix } = useWidgetConfig()
+  const { storageScopeKey } = useWidgetConfig()
   const sdkClient = useSDKClient()
   const firstLoadStartRef = useRef<number | null>(null)
 
@@ -34,7 +34,7 @@ export const useTokenBalancesQueries = (
           const chainId = Number(chainIdStr)
           return {
             queryKey: [
-              getQueryKey('token-balances', keyPrefix),
+              getQueryKey('token-balances', storageScopeKey),
               accountAddress,
               chainId,
               tokens.length,
@@ -55,7 +55,7 @@ export const useTokenBalancesQueries = (
           }
         })
     )
-  }, [accountsWithTokens, isBalanceLoadingEnabled, keyPrefix, sdkClient])
+  }, [accountsWithTokens, isBalanceLoadingEnabled, storageScopeKey, sdkClient])
 
   const result = useQueries({
     queries: queryConfig,

package/src/hooks/useTokenSearch.ts

@@ -18,11 +18,15 @@ export const useTokenSearch = (
   isLoading: boolean
 } => {
   const queryClient = useQueryClient()
-  const { tokens: configTokens, keyPrefix } = useWidgetConfig()
+  const { tokens: configTokens, storageScopeKey } = useWidgetConfig()
   const sdkClient = useSDKClient()
 
   const { data, isLoading } = useQuery({
-    queryKey: [getQueryKey('token-search', keyPrefix), chainId, tokenQuery],
+    queryKey: [
+      getQueryKey('token-search', storageScopeKey),
+      chainId,
+      tokenQuery,
+    ],
     queryFn: async ({ queryKey: [, chainId, tokenQuery], signal }) => {
       const token = await getToken(
         sdkClient,
@@ -52,7 +56,7 @@ export const useTokenSearch = (
 
         // Add token to main tokens cache
         queryClient.setQueriesData<TokensByChain>(
-          { queryKey: [getQueryKey('tokens', keyPrefix)] },
+          { queryKey: [getQueryKey('tokens', storageScopeKey)] },
           (data) => {
             if (!data) {
               return data

package/src/hooks/useTokens.ts

@@ -25,6 +25,14 @@ import { useAvailableChains } from './useAvailableChains.js'
 
 const refetchInterval = 300_000
 
+// The main list and the search send the same list parameters.
+const tokenListParams = {
+  orderBy: 'volumeUSD24H',
+  extended: true,
+  limit: 1100,
+  minPriceUSD: 0.000001,
+} as const
+
 export const useTokens = (
   formType?: FormType,
   search?: string,
@@ -39,7 +47,7 @@ export const useTokens = (
   const {
     tokens: configTokens,
     chains: chainsConfig,
-    keyPrefix,
+    storageScopeKey,
   } = useWidgetConfig()
   const sdkClient = useSDKClient()
   const { getChainTypeFromTokenAddress } = useChainTypeFromAddress()
@@ -55,7 +63,7 @@ export const useTokens = (
 
   // Main tokens cache - verified tokens from API
   const { data: verifiedTokens, isLoading } = useQuery({
-    queryKey: [getQueryKey('tokens', keyPrefix)],
+    queryKey: [getQueryKey('tokens', storageScopeKey)],
     queryFn: async ({ signal }) => {
       const chainTypes = [
         ChainType.EVM,
@@ -68,13 +76,7 @@ export const useTokens = (
 
       const tokensResponse: TokensExtendedResponse = await getTokens(
         sdkClient,
-        {
-          chainTypes,
-          orderBy: 'volumeUSD24H',
-          extended: true,
-          limit: 1000,
-          minPriceUSD: 0.000001,
-        },
+        { ...tokenListParams, chainTypes },
         { signal }
       )
 
@@ -95,7 +97,7 @@ export const useTokens = (
   // Search tokens cache - unverified tokens from search
   const { data: searchTokens, isLoading: isSearchLoading } = useQuery({
     queryKey: [
-      getQueryKey('tokens-search', keyPrefix),
+      getQueryKey('tokens-search', storageScopeKey),
       trimmedSearch,
       chainId,
       isAddressSearch,
@@ -114,12 +116,9 @@ export const useTokens = (
       const tokensResponse: TokensExtendedResponse = await getTokens(
         sdkClient,
         {
+          ...tokenListParams,
           chainTypes,
-          orderBy: 'volumeUSD24H',
-          extended: true,
           search: searchQuery,
-          limit: 1000,
-          minPriceUSD: 0.000001,
         },
         { signal }
       )

package/src/hooks/useTools.sharedEntry.test.tsx

@@ -0,0 +1,155 @@
+/** @vitest-environment happy-dom */
+
+import type * as LifiSdk from '@lifi/sdk'
+import type { SDKClient, ToolsResponse } from '@lifi/sdk'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { WidgetConfig } from '../types/widget.js'
+
+/**
+ * The tools entry is shared with the host app through
+ * `getToolsQueryOptions`, keyed by the client's API base and the widget's
+ * `queryScopeKey`. When the host fetched first, the widget must read that entry
+ * — no request of its own — and still seed its settings store from the
+ * filtered view.
+ */
+
+const API_URL = 'https://api.example/v1'
+
+const mocks = vi.hoisted(() => ({
+  getTools: vi.fn(),
+  initializeTools: vi.fn(),
+}))
+
+vi.mock('@lifi/sdk', async (importOriginal) => ({
+  ...(await importOriginal<typeof LifiSdk>()),
+  getTools: mocks.getTools,
+}))
+
+let widgetConfig: Partial<WidgetConfig> = {}
+
+vi.mock('../providers/WidgetProvider/WidgetProvider.js', () => ({
+  useWidgetConfig: () => widgetConfig,
+}))
+
+const client = { config: { apiUrl: API_URL } } as unknown as SDKClient
+vi.mock('../providers/SDKClientProvider.js', () => ({
+  useSDKClient: () => client,
+}))
+
+const settingsStore = {
+  getState: () => ({ initializeTools: mocks.initializeTools }),
+}
+vi.mock('../stores/settings/SettingsStore.js', () => ({
+  useSettingsStoreContext: () => settingsStore,
+}))
+
+import { getToolsQueryKey } from '../queries/getTools.js'
+import { useTools } from './useTools.js'
+
+const TOOLS = {
+  bridges: [{ key: 'across' }, { key: 'stargate' }, { key: 'hop' }],
+  exchanges: [{ key: '1inch' }, { key: 'paraswap' }],
+} as unknown as ToolsResponse
+
+const Probe = () => {
+  useTools()
+  return null
+}
+
+let root: Root
+let queryClient: QueryClient
+
+const render = async () => {
+  await act(async () => {
+    root.render(
+      <QueryClientProvider client={queryClient}>
+        <Probe />
+      </QueryClientProvider>
+    )
+  })
+}
+
+describe('useTools with a shared tools entry', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mocks.getTools.mockResolvedValue(TOOLS)
+    widgetConfig = {
+      integrator: 'test',
+      queryScopeKey: 'host',
+      bridges: { allow: ['across', 'hop'] },
+      exchanges: { deny: ['paraswap'] },
+    }
+    queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    })
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    root = createRoot(container)
+  })
+
+  afterEach(async () => {
+    await act(async () => root.unmount())
+    queryClient.clear()
+  })
+
+  it('initialises the settings store when the host already fetched the tools', async () => {
+    // The host app fetched first and filled the shared entry.
+    queryClient.setQueryData(
+      getToolsQueryKey({ apiUrl: API_URL, scopeKey: 'host' }),
+      TOOLS
+    )
+
+    await render()
+
+    await vi.waitFor(() => {
+      expect(mocks.initializeTools).toHaveBeenCalledWith('Bridges', [
+        'across',
+        'hop',
+      ])
+    })
+    expect(mocks.initializeTools).toHaveBeenCalledWith('Exchanges', ['1inch'])
+    // The widget read the host's entry instead of sending its own request.
+    expect(mocks.getTools).not.toHaveBeenCalled()
+  })
+
+  it('initialises the settings store when the widget fetched the tools itself', async () => {
+    await render()
+
+    await vi.waitFor(() => {
+      expect(mocks.initializeTools).toHaveBeenCalledWith('Bridges', [
+        'across',
+        'hop',
+      ])
+    })
+    expect(mocks.getTools).toHaveBeenCalledTimes(1)
+  })
+
+  it('initialises with the filtered view while the cache keeps the raw list', async () => {
+    await render()
+
+    await vi.waitFor(() => {
+      expect(mocks.initializeTools).toHaveBeenCalled()
+    })
+    const cached = queryClient.getQueryData<ToolsResponse>(
+      getToolsQueryKey({ apiUrl: API_URL, scopeKey: 'host' })
+    )
+    expect(cached?.bridges).toHaveLength(3)
+    expect(cached?.exchanges).toHaveLength(2)
+  })
+
+  it('refreshes the tools every three minutes', async () => {
+    await render()
+    await vi.waitFor(() => {
+      expect(mocks.initializeTools).toHaveBeenCalled()
+    })
+
+    const [observer] = queryClient.getQueryCache().find({
+      queryKey: getToolsQueryKey({ apiUrl: API_URL, scopeKey: 'host' }),
+    })!.observers
+    expect(observer.options.refetchInterval).toBe(180_000)
+    expect(observer.options.staleTime).toBe(180_000)
+  })
+})

package/src/hooks/useTools.ts

@@ -1,56 +1,61 @@
-import { getTools, type ToolsResponse } from '@lifi/sdk'
+import type { ToolsResponse } from '@lifi/sdk'
 import { useQuery } from '@tanstack/react-query'
+import { useCallback, useEffect } from 'react'
 import { useSDKClient } from '../providers/SDKClientProvider.js'
 import { useWidgetConfig } from '../providers/WidgetProvider/WidgetProvider.js'
+import { getToolsQueryOptions } from '../queries/getTools.js'
 import { useSettingsStoreContext } from '../stores/settings/SettingsStore.js'
 import { getConfigItemSets, isItemAllowedForSets } from '../utils/item.js'
-import { getQueryKey } from '../utils/queries.js'
+
+const refetchInterval = 180_000
 
 export const useTools = (): { tools: ToolsResponse | undefined } => {
-  const { bridges, exchanges, keyPrefix } = useWidgetConfig()
+  const { bridges, exchanges, queryScopeKey } = useWidgetConfig()
   const settingsStore = useSettingsStoreContext()
   const sdkClient = useSDKClient()
 
-  const { data } = useQuery({
-    queryKey: [
-      getQueryKey('tools', keyPrefix),
-      bridges?.allow,
-      bridges?.deny,
-      exchanges?.allow,
-      exchanges?.deny,
-    ],
-    queryFn: async (): Promise<ToolsResponse> => {
-      const tools = await getTools(sdkClient)
-      const bridgesConfigSets = getConfigItemSets(
-        bridges,
-        (bridges) => new Set(bridges)
-      )
-      const exchangesConfigSets = getConfigItemSets(
-        exchanges,
-        (exchanges) => new Set(exchanges)
-      )
-      const result = {
+  const selectAllowedTools = useCallback(
+    (tools: ToolsResponse): ToolsResponse => {
+      const bridgeSets = getConfigItemSets(bridges, (keys) => new Set(keys))
+      const exchangeSets = getConfigItemSets(exchanges, (keys) => new Set(keys))
+      return {
         bridges: tools.bridges.filter((bridge) =>
-          isItemAllowedForSets(bridge.key, bridgesConfigSets)
+          isItemAllowedForSets(bridge.key, bridgeSets)
         ),
         exchanges: tools.exchanges.filter((exchange) =>
-          isItemAllowedForSets(exchange.key, exchangesConfigSets)
+          isItemAllowedForSets(exchange.key, exchangeSets)
         ),
       }
-      const { initializeTools } = settingsStore.getState()
-      initializeTools(
-        'Bridges',
-        result.bridges.map((bridge) => bridge.key)
-      )
-      initializeTools(
-        'Exchanges',
-        result.exchanges.map((exchange) => exchange.key)
-      )
-      return result
     },
-    refetchInterval: 180_000,
-    staleTime: 180_000,
-  })
+    [bridges, exchanges]
+  )
+
+  const { data } = useQuery(
+    getToolsQueryOptions(sdkClient, {
+      scopeKey: queryScopeKey,
+      query: {
+        refetchInterval,
+        staleTime: refetchInterval,
+        select: selectAllowedTools,
+      },
+    })
+  )
+
+  // A host may fill the shared entry, so seed from the data, not in a queryFn.
+  useEffect(() => {
+    if (!data) {
+      return
+    }
+    const { initializeTools } = settingsStore.getState()
+    initializeTools(
+      'Bridges',
+      data.bridges.map((bridge) => bridge.key)
+    )
+    initializeTools(
+      'Exchanges',
+      data.exchanges.map((exchange) => exchange.key)
+    )
+  }, [data, settingsStore])
 
   return { tools: data }
 }

package/src/hooks/useTransactionDetails.ts

@@ -19,12 +19,12 @@ export const useTransactionDetails = (
 } => {
   const { account, accounts } = useAccount()
   const queryClient = useQueryClient()
-  const { keyPrefix } = useWidgetConfig()
+  const { storageScopeKey } = useWidgetConfig()
   const sdkClient = useSDKClient()
 
   const transactionHistoryQueryKey = useMemo(
-    () => getQueryKey('transaction-history', keyPrefix),
-    [keyPrefix]
+    () => getQueryKey('transaction-history', storageScopeKey),
+    [storageScopeKey]
   )
 
   const { data, isLoading } = useQuery({

package/src/hooks/useTransactionHistory.ts

@@ -22,14 +22,14 @@ export const useTransactionHistory = (): {
 } => {
   const store = useRouteExecutionStoreContext()
   const { accounts } = useAccount()
-  const { keyPrefix } = useWidgetConfig()
+  const { storageScopeKey } = useWidgetConfig()
   const sdkClient = useSDKClient()
   const { tools } = useTools()
 
   const { data: routeExecutions, isLoading } = useQueries({
     queries: accounts.map((account) => ({
       queryKey: [
-        getQueryKey('transaction-history', keyPrefix),
+        getQueryKey('transaction-history', storageScopeKey),
         account.address,
       ],
       queryFn: (async ({ queryKey: [, accountAddress], signal }) => {

package/src/index.ts

@@ -8,13 +8,14 @@ export * from './components/ContractComponent/NFT/NFTBase.js'
 export * from './components/ContractComponent/NFT/types.js'
 export * from './components/Skeleton/WidgetSkeleton.js'
 export { defaultMaxHeight } from './config/constants.js'
-export * from './config/version.js'
+export { name, version } from './config/version.js'
 export { useWidgetChains } from './hooks/useWidgetChains.js'
 export {
   useWidgetEvents,
   type WidgetEventEmitter,
   widgetEvents,
 } from './hooks/useWidgetEvents.js'
+export * from './queries/index.js'
 export * from './stores/bookmarks/types.js'
 export * from './stores/form/types.js'
 export { useFieldActions } from './stores/form/useFieldActions.js'

package/src/providers/WidgetProvider/WidgetProvider.test.tsx

@@ -0,0 +1,73 @@
+/** @vitest-environment happy-dom */
+
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { WidgetConfig } from '../../types/widget.js'
+import type { WidgetContextProps } from './types.js'
+
+const settingsActions = { setDefaultSettings: vi.fn() }
+vi.mock('../../stores/settings/useSettingsActions.js', () => ({
+  useSettingsActions: () => settingsActions,
+}))
+
+import { useWidgetConfig, WidgetProvider } from './WidgetProvider.js'
+
+let root: Root
+let seen: WidgetContextProps | undefined
+
+const Probe = () => {
+  seen = useWidgetConfig()
+  return null
+}
+
+const render = async (config: WidgetConfig) => {
+  await act(async () => {
+    root.render(
+      <WidgetProvider config={config}>
+        <Probe />
+      </WidgetProvider>
+    )
+  })
+}
+
+describe('WidgetProvider scope keys', () => {
+  beforeEach(() => {
+    seen = undefined
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    root = createRoot(container)
+  })
+
+  afterEach(async () => {
+    await act(async () => root.unmount())
+  })
+
+  // An integration that only ever set the deprecated keyPrefix keeps its
+  // isolation: everything below reads the resolved keys, never keyPrefix.
+  it('resolves both scopes from keyPrefix alone', async () => {
+    await render({ integrator: 'test', keyPrefix: 'legacy' })
+
+    expect(seen?.storageScopeKey).toBe('legacy')
+    expect(seen?.queryScopeKey).toBe('legacy')
+  })
+
+  it('prefers the explicit scopes over keyPrefix', async () => {
+    await render({
+      integrator: 'test',
+      keyPrefix: 'legacy',
+      storageScopeKey: 'store',
+      queryScopeKey: 'query',
+    })
+
+    expect(seen?.storageScopeKey).toBe('store')
+    expect(seen?.queryScopeKey).toBe('query')
+  })
+
+  it('keeps the historical storage names and the default query scope when nothing is set', async () => {
+    await render({ integrator: 'test' })
+
+    expect(seen?.storageScopeKey).toBeUndefined()
+    expect(seen?.queryScopeKey).toBe('li.fi')
+  })
+})

package/src/providers/WidgetProvider/WidgetProvider.tsx

@@ -1,11 +1,17 @@
 import type { Context } from 'react'
 import { createContext, use, useId, useMemo } from 'react'
 import { useSettingsActions } from '../../stores/settings/useSettingsActions.js'
+import {
+  defaultQueryScopeKey,
+  resolveQueryScopeKey,
+  resolveStorageScopeKey,
+} from '../../utils/scopeKeys.js'
 import type { WidgetContextProps, WidgetProviderProps } from './types.js'
 
 const initialContext: WidgetContextProps = {
   elementId: '',
   integrator: '',
+  queryScopeKey: defaultQueryScopeKey,
 }
 
 export const WidgetContext: Context<WidgetContextProps> =
@@ -24,10 +30,16 @@ export const WidgetProvider: React.FC<
   }
 
   const value = useMemo((): WidgetContextProps => {
+    // Resolved once, so nothing below reads the deprecated keyPrefix.
+    const scopeKeys = {
+      storageScopeKey: resolveStorageScopeKey(widgetConfig),
+      queryScopeKey: resolveQueryScopeKey(widgetConfig),
+    }
     try {
       // Create widget configuration object
       const value = {
         ...widgetConfig,
+        ...scopeKeys,
         elementId,
       } as WidgetContextProps
 
@@ -39,6 +51,7 @@ export const WidgetProvider: React.FC<
       console.warn(e)
       return {
         ...widgetConfig,
+        ...scopeKeys,
         elementId,
         integrator: widgetConfig.integrator,
       }

package/src/providers/WidgetProvider/types.ts

@@ -2,6 +2,8 @@ import type { WidgetConfig } from '../../types/widget.js'
 
 export type WidgetContextProps = WidgetConfig & {
   elementId: string
+  /** Always resolved by `WidgetProvider` — see `resolveQueryScopeKey`. */
+  queryScopeKey: string
 }
 
 export interface WidgetProviderProps {

package/src/queries/getChains.ts

@@ -0,0 +1,93 @@
+import type { ExtendedChain, SDKClient } from '@lifi/sdk'
+import { ChainType, getChains } from '@lifi/sdk'
+import type {
+  FactoryQueryOptions,
+  QueryParameter,
+  ScopeKeyParameter,
+} from './types.js'
+
+/** Every chain type the widget supports, in the order keys are built in. */
+export const supportedChainTypes: readonly ChainType[] = [
+  ChainType.EVM,
+  ChainType.SVM,
+  ChainType.UTXO,
+  ChainType.MVM,
+  ChainType.TVM,
+  ChainType.STL,
+]
+
+export type GetChainsQueryFnData = ExtendedChain[]
+
+export type GetChainsQueryKeyParameters = {
+  /** API base the client talks to. Different bases return different chains. */
+  apiUrl: string
+  chainTypes: readonly ChainType[]
+} & ScopeKeyParameter
+
+export type GetChainsQueryKey = readonly [
+  'chains',
+  { apiUrl: string; chainTypes: ChainType[]; scopeKey?: string },
+]
+
+const rank = (type: ChainType): number => {
+  const index = supportedChainTypes.indexOf(type)
+  return index === -1 ? supportedChainTypes.length : index
+}
+
+/** The key alone — to read, set or invalidate the entry. */
+export function getChainsQueryKey(
+  parameters: GetChainsQueryKeyParameters
+): GetChainsQueryKey {
+  // Array order is part of the query hash, so sort into one canonical order.
+  const chainTypes = [...new Set(parameters.chainTypes)].sort(
+    (a, b) => rank(a) - rank(b) || a.localeCompare(b)
+  )
+  return [
+    'chains',
+    {
+      apiUrl: parameters.apiUrl,
+      chainTypes,
+      ...(parameters.scopeKey === undefined
+        ? {}
+        : { scopeKey: parameters.scopeKey }),
+    },
+  ]
+}
+
+export type GetChainsOptions<selectData = GetChainsQueryFnData> = {
+  /** Chain types to request, in any order. Defaults to every supported type. */
+  chainTypes?: readonly ChainType[] | undefined
+} & ScopeKeyParameter &
+  QueryParameter<GetChainsQueryFnData, selectData, GetChainsQueryKey>
+
+export type GetChainsQueryOptions<selectData = GetChainsQueryFnData> =
+  FactoryQueryOptions<GetChainsQueryFnData, selectData, GetChainsQueryKey>
+
+/**
+ * Query options for the chain list of one API base.
+ *
+ * The key is `['chains', { apiUrl, chainTypes, scopeKey }]`: the API base and
+ * the requested types decide the response, the scope isolates integrations.
+ * The widget and a host app that build their options here, with the same
+ * scope, therefore share one cache entry and one request.
+ *
+ * The query has no side effects. A caller that needs the chains in its SDK
+ * client's storage calls `client.setChains` on the data — the entry may have
+ * been filled by another caller, so a `queryFn` cannot be relied on to run.
+ */
+export function getChainsQueryOptions<selectData = GetChainsQueryFnData>(
+  client: SDKClient,
+  options: GetChainsOptions<selectData> = {}
+): GetChainsQueryOptions<selectData> {
+  return {
+    ...options.query,
+    queryKey: getChainsQueryKey({
+      apiUrl: client.config.apiUrl,
+      chainTypes: options.chainTypes ?? supportedChainTypes,
+      scopeKey: options.scopeKey,
+    }),
+    // No signal: the data still fills the cache if all observers leave.
+    queryFn: ({ queryKey: [, { chainTypes }] }) =>
+      getChains(client, { chainTypes }),
+  }
+}