@luxexchange/api 1.0.0

package/src/connectRpc/utils.ts

@@ -0,0 +1,136 @@
+import { type PlainMessage } from '@bufbuild/protobuf'
+import { Platform, type PlatformAddress, type WalletAccount } from '@uniswap/client-data-api/dist/data/v1/api_pb'
+import { ProtocolVersion } from '@uniswap/client-data-api/dist/data/v1/poolTypes_pb'
+import { type ProtectionInfo as ProtectionInfoProtobuf } from '@luxdex/client-explore/dist/uniswap/explore/v1/service_pb'
+import {
+  ProtectionAttackType,
+  type ProtectionInfo,
+  ProtectionResult,
+  SafetyLevel,
+} from '@luxfi/api/src/clients/graphql/__generated__/schema-types'
+import { logger } from '@luxfi/utilities/src/logger/logger'
+
+/**
+ * Helper functions to parse string enum fields from REST API responses.
+ *
+ * Note: The Protobuf types use string enums instead of strictly typed enums because
+ * Protobuf does not allow defining two of the same enum name in the same proto file. (i.e. both ProtectionAttackType and
+ * ProtectionResult contain 'UNKNOWN')
+ *
+ * Since the Explore service just calls GraphQL, we have confidence the string values will match the GraphQL enums.
+ * Just validating here!
+ */
+export function parseSafetyLevel(safetyLevel?: string): SafetyLevel | undefined {
+  if (!safetyLevel) {
+    return undefined
+  }
+  const validSafetyLevels: SafetyLevel[] = Object.values(SafetyLevel)
+  if (validSafetyLevels.includes(safetyLevel as SafetyLevel)) {
+    return safetyLevel as SafetyLevel
+  } else {
+    logger.warn(
+      'api/clients/connectRpc/utils.ts',
+      'parseSafetyLevel',
+      `Invalid safetyLevel from REST TokenRankings query: ${safetyLevel}`,
+    )
+    return undefined
+  }
+}
+
+export function parseProtectionInfo(protectionInfo?: ProtectionInfoProtobuf): ProtectionInfo | undefined {
+  if (!protectionInfo) {
+    return undefined
+  }
+
+  let protectionResult: ProtectionResult | undefined
+  // protectionInfo.result and protectionInfo.attackTypes are a string instead of an enum
+  // message TokenProtectionInfo {
+  //   string result = 1;
+  //   ...
+  // }
+  // So result and attackTypes are a capitalized string instead of an uppercase enum value
+  const validProtectionResults: string[] = Object.values(ProtectionResult)
+  if (validProtectionResults.includes(protectionInfo.result.toUpperCase())) {
+    protectionResult = protectionInfo.result.toUpperCase() as ProtectionResult
+  } else {
+    logger.warn(
+      'api/clients/connectRpc/utils.ts',
+      'parseProtectionInfo',
+      `Invalid protectionResult from REST TokenRankings query: ${protectionInfo.result}`,
+    )
+    return undefined
+  }
+
+  const validAttackTypes: string[] = Object.values(ProtectionAttackType)
+  const attackTypes = protectionInfo.attackTypes
+    .filter((at) => validAttackTypes.includes(at.toUpperCase()))
+    .map((at) => at.toUpperCase() as ProtectionAttackType)
+  if (attackTypes.length !== protectionInfo.attackTypes.length) {
+    logger.warn(
+      'api/clients/connectRpc/utils.ts',
+      'parseProtectionInfo',
+      `Invalid attackTypes in REST TokenRankings query: ${protectionInfo.attackTypes}`,
+    )
+  }
+
+  return { attackTypes, result: protectionResult }
+}
+
+export function parseRestProtocolVersion(version: string | undefined): ProtocolVersion | undefined {
+  switch (version?.toLowerCase()) {
+    case 'v2':
+      return ProtocolVersion.V2
+    case 'v3':
+      return ProtocolVersion.V3
+    case 'v4':
+      return ProtocolVersion.V4
+    default:
+      return undefined
+  }
+}
+
+/**
+ * Helps simplify REST endpoint interfaces that expect a walletAccount object instead
+ * of simple address fields
+ */
+function createWalletAccount({ evmAddress, svmAddress }: { evmAddress?: string; svmAddress?: string }): {
+  walletAccount: PlainMessage<WalletAccount>
+} {
+  const platformAddresses: PlainMessage<PlatformAddress>[] = []
+
+  if (evmAddress) {
+    platformAddresses.push({ platform: Platform.EVM, address: evmAddress })
+  }
+
+  if (svmAddress) {
+    platformAddresses.push({ platform: Platform.SVM, address: svmAddress })
+  }
+
+  return {
+    walletAccount: {
+      platformAddresses,
+    },
+  }
+}
+
+export type WithoutWalletAccount<T> = Omit<T, 'walletAccount'>
+
+/**
+ * Helper function to transform input that includes evmAddress/svmAddress to use walletAccount instead
+ */
+export function transformInput<T extends Record<string, unknown> & { walletAccount?: never }>(
+  input: (T & { evmAddress?: string; svmAddress?: string }) | undefined,
+):
+  | (Omit<T, 'evmAddress' | 'svmAddress' | 'walletAccount'> & { walletAccount: PlainMessage<WalletAccount> })
+  | undefined {
+  if (!input) {
+    return undefined
+  }
+
+  const { evmAddress, svmAddress, walletAccount: _walletAccount, ...restInput } = input
+
+  return {
+    ...restInput,
+    ...createWalletAccount({ evmAddress, svmAddress }),
+  }
+}

package/src/getEntryGatewayUrl.ts

@@ -0,0 +1,46 @@
+import {
+  PROD_ENTRY_GATEWAY_API_BASE_URL,
+  STAGING_ENTRY_GATEWAY_API_BASE_URL,
+} from '@luxfi/api/src/clients/base/urls'
+import { getConfig } from '@luxfi/config'
+import { Environment, getCurrentEnv } from '@luxfi/utilities/src/environment/getCurrentEnv'
+/**
+ * Returns the appropriate Entry Gateway API base URL based on the current environment.
+ * When proxy is enabled, returns the proxy path. Otherwise returns the direct URL.
+ * Can be overridden by setting ENTRY_GATEWAY_API_URL_OVERRIDE in environment variables.
+ */
+/**
+ * Get the FOR API URL routed through the Entry Gateway.
+ * Delegates to getEntryGatewayUrl() and appends the FOR service path.
+ */
+export function getMigratedForApiUrl(): string {
+  return `${getEntryGatewayUrl()}/FOR.v1.FORService`
+}
+
+export function getEntryGatewayUrl(): string {
+  const config = getConfig()
+
+  // Use proxy path if enabled (local dev, Vercel previews, or explicit opt-in)
+  if (config.enableEntryGatewayProxy) {
+    return '/entry-gateway'
+  }
+
+  // Allow override via environment variable
+  const override: string = config.entryGatewayApiUrlOverride
+  if (override) {
+    return override
+  }
+
+  const environment = getCurrentEnv({
+    isVercelEnvironment: config.isVercelEnvironment,
+  })
+  switch (environment) {
+    case Environment.DEV: // Dev also currently uses staging builds, as for many features staging is more stable / less prone to breaking testing changes.
+    case Environment.STAGING:
+      return STAGING_ENTRY_GATEWAY_API_BASE_URL
+    case Environment.PROD:
+      return PROD_ENTRY_GATEWAY_API_BASE_URL
+    default:
+      throw new Error(`Invalid environment: ${environment}`)
+  }
+}

package/src/getWebSocketUrl.ts

@@ -0,0 +1,28 @@
+import { PROD_WEBSOCKET_BASE_URL, STAGING_WEBSOCKET_BASE_URL } from '@luxexchange/api/src/clients/base/urls'
+import { getConfig } from '@luxexchange/config'
+import { Environment, getCurrentEnv } from '@luxfi/utilities/src/environment/getCurrentEnv'
+
+/**
+ * Returns the appropriate WebSocket URL based on the current environment.
+ * When the entry gateway proxy is enabled, returns the BFF proxy path so the
+ * Cloudflare Worker or Vercel edge function can forward the connection with
+ * correct cookies/origin.
+ */
+export function getWebSocketUrl(): string {
+  const config = getConfig()
+
+  if (config.enableEntryGatewayProxy) {
+    return '/ws'
+  }
+
+  const environment = getCurrentEnv({ isVercelEnvironment: config.isVercelEnvironment })
+  switch (environment) {
+    case Environment.DEV:
+    case Environment.STAGING:
+      return STAGING_WEBSOCKET_BASE_URL as string
+    case Environment.PROD:
+      return PROD_WEBSOCKET_BASE_URL as string
+    default:
+      throw new Error(`Invalid environment: ${environment}`)
+  }
+}

package/src/global.d.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="../../../index.d.ts" />

package/src/hooks/index.ts

@@ -0,0 +1,6 @@
+/**
+ * API Hooks
+ */
+
+export * from './use-token-list'
+export * from './use-token-price'

package/src/hooks/shared/types.ts

@@ -0,0 +1,10 @@
+import { useQuery } from '@tanstack/react-query'
+
+export type UseQueryApiHelperHookArgs<REQ, RES> = {
+  params?: REQ
+} & Omit<Parameters<typeof useQuery<RES>>[0], 'queryKey' | 'queryFn'>
+
+export type UseQueryWithImmediateGarbageCollectionApiHelperHookArgs<REQ, RES> = Omit<
+  UseQueryApiHelperHookArgs<REQ, RES>,
+  'gcTime'
+> & { immediateGcTime?: number }

package/src/hooks/shared/useQueryWithImmediateGarbageCollection.ts

@@ -0,0 +1,90 @@
+import {
+  type DefaultError,
+  type QueryClient,
+  type QueryKey,
+  skipToken,
+  type UseQueryOptions,
+  type UseQueryResult,
+  useQuery,
+  useQueryClient,
+} from '@tanstack/react-query'
+import { useEffect } from 'react'
+import { logger } from '@luxfi/utilities/src/logger/logger'
+
+/**
+ * This is a wrapper around react-query's `useQuery` that immediately clears the cache if the data is older than `gcTime`,
+ * even for active queries.
+ *
+ * react-query's garbage collection only runs once a query becomes inactive (the timer starts running the moment a query unmounts).
+ * There are some endpoints (for example, swap quotes) where we want to be able to use a stale-while-revalidate approach (using `staleTime`)
+ * for very short periods of time, while at the same time we want to make sure we never use stale data if it's older than the `gcTime`.
+ */
+export function useQueryWithImmediateGarbageCollection<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  {
+    immediateGcTime,
+    ...queryArgs
+  }: Omit<UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, 'gcTime'> & {
+    immediateGcTime?: number
+  },
+  customQueryClient?: QueryClient,
+): UseQueryResult<TData, TError> {
+  const defaultQueryClient = useQueryClient()
+  const queryClient = customQueryClient ?? defaultQueryClient
+
+  const { queryKey, queryFn } = queryArgs
+  const skip = queryFn === skipToken
+
+  const result = useQuery<TQueryFnData, TError, TData, TQueryKey>(
+    { ...queryArgs, gcTime: immediateGcTime },
+    queryClient,
+  )
+  const { dataUpdatedAt } = result
+
+  useEffect(() => {
+    if (skip || !immediateGcTime) {
+      return undefined
+    }
+
+    const timeSinceLastUpdate = Date.now() - dataUpdatedAt
+
+    const timeout = setTimeout(() => {
+      const state = queryClient.getQueryCache().find({ queryKey })?.state
+
+      if (!state) {
+        logger.debug('TradingApiClient.ts', 'useQueryWithImmediateGarbageCollection', 'Cache not found', { queryKey })
+        return
+      }
+
+      const { data, dataUpdatedAt: latestDataUpdatedAt, fetchStatus } = state
+
+      if (!data || fetchStatus === 'fetching') {
+        // We do not want to clear the cache if the query is currently being fetched,
+        // or else we could end up in an infite loop of clearing and refetching.
+        return
+      }
+
+      const latestTimeSinceLastUpdate = Date.now() - latestDataUpdatedAt
+
+      if (latestTimeSinceLastUpdate >= immediateGcTime) {
+        logger.debug('TradingApiClient.ts', 'useQueryWithImmediateGarbageCollection', 'Clearing stale data', {
+          queryKey,
+          immediateGcTime,
+          latestDataUpdatedAt,
+          latestTimeSinceLastUpdate,
+          state,
+        })
+
+        queryClient.removeQueries({ queryKey, exact: true })
+      }
+    }, immediateGcTime - timeSinceLastUpdate)
+
+    return () => clearTimeout(timeout)
+  }, [dataUpdatedAt, immediateGcTime, queryClient, queryKey, skip])
+
+  return result
+}

package/src/hooks/use-token-list.ts

@@ -0,0 +1,52 @@
+'use client'
+
+import { useQuery } from '@tanstack/react-query'
+import { fetchWithTimeout, API_URLS } from '../client'
+
+export interface TokenListToken {
+  address: string
+  chainId: number
+  decimals: number
+  symbol: string
+  name: string
+  logoURI?: string
+}
+
+export interface TokenList {
+  name: string
+  tokens: TokenListToken[]
+  version: {
+    major: number
+    minor: number
+    patch: number
+  }
+}
+
+/**
+ * Fetch and cache token list
+ */
+export function useTokenList(chainId: number) {
+  return useQuery({
+    queryKey: ['tokenList', chainId],
+    queryFn: async (): Promise<TokenListToken[]> => {
+      try {
+        const response = await fetchWithTimeout(
+          `${API_URLS.TOKEN_LIST}/lux-default.json`
+        )
+
+        if (!response.ok) {
+          throw new Error('Failed to fetch token list')
+        }
+
+        const data: TokenList = await response.json()
+
+        // Filter tokens for the specified chain
+        return data.tokens.filter((token) => token.chainId === chainId)
+      } catch (error) {
+        console.error('Failed to fetch token list:', error)
+        return []
+      }
+    },
+    staleTime: 5 * 60 * 1000, // 5 minutes
+  })
+}

package/src/hooks/use-token-price.ts

@@ -0,0 +1,82 @@
+'use client'
+
+import { useQuery } from '@tanstack/react-query'
+import { fetchWithTimeout, API_URLS } from '../client'
+import type { Address } from 'viem'
+
+export interface TokenPrice {
+  address: Address
+  priceUSD: number
+  change24h: number
+}
+
+/**
+ * Fetch token price in USD
+ */
+export function useTokenPrice(address: Address | undefined, chainId: number) {
+  return useQuery({
+    queryKey: ['tokenPrice', address, chainId],
+    queryFn: async (): Promise<TokenPrice | null> => {
+      if (!address) return null
+
+      try {
+        const response = await fetchWithTimeout(
+          `${API_URLS.PRICE_API}/${chainId}/${address}`
+        )
+
+        if (!response.ok) {
+          return null
+        }
+
+        return response.json()
+      } catch (error) {
+        console.error('Failed to fetch token price:', error)
+        return null
+      }
+    },
+    enabled: !!address,
+    staleTime: 30_000, // 30 seconds
+    refetchInterval: 60_000, // Refetch every minute
+  })
+}
+
+/**
+ * Fetch multiple token prices
+ */
+export function useTokenPrices(addresses: Address[], chainId: number) {
+  return useQuery({
+    queryKey: ['tokenPrices', addresses, chainId],
+    queryFn: async (): Promise<Map<Address, TokenPrice>> => {
+      const priceMap = new Map<Address, TokenPrice>()
+
+      if (addresses.length === 0) return priceMap
+
+      try {
+        const response = await fetchWithTimeout(
+          `${API_URLS.PRICE_API}/${chainId}/batch`,
+          {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ addresses }),
+          }
+        )
+
+        if (!response.ok) {
+          return priceMap
+        }
+
+        const prices: TokenPrice[] = await response.json()
+        prices.forEach((price) => {
+          priceMap.set(price.address, price)
+        })
+
+        return priceMap
+      } catch (error) {
+        console.error('Failed to fetch token prices:', error)
+        return priceMap
+      }
+    },
+    enabled: addresses.length > 0,
+    staleTime: 30_000,
+  })
+}

package/src/hooks/useIsSessionInitialized.ts

@@ -0,0 +1,17 @@
+import { useQueryClient } from '@tanstack/react-query'
+import { SESSION_INIT_QUERY_KEY } from '@luxexchange/api/src/components/ApiInit'
+
+/**
+ * Hook to check if session initialization is complete.
+ * Use this to gate API calls that require an authenticated session.
+ *
+ * @returns true if session init query has completed (success or error), false if pending or not started
+ */
+export function useIsSessionInitialized(): boolean {
+  const queryClient = useQueryClient()
+  const state = queryClient.getQueryState(SESSION_INIT_QUERY_KEY)
+
+  // Session is initialized if the query exists and is not in pending/fetching state
+  // We consider both success and error as "initialized" since we don't want to block forever
+  return state?.status === 'success' || state?.status === 'error'
+}