@lifi/widget 4.7.1 → 4.8.0

package/src/queries/getTools.ts

@@ -0,0 +1,62 @@
+import type { SDKClient, ToolsResponse } from '@lifi/sdk'
+import { getTools } from '@lifi/sdk'
+import type {
+  FactoryQueryOptions,
+  QueryParameter,
+  ScopeKeyParameter,
+} from './types.js'
+
+export type GetToolsQueryFnData = ToolsResponse
+
+export type GetToolsQueryKeyParameters = {
+  /** API base the client talks to. Different bases return different tools. */
+  apiUrl: string
+} & ScopeKeyParameter
+
+export type GetToolsQueryKey = readonly [
+  'tools',
+  { apiUrl: string; scopeKey?: string },
+]
+
+/** The key alone — to read, set or invalidate the entry. */
+export function getToolsQueryKey(
+  parameters: GetToolsQueryKeyParameters
+): GetToolsQueryKey {
+  return [
+    'tools',
+    {
+      apiUrl: parameters.apiUrl,
+      ...(parameters.scopeKey === undefined
+        ? {}
+        : { scopeKey: parameters.scopeKey }),
+    },
+  ]
+}
+
+export type GetToolsOptions<selectData = GetToolsQueryFnData> =
+  ScopeKeyParameter &
+    QueryParameter<GetToolsQueryFnData, selectData, GetToolsQueryKey>
+
+export type GetToolsQueryOptions<selectData = GetToolsQueryFnData> =
+  FactoryQueryOptions<GetToolsQueryFnData, selectData, GetToolsQueryKey>
+
+/**
+ * Query options for the bridges and exchanges of one API base.
+ *
+ * The key is `['tools', { apiUrl, scopeKey }]`. The cache holds the raw,
+ * unfiltered response so every caller can share it; narrow it per caller with
+ * `query.select`, never in the `queryFn`.
+ */
+export function getToolsQueryOptions<selectData = GetToolsQueryFnData>(
+  client: SDKClient,
+  options: GetToolsOptions<selectData> = {}
+): GetToolsQueryOptions<selectData> {
+  return {
+    ...options.query,
+    queryKey: getToolsQueryKey({
+      apiUrl: client.config.apiUrl,
+      scopeKey: options.scopeKey,
+    }),
+    queryFn: ({ signal }) => getTools(client, undefined, { signal }),
+  }
+}

package/src/queries/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Query option factories for LI.FI server data, shared by the widget and its
+ * host. Published as `@lifi/widget/queries`; it depends only on
+ * `@lifi/sdk` and on `@tanstack/react-query` types, so importing it does not
+ * pull in the widget itself.
+ *
+ * Keys follow wagmi's `@wagmi/core/query` convention: `[name, parameters]`,
+ * where the parameters hold everything that changes the response plus an
+ * optional `scopeKey`.
+ */
+export {
+  type GetChainsOptions,
+  type GetChainsQueryFnData,
+  type GetChainsQueryKey,
+  type GetChainsQueryKeyParameters,
+  type GetChainsQueryOptions,
+  getChainsQueryKey,
+  getChainsQueryOptions,
+  supportedChainTypes,
+} from './getChains.js'
+export {
+  type GetToolsOptions,
+  type GetToolsQueryFnData,
+  type GetToolsQueryKey,
+  type GetToolsQueryKeyParameters,
+  type GetToolsQueryOptions,
+  getToolsQueryKey,
+  getToolsQueryOptions,
+} from './getTools.js'
+export type { QueryParameter, ScopeKeyParameter } from './types.js'

package/src/queries/sharedCache.test.tsx

@@ -0,0 +1,223 @@
+/** @vitest-environment happy-dom */
+
+import type * as LifiSdk from '@lifi/sdk'
+import type { SDKClient, ToolsResponse } from '@lifi/sdk'
+import { ChainType } from '@lifi/sdk'
+import {
+  QueryClient,
+  QueryClientProvider,
+  useQuery,
+} from '@tanstack/react-query'
+import type { ReactNode } from 'react'
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+/**
+ * A host app and the widget that both build
+ * their options from these factories, inside one QueryClient, send each
+ * request once — whether they mount together or seconds apart.
+ */
+
+const mocks = vi.hoisted(() => ({
+  getChains: vi.fn(),
+  getTools: vi.fn(),
+}))
+
+vi.mock('@lifi/sdk', async (importOriginal) => ({
+  ...(await importOriginal<typeof LifiSdk>()),
+  getChains: mocks.getChains,
+  getTools: mocks.getTools,
+}))
+
+import { getChainsQueryOptions } from './getChains.js'
+import { getToolsQueryOptions } from './getTools.js'
+
+const V1 = 'https://api.example/v1'
+const OTHER_BASE = 'https://api-b.example/v1'
+const clientFor = (apiUrl: string) =>
+  ({ config: { apiUrl } }) as unknown as SDKClient
+
+const TOOLS = {
+  bridges: [{ key: 'across' }, { key: 'stargate' }],
+  exchanges: [{ key: '1inch' }],
+} as unknown as ToolsResponse
+
+/** A host app: all chain types, its own refresh cadence. */
+const Host = ({
+  client,
+  scopeKey,
+}: {
+  client: SDKClient
+  scopeKey: string
+}) => {
+  useQuery(
+    getChainsQueryOptions(client, {
+      scopeKey,
+      query: { staleTime: 300_000 },
+    })
+  )
+  useQuery(
+    getToolsQueryOptions(client, { scopeKey, query: { staleTime: 300_000 } })
+  )
+  return null
+}
+
+/** What the widget does: chain types in another order, a filtered tools view. */
+const Widget = ({
+  client,
+  scopeKey,
+}: {
+  client: SDKClient
+  scopeKey: string
+}) => {
+  useQuery(
+    getChainsQueryOptions(client, {
+      chainTypes: [
+        ChainType.STL,
+        ChainType.TVM,
+        ChainType.MVM,
+        ChainType.UTXO,
+        ChainType.SVM,
+        ChainType.EVM,
+      ],
+      scopeKey,
+      query: { staleTime: 300_000 },
+    })
+  )
+  useQuery(
+    getToolsQueryOptions(client, {
+      scopeKey,
+      query: {
+        staleTime: 180_000,
+        select: (tools) => ({ ...tools, bridges: tools.bridges.slice(0, 1) }),
+      },
+    })
+  )
+  return null
+}
+
+let root: Root
+let queryClient: QueryClient
+
+const render = async (node: ReactNode) => {
+  await act(async () => {
+    root.render(
+      <QueryClientProvider client={queryClient}>{node}</QueryClientProvider>
+    )
+  })
+}
+
+const settle = () =>
+  vi.waitFor(() => {
+    expect(queryClient.isFetching()).toBe(0)
+  })
+
+describe('shared chains and tools cache', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mocks.getChains.mockResolvedValue([{ id: 1 }])
+    mocks.getTools.mockResolvedValue(TOOLS)
+    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('fetches once when the host and the widget mount together', async () => {
+    const client = clientFor(V1)
+
+    await render(
+      <>
+        <Host client={client} scopeKey="host" />
+        <Widget client={client} scopeKey="host" />
+      </>
+    )
+    await settle()
+
+    expect(mocks.getChains).toHaveBeenCalledTimes(1)
+    expect(mocks.getTools).toHaveBeenCalledTimes(1)
+  })
+
+  // A widget often mounts seconds after the host app. A later observer with a
+  // staleTime reads the entry instead of refetching it.
+  it('fetches once when the widget mounts after the host has settled', async () => {
+    const client = clientFor(V1)
+
+    await render(<Host client={client} scopeKey="host" />)
+    await settle()
+    await render(
+      <>
+        <Host client={client} scopeKey="host" />
+        <Widget client={client} scopeKey="host" />
+      </>
+    )
+    await settle()
+
+    expect(mocks.getChains).toHaveBeenCalledTimes(1)
+    expect(mocks.getTools).toHaveBeenCalledTimes(1)
+  })
+
+  it('also shares when the host and widget hold different client objects on the same base', async () => {
+    await render(
+      <>
+        <Host client={clientFor(V1)} scopeKey="host" />
+        <Widget client={clientFor(V1)} scopeKey="host" />
+      </>
+    )
+    await settle()
+
+    expect(mocks.getChains).toHaveBeenCalledTimes(1)
+    expect(mocks.getTools).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps the raw tools response in the cache under a filtering select', async () => {
+    const client = clientFor(V1)
+
+    await render(<Widget client={client} scopeKey="host" />)
+    await settle()
+
+    const cached = queryClient.getQueryData<ToolsResponse>(
+      getToolsQueryOptions(client, { scopeKey: 'host' }).queryKey
+    )
+    expect(cached?.bridges).toHaveLength(2)
+  })
+
+  // A partner's own queries and another integration's widget stay apart.
+  it('does not share across scopes', async () => {
+    const client = clientFor(V1)
+
+    await render(
+      <>
+        <Host client={client} scopeKey="host" />
+        <Widget client={client} scopeKey="partner" />
+      </>
+    )
+    await settle()
+
+    expect(mocks.getChains).toHaveBeenCalledTimes(2)
+    expect(mocks.getTools).toHaveBeenCalledTimes(2)
+  })
+
+  // Different API bases can return different chains and tools, so they must
+  // never share an entry.
+  it('does not share across API bases', async () => {
+    await render(
+      <>
+        <Host client={clientFor(V1)} scopeKey="host" />
+        <Widget client={clientFor(OTHER_BASE)} scopeKey="host" />
+      </>
+    )
+    await settle()
+
+    expect(mocks.getChains).toHaveBeenCalledTimes(2)
+    expect(mocks.getTools).toHaveBeenCalledTimes(2)
+  })
+})

package/src/queries/types.ts

@@ -0,0 +1,38 @@
+import type {
+  QueryFunction,
+  QueryKey,
+  UseQueryOptions,
+} from '@tanstack/react-query'
+
+export type ScopeKeyParameter = {
+  /**
+   * Scopes the entry inside a shared `QueryClient`, like wagmi's `scopeKey`.
+   * Callers that pass the same value share the cached data; a widget passes
+   * its `queryScopeKey`.
+   */
+  scopeKey?: string | undefined
+}
+
+/**
+ * Behaviour the caller owns — `staleTime`, `refetchInterval`, `select`,
+ * `enabled`, … It is spread into the options and never becomes part of the
+ * key, so callers with different behaviour still share one entry.
+ */
+export type QueryParameter<queryFnData, data, queryKey extends QueryKey> = {
+  query?:
+    | Omit<
+        UseQueryOptions<queryFnData, Error, data, queryKey>,
+        'queryKey' | 'queryFn'
+      >
+    | undefined
+}
+
+/** Options ready for `useQuery`, `fetchQuery` or `prefetchQuery`. */
+export type FactoryQueryOptions<
+  queryFnData,
+  data,
+  queryKey extends QueryKey,
+> = UseQueryOptions<queryFnData, Error, data, queryKey> & {
+  queryKey: queryKey
+  queryFn: QueryFunction<queryFnData, queryKey>
+}

package/src/shared.ts

@@ -188,5 +188,6 @@ export {
 export { getPriceImpact } from './utils/getPriceImpact.js'
 export { fitInputText } from './utils/input.js'
 export { navigationRoutes } from './utils/navigationRoutes.js'
+export { resolveStorageScopeKey } from './utils/scopeKeys.js'
 export { isHttpUrl, openInNewTab } from './utils/url.js'
 export { shortenAddress } from './utils/wallet.js'

package/src/stores/StoreProvider.test.tsx

@@ -0,0 +1,107 @@
+/** @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'
+
+/**
+ * The persisted stores are named from the resolved storage scope. An
+ * integration that only set the deprecated keyPrefix must keep the store
+ * names it always had, or its users lose their saved state.
+ */
+
+const { recorded, recorder } = vi.hoisted(() => {
+  const recorded = { namePrefix: {} as Record<string, string | undefined> }
+  const recorder = (name: string) => ({
+    [name]: ({
+      children,
+      namePrefix,
+    }: {
+      children?: unknown
+      namePrefix?: string
+    }) => {
+      recorded.namePrefix[name] = namePrefix
+      return children
+    },
+  })
+  return { recorded, recorder }
+})
+
+vi.mock('./bookmarks/BookmarkStore.js', () => recorder('BookmarkStoreProvider'))
+vi.mock('./chains/ChainOrderStore.js', () =>
+  recorder('ChainOrderStoreProvider')
+)
+vi.mock('./form/FormStore.js', () => recorder('FormStoreProvider'))
+vi.mock('./header/useHeaderStore.js', () => recorder('HeaderStoreProvider'))
+vi.mock('./navigationTabs/useNavigationTabsStore.js', () =>
+  recorder('NavigationTabsStoreProvider')
+)
+vi.mock('./pinnedTokens/PinnedTokensStore.js', () =>
+  recorder('PinnedTokensStoreProvider')
+)
+vi.mock('./recentTokens/RecentTokensStore.js', () =>
+  recorder('RecentTokensStoreProvider')
+)
+vi.mock('./routes/RouteExecutionStore.js', () =>
+  recorder('RouteExecutionStoreProvider')
+)
+
+import { StoreProvider } from './StoreProvider.js'
+
+const PERSISTED = [
+  'BookmarkStoreProvider',
+  'PinnedTokensStoreProvider',
+  'RecentTokensStoreProvider',
+  'ChainOrderStoreProvider',
+  'RouteExecutionStoreProvider',
+]
+
+let root: Root
+
+const render = async (config: WidgetConfig) => {
+  await act(async () => {
+    root.render(<StoreProvider config={config}>{null}</StoreProvider>)
+  })
+}
+
+describe('StoreProvider storage scope', () => {
+  beforeEach(() => {
+    recorded.namePrefix = {}
+    const container = document.createElement('div')
+    document.body.appendChild(container)
+    root = createRoot(container)
+  })
+
+  afterEach(async () => {
+    await act(async () => root.unmount())
+  })
+
+  it('names the persisted stores from keyPrefix when only that is set', async () => {
+    await render({ integrator: 'test', keyPrefix: 'legacy' })
+
+    for (const store of PERSISTED) {
+      expect(recorded.namePrefix[store]).toBe('legacy')
+    }
+  })
+
+  it('names the persisted stores from storageScopeKey over keyPrefix', async () => {
+    await render({
+      integrator: 'test',
+      keyPrefix: 'legacy',
+      storageScopeKey: 'store',
+    })
+
+    for (const store of PERSISTED) {
+      expect(recorded.namePrefix[store]).toBe('store')
+    }
+  })
+
+  it('keeps the historical names when nothing is set', async () => {
+    await render({ integrator: 'test' })
+
+    for (const store of PERSISTED) {
+      expect(recorded.namePrefix[store]).toBeUndefined()
+    }
+  })
+})

package/src/stores/StoreProvider.tsx

@@ -1,5 +1,6 @@
 import type { PropsWithChildren } from 'react'
 import type { WidgetConfigProps } from '../types/widget.js'
+import { resolveStorageScopeKey } from '../utils/scopeKeys.js'
 import { BookmarkStoreProvider } from './bookmarks/BookmarkStore.js'
 import { ChainOrderStoreProvider } from './chains/ChainOrderStore.js'
 import { FormStoreProvider } from './form/FormStore.js'
@@ -14,15 +15,16 @@ export const StoreProvider: React.FC<PropsWithChildren<WidgetConfigProps>> = ({
   config,
   formRef,
 }) => {
+  const storageScopeKey = resolveStorageScopeKey(config)
   return (
     <NavigationTabsStoreProvider config={config}>
-      <HeaderStoreProvider namePrefix={config?.keyPrefix}>
-        <BookmarkStoreProvider namePrefix={config?.keyPrefix}>
-          <PinnedTokensStoreProvider namePrefix={config?.keyPrefix}>
-            <RecentTokensStoreProvider namePrefix={config?.keyPrefix}>
+      <HeaderStoreProvider>
+        <BookmarkStoreProvider namePrefix={storageScopeKey}>
+          <PinnedTokensStoreProvider namePrefix={storageScopeKey}>
+            <RecentTokensStoreProvider namePrefix={storageScopeKey}>
               <FormStoreProvider formRef={formRef}>
-                <ChainOrderStoreProvider namePrefix={config?.keyPrefix}>
-                  <RouteExecutionStoreProvider namePrefix={config?.keyPrefix}>
+                <ChainOrderStoreProvider namePrefix={storageScopeKey}>
+                  <RouteExecutionStoreProvider namePrefix={storageScopeKey}>
                     {children}
                   </RouteExecutionStoreProvider>
                 </ChainOrderStoreProvider>

package/src/stores/header/useHeaderStore.tsx

@@ -1,14 +1,13 @@
+import type { PropsWithChildren } from 'react'
 import { createContext, use, useRef } from 'react'
 import { create } from 'zustand'
 import { useShallow } from 'zustand/shallow'
-import type { PersistStoreProviderProps } from '../types.js'
 import type { HeaderState, HeaderStore } from './types.js'
 
 const HeaderStoreContext = createContext<HeaderStore | null>(null)
 
-export function HeaderStoreProvider({
-  children,
-}: PersistStoreProviderProps): any {
+// Not persisted, so it takes no storage scope.
+export function HeaderStoreProvider({ children }: PropsWithChildren): any {
   const storeRef = useRef<HeaderStore>(null)
   if (!storeRef.current) {
     storeRef.current = createHeaderStore()

package/src/types/widget.ts

@@ -410,7 +410,37 @@ export interface WidgetConfig {
   sdkConfig?: WidgetSDKConfig
 
   buildUrl?: boolean
+  /**
+   * @deprecated Use `storageScopeKey` for persisted state and `queryScopeKey`
+   * for the query cache. Still honoured as the fallback for both.
+   */
   keyPrefix?: string
+  /**
+   * Namespaces the widget's persisted state in `localStorage`: bookmarks,
+   * pinned tokens, recent tokens, chain order and route history, as
+   * `keyPrefix` does. Use a different value per widget instance that should
+   * keep its own state. Settings keep one shared name.
+   *
+   * It also scopes the widget's other queries (routes, tokens, balances, …),
+   * so instances with different values keep their data apart.
+   *
+   * Falls back to `keyPrefix`, then to the historical `li.fi-*` names.
+   */
+  storageScopeKey?: string
+  /**
+   * Scopes the widget's chains and tools queries inside the host's react-query
+   * `QueryClient`. Widget instances - and a host app using the
+   * `@lifi/widget/queries` factories - that pass the same value
+   * share those entries. The other widget queries are scoped by
+   * `storageScopeKey`.
+   *
+   * The keys start with a plain `'chains'` / `'tools'`, as in wagmi, so a host
+   * that matches on those roots (for example `setQueriesData({ queryKey:
+   * ['chains'] })`) also reaches the widget's entries.
+   *
+   * Falls back to `keyPrefix`, then to `'li.fi'`.
+   */
+  queryScopeKey?: string
 
   bridges?: AllowDeny<string>
   exchanges?: AllowDeny<string>

package/src/utils/queries.ts

@@ -1,2 +1,3 @@
+// Legacy keys: callers pass the storage scope, so instances stay apart.
 export const getQueryKey = (key: string, prefix?: string) =>
   `${prefix || 'li.fi'}-widget-${key}`

package/src/utils/scopeKeys.ts

@@ -0,0 +1,18 @@
+import type { WidgetConfig } from '../types/widget.js'
+
+// Non-empty, so an unconfigured widget never shares a host's unscoped entries.
+export const defaultQueryScopeKey = 'li.fi'
+
+type ScopeKeyConfig = Pick<
+  WidgetConfig,
+  'storageScopeKey' | 'queryScopeKey' | 'keyPrefix'
+>
+
+// `undefined` keeps the historical `li.fi-*` store names.
+export const resolveStorageScopeKey = (
+  config: Partial<ScopeKeyConfig> | undefined
+): string | undefined => config?.storageScopeKey ?? config?.keyPrefix
+
+export const resolveQueryScopeKey = (
+  config: Partial<ScopeKeyConfig> | undefined
+): string => config?.queryScopeKey ?? config?.keyPrefix ?? defaultQueryScopeKey