@luxexchange/api 1.0.0

package/src/index.ts

@@ -0,0 +1,318 @@
+/** biome-ignore-all assist/source/organizeImports: we want to manually group exports by category */
+
+/**
+ * @luxexchange/api - Unified data layer for Lux Universe
+ *
+ * This is the ONLY public entry point for the API package.
+ * All exports must be explicitly listed here.
+ * Deep imports are forbidden and will be blocked by ESLint.
+ */
+
+// Foundations
+export { createFetchClient } from '@luxexchange/api/src/clients/base/createFetchClient'
+export {
+  FetchError,
+  is401Error,
+  is404Error,
+  isRateLimitFetchError,
+} from '@luxexchange/api/src/clients/base/errors'
+export type {
+  CustomOptions,
+  FetchClient,
+  StandardFetchOptions,
+} from '@luxexchange/api/src/clients/base/types'
+export { SharedQueryClient } from '@luxexchange/api/src/clients/base/SharedQueryClient'
+
+// Constants and URLs
+export {
+  createHelpArticleUrl,
+  DEV_ENTRY_GATEWAY_API_BASE_URL,
+  getCloudflareApiBaseUrl,
+  getCloudflarePrefix,
+  getServicePrefix,
+  helpUrl,
+  PROD_ENTRY_GATEWAY_API_BASE_URL,
+  STAGING_ENTRY_GATEWAY_API_BASE_URL,
+  TrafficFlows,
+} from '@luxexchange/api/src/clients/base/urls'
+
+// Auth
+export type { AuthData, SignedRequestParams, SignMessageFunc } from '@luxexchange/api/src/clients/base/auth'
+export { createSignedRequestBody, createSignedRequestParams } from '@luxexchange/api/src/clients/base/auth'
+
+// GraphQL API
+export * as GraphQLApi from '@luxexchange/api/src/clients/graphql/generated'
+export {
+  useTokenBasicInfoPartsFragment,
+  useTokenBasicProjectPartsFragment,
+  useTokenMarketPartsFragment,
+  useTokenProjectMarketsPartsFragment,
+  useTokenProjectUrlsPartsFragment,
+} from '@luxexchange/api/src/clients/graphql/fragments'
+export { GQLQueries } from '@luxexchange/api/src/clients/graphql/queries'
+export type { GqlResult } from '@luxexchange/api/src/clients/graphql/types'
+export { isError, isNonPollingRequestInFlight, isWarmLoadingStatus } from '@luxexchange/api/src/clients/graphql/utils'
+
+// Jupiter API
+export {
+  createJupiterApiClient,
+  type JupiterApiClient,
+} from '@luxexchange/api/src/clients/jupiter/createJupiterApiClient'
+export type {
+  JupiterExecuteResponse,
+  JupiterOrderResponse,
+  JupiterExecuteUrlParams,
+  JupiterOrderUrlParams,
+} from '@luxexchange/api/src/clients/jupiter/types'
+export {
+  jupiterExecuteResponseSchema,
+  jupiterOrderResponseSchema,
+} from '@luxexchange/api/src/clients/jupiter/types'
+
+// Blockaid API
+export {
+  createBlockaidApiClient,
+  type BlockaidApiClient,
+} from '@luxexchange/api/src/clients/blockaid/createBlockaidApiClient'
+export {
+  getBlockaidScanSiteResponseSchema,
+  getBlockaidScanTransactionRequestSchema,
+  getBlockaidScanTransactionResponseSchema,
+  getBlockaidScanJsonRpcRequestSchema,
+  DappVerificationStatus,
+  type BlockaidScanSiteRequest,
+  type BlockaidScanSiteResponse,
+  type BlockaidScanSiteHitResponse,
+  type BlockaidScanSiteMissResponse,
+  type BlockaidScanTransactionRequest,
+  type BlockaidScanTransactionResponse,
+  type BlockaidScanJsonRpcRequest,
+  type BlockaidScanJsonRpcResponse,
+} from '@luxexchange/api/src/clients/blockaid/types'
+
+// Trading API
+export * as TradingApi from '@luxexchange/api/src/clients/trading/__generated__'
+export {
+  createTradingApiClient,
+  type TradingApiClient,
+  type TradingClientContext,
+} from '@luxexchange/api/src/clients/trading/createTradingApiClient'
+export {
+  type BridgeQuoteResponse,
+  type ChainedQuoteResponse,
+  type ClassicQuoteResponse,
+  type DiscriminatedQuoteResponse,
+  type DutchQuoteResponse,
+  type DutchV3QuoteResponse,
+  type ExistingPlanRequest,
+  type PriorityQuoteResponse,
+  type SwappableTokensParams,
+  type UnwrapQuoteResponse,
+  type UpdatePlanRequestWithPlanId,
+  type WrapQuoteResponse,
+} from '@luxexchange/api/src/clients/trading/tradeTypes'
+export {
+  FeeType,
+  type FormattedDEXGasFeeInfo,
+  type GasEstimate,
+  type GasEstimateEip1559,
+  type GasEstimateLegacy,
+  type GasFeeResponse,
+  type GasFeeResult,
+  type GasFeeResultWithoutState,
+  type GasStrategy,
+  type TransactionEip1559FeeParams,
+  type TransactionLegacyFeeParams,
+} from '@luxexchange/api/src/clients/trading/types'
+
+// Liquidity Service API
+export {
+  createLiquidityServiceClient,
+  type LiquidityServiceClient,
+} from '@luxexchange/api/src/clients/liquidity/createLiquidityServiceClient'
+export {
+  createAuctionMutationClient,
+  type AuctionMutationClient,
+} from '@luxexchange/api/src/clients/liquidity/createAuctionMutationClient'
+
+// Auction Service API
+export {
+  createAuctionServiceClient,
+  type AuctionServiceClient,
+} from '@luxexchange/api/src/clients/auctions/createAuctionServiceClient'
+
+// Lux API
+export {
+  createLuxApiClient,
+  type ScreenRequest,
+  type ScreenResponse,
+  type LuxApiClient,
+  type LuxApiClientContext,
+} from '@luxexchange/api/src/clients/lux/createLuxApiClient'
+
+// Unitags API
+export {
+  type ProfileMetadata,
+  type UnitagAddressesRequest,
+  type UnitagAddressesResponse,
+  type UnitagAddressRequest,
+  type UnitagAddressResponse,
+  type UnitagAvatarUploadCredentials,
+  type UnitagChangeUsernameRequestBody,
+  type UnitagClaim,
+  type UnitagClaimContext,
+  type UnitagClaimEligibilityRequest,
+  type UnitagClaimEligibilityResponse,
+  type UnitagClaimSource,
+  type UnitagClaimUsernameRequestBody,
+  type UnitagDeleteUsernameRequestBody,
+  UnitagErrorCodes,
+  type UnitagGetAvatarUploadUrlResponse,
+  type UnitagResponse,
+  type UnitagUpdateMetadataRequestBody,
+  type UnitagUpdateMetadataResponse,
+  type UnitagUsernameRequest,
+  type UnitagUsernameResponse,
+} from '@luxexchange/api/src/clients/unitags/types'
+export { createUnitagsApiClient } from '@luxexchange/api/src/clients/unitags/createUnitagsApiClient'
+
+// Data API Service (ConnectRPC - listTopTokens, listTopPools, getPortfolio, etc.)
+export {
+  createDataApiServiceClient,
+  type DataApiServiceClient,
+  type DataApiServiceClientContext,
+} from '@luxexchange/api/src/clients/dataApi/createDataApiServiceClient'
+export {
+  getGetPortfolioQueryOptions,
+  type GetPortfolioQueryParams,
+} from '@luxexchange/api/src/clients/dataApi/getGetPortfolioQueryOptions'
+export {
+  TopPoolsOrderBy,
+  TopTokensOrderBy,
+  type GetPortfolioRequest,
+  type GetPortfolioResponse,
+  type ListTopPoolsResponse,
+  type ListTopTokensResponse,
+} from '@uniswap/client-data-api/dist/data/v1/api_pb'
+export { ProtocolVersion } from '@uniswap/client-data-api/dist/data/v1/poolTypes_pb'
+export { type Pool as DataApiPool, type Token as DataApiToken } from '@uniswap/client-data-api/dist/data/v1/types_pb'
+
+// Data Service API
+export {
+  createDataServiceApiClient,
+  type DataServiceApiClient,
+  type DataServiceApiClientContext,
+  TokenReportEventType,
+  ReportAssetType,
+} from '@luxexchange/api/src/clients/data/createDataServiceApiClient'
+
+// Notifications API
+export { createNotificationsApiClient } from '@luxexchange/api/src/clients/notifications/createNotificationsApiClient'
+export { BackgroundType, ContentStyle, OnClickAction } from '@luxexchange/api/src/clients/notifications/types'
+export type {
+  AckNotificationRequest,
+  AckNotificationResponse,
+  GetNotificationsRequest,
+  GetNotificationsResponse,
+  InAppNotification,
+  NotificationsApiClient,
+  NotificationsClientContext,
+} from '@luxexchange/api/src/clients/notifications/types'
+
+// FOR (Fiat On-Ramp) API
+export {
+  createForApiClient,
+  type ForApiClient,
+} from '@luxexchange/api/src/clients/for/createForApiClient'
+export { transformPaymentMethods } from '@luxexchange/api/src/clients/for/utils'
+export type {
+  FORCountry,
+  FORLogo,
+  FORQuote,
+  FORQuoteResponse,
+  FORServiceProvider,
+  FORSupportedFiatCurrency,
+  FORSupportedToken,
+  FORTransaction,
+} from '@luxexchange/api/src/clients/for/types'
+// Re-export FOR protobuf types for consumer packages
+export {
+  RampDirection,
+  TransactionStatus as FORTransactionStatus,
+  GetCountryResponse,
+  OffRampTransferDetailsRequest,
+  OffRampTransferDetailsResponse,
+  OffRampWidgetUrlRequest,
+  QuoteRequest,
+  SupportedCountriesRequest,
+  SupportedCountriesResponse,
+  SupportedFiatCurrenciesRequest,
+  SupportedFiatCurrenciesResponse,
+  SupportedTokensRequest,
+  SupportedTokensResponse,
+  TransactionRequest,
+  TransactionResponse,
+  TransferServiceProvidersResponse,
+  TransferWidgetUrlRequest,
+  WidgetUrlRequest,
+  WidgetUrlResponse,
+} from '@uniswap/client-for/dist/for/v1/api_pb'
+
+// ConnectRPC API
+export {
+  ALL_NETWORKS_ARG,
+  createConnectTransportWithDefaults,
+  type ConnectRpcContext,
+} from '@luxexchange/api/src/connectRpc/base'
+export {
+  parseProtectionInfo,
+  parseRestProtocolVersion,
+  parseSafetyLevel,
+  transformInput,
+  type WithoutWalletAccount,
+} from '@luxexchange/api/src/connectRpc/utils'
+
+// Conversion Tracking API
+export * as ConversionTrackingApi from '@luxexchange/api/src/clients/conversionTracking'
+
+// Embedded Wallet API
+export {
+  createEmbeddedWalletApiClient,
+  type EmbeddedWalletApiClient,
+  type EmbeddedWalletClientContext,
+} from '@luxexchange/api/src/clients/embeddedWallet/createEmbeddedWalletApiClient'
+
+// Other Utilities
+export {
+  createFetcher,
+  objectToQueryString,
+} from '@luxexchange/api/src/clients/base/utils'
+
+// Session API
+export { ApiInit, SESSION_INIT_QUERY_KEY } from '@luxexchange/api/src/components/ApiInit'
+export { provideSessionService } from '@luxexchange/api/src/provideSessionService'
+export { useIsSessionInitialized } from '@luxexchange/api/src/hooks/useIsSessionInitialized'
+
+// Session Transport (pure factory, no platform detection)
+export { createSessionTransport, type CreateSessionTransportOptions } from '@luxexchange/api/src/session'
+
+export type {
+  UseQueryApiHelperHookArgs,
+  UseQueryWithImmediateGarbageCollectionApiHelperHookArgs,
+} from '@luxexchange/api/src/hooks/shared/types'
+export { useQueryWithImmediateGarbageCollection } from '@luxexchange/api/src/hooks/shared/useQueryWithImmediateGarbageCollection'
+
+// Other Types
+export {
+  CustomRankingType,
+  RankingType,
+  SpamCode,
+} from '@luxexchange/api/src/clients/content/types'
+
+export { getTransport } from '@luxexchange/api/src/transport'
+
+export { getEntryGatewayUrl, getMigratedForApiUrl } from '@luxexchange/api/src/getEntryGatewayUrl'
+
+export { getWebSocketUrl } from '@luxexchange/api/src/getWebSocketUrl'
+
+export { provideLuxIdentifierService } from '@luxexchange/api/src/provideLuxIdentifierService'

package/src/provideDeviceIdService.ts

@@ -0,0 +1,25 @@
+import { getStorageDriver } from '@luxfi/api/src/storage/getStorageDriver'
+import { createDeviceIdService, DeviceIdService } from '@luxfi/sessions'
+
+const DEVICE_ID_KEY = 'LUX_DEVICE_ID'
+
+function provideDeviceIdService(): DeviceIdService {
+  const driver = getStorageDriver()
+
+  const service = createDeviceIdService({
+    getDeviceId: async () => {
+      const deviceId = await driver.get(DEVICE_ID_KEY)
+      return deviceId || ''
+    },
+    setDeviceId: async (deviceId: string) => {
+      await driver.set(DEVICE_ID_KEY, deviceId)
+    },
+    removeDeviceId: async () => {
+      await driver.remove(DEVICE_ID_KEY)
+    },
+  })
+
+  return service
+}
+
+export { provideDeviceIdService }

package/src/provideLuxIdentifierService.ts

@@ -0,0 +1,25 @@
+import { getStorageDriver } from '@luxfi/api/src/storage/getStorageDriver'
+import { createLuxIdentifierService, LuxIdentifierService } from '@luxfi/sessions'
+
+const LUX_IDENTIFIER_KEY = 'LUX_IDENTIFIER'
+
+function provideLuxIdentifierService(): LuxIdentifierService {
+  const driver = getStorageDriver()
+
+  const service = createLuxIdentifierService({
+    getLuxIdentifier: async () => {
+      const identifier = await driver.get(LUX_IDENTIFIER_KEY)
+      return identifier || null
+    },
+    setLuxIdentifier: async (identifier: string) => {
+      await driver.set(LUX_IDENTIFIER_KEY, identifier)
+    },
+    removeLuxIdentifier: async () => {
+      await driver.remove(LUX_IDENTIFIER_KEY)
+    },
+  })
+
+  return service
+}
+
+export { provideLuxIdentifierService }

package/src/provideSessionService.native.ts

@@ -0,0 +1,46 @@
+import { provideDeviceIdService } from '@luxfi/api/src/provideDeviceIdService'
+import { provideSessionStorage } from '@luxfi/api/src/provideSessionStorage'
+import { provideLuxIdentifierService } from '@luxfi/api/src/provideLuxIdentifierService'
+import { getTransport } from '@luxfi/api/src/transport'
+import {
+  createNoopSessionService,
+  createSessionClient,
+  createSessionRepository,
+  createSessionService,
+  type SessionService,
+} from '@luxfi/sessions'
+import type { Logger } from '@luxfi/utilities/src/logger/logger'
+import { REQUEST_SOURCE } from '@luxfi/utilities/src/platform/requestSource'
+
+function provideSessionService(ctx: {
+  getBaseUrl: () => string
+  getIsSessionServiceEnabled: () => boolean
+  getLogger?: () => Logger
+}): SessionService {
+  if (!ctx.getIsSessionServiceEnabled()) {
+    return createNoopSessionService()
+  }
+  return getMobileSessionService(ctx)
+}
+
+function getMobileSessionService(ctx: { getBaseUrl: () => string; getLogger?: () => Logger }): SessionService {
+  const sessionClient = createSessionClient({
+    transport: getTransport({
+      getBaseUrl: ctx.getBaseUrl,
+      getHeaders: () => ({ 'x-request-source': REQUEST_SOURCE }),
+    }),
+  })
+
+  const sessionStorage = provideSessionStorage()
+  const deviceIdService = provideDeviceIdService()
+  const luxIdentifierService = provideLuxIdentifierService()
+  const sessionRepository = createSessionRepository({ client: sessionClient, getLogger: ctx.getLogger })
+  return createSessionService({
+    sessionStorage,
+    deviceIdService,
+    luxIdentifierService,
+    sessionRepository,
+  })
+}
+
+export { provideSessionService }

package/src/provideSessionService.ts

@@ -0,0 +1,13 @@
+import type { SessionService, LuxIdentifierService } from '@luxexchange/sessions'
+import { PlatformSplitStubError } from '@luxfi/utilities/src/errors'
+import type { Logger } from '@luxfi/utilities/src/logger/logger'
+
+export function provideSessionService(_ctx: {
+  getBaseUrl: () => string
+  getIsSessionServiceEnabled: () => boolean
+  getLogger?: () => Logger
+  /** Optional custom LuxIdentifierService. If not provided, uses default localStorage-based service. */
+  luxIdentifierService?: LuxIdentifierService
+}): SessionService {
+  throw new PlatformSplitStubError('provideSessionService')
+}

package/src/provideSessionService.web.ts

@@ -0,0 +1,87 @@
+import { provideDeviceIdService } from '@luxexchange/api/src/provideDeviceIdService'
+import { provideSessionStorage } from '@luxexchange/api/src/provideSessionStorage'
+import { provideLuxIdentifierService } from '@luxexchange/api/src/provideLuxIdentifierService'
+import { getTransport } from '@luxexchange/api/src/transport'
+import {
+  createNoopSessionService,
+  createSessionClient,
+  createSessionRepository,
+  createSessionService,
+  type SessionService,
+  type LuxIdentifierService,
+} from '@luxexchange/sessions'
+import type { Logger } from '@luxfi/utilities/src/logger/logger'
+import { isWebApp } from '@luxfi/utilities/src/platform'
+import { REQUEST_SOURCE } from '@luxfi/utilities/src/platform/requestSource'
+
+function provideSessionService(ctx: {
+  getBaseUrl: () => string
+  getIsSessionServiceEnabled: () => boolean
+  getLogger?: () => Logger
+  /** Optional custom LuxIdentifierService. If not provided, uses default localStorage-based service. */
+  luxIdentifierService?: LuxIdentifierService
+}): SessionService {
+  if (!ctx.getIsSessionServiceEnabled()) {
+    return createNoopSessionService()
+  }
+  if (isWebApp) {
+    return getWebAppSessionService(ctx)
+  }
+  return getExtensionSessionService(ctx)
+}
+
+/**
+ * In production, web won't need an explicit session service since cookies are automatically handled by the backend+browser.
+ *
+ * For testing, we need this since SessionService is the only backend service that has CORS configured to handle the credentials header.
+ *
+ * When more services are added to the Entry Gateway, we can remove this and rely on those typical requests to instantiate the cookie.
+ */
+function getWebAppSessionService(ctx: {
+  getBaseUrl: () => string
+  getLogger?: () => Logger
+  luxIdentifierService?: LuxIdentifierService
+}): SessionService {
+  const sessionClient = createSessionClient({
+    transport: getTransport({
+      getBaseUrl: ctx.getBaseUrl,
+      getHeaders: () => ({ 'x-request-source': REQUEST_SOURCE }),
+      options: {
+        credentials: 'include',
+      },
+    }),
+  })
+
+  const sessionRepository = createSessionRepository({ client: sessionClient, getLogger: ctx.getLogger })
+
+  return createSessionService({
+    sessionStorage: provideSessionStorage(),
+    deviceIdService: provideDeviceIdService(),
+    luxIdentifierService: ctx.luxIdentifierService ?? provideLuxIdentifierService(),
+    sessionRepository,
+  })
+}
+
+function getExtensionSessionService(ctx: {
+  getBaseUrl: () => string
+  getLogger?: () => Logger
+  luxIdentifierService?: LuxIdentifierService
+}): SessionService {
+  const sessionClient = createSessionClient({
+    transport: getTransport({
+      getBaseUrl: ctx.getBaseUrl,
+      getHeaders: () => ({ 'x-request-source': REQUEST_SOURCE }),
+    }),
+  })
+
+  const sessionRepository = createSessionRepository({ client: sessionClient, getLogger: ctx.getLogger })
+
+  return createSessionService({
+    sessionStorage: provideSessionStorage(),
+    deviceIdService: provideDeviceIdService(),
+    luxIdentifierService: ctx.luxIdentifierService ?? provideLuxIdentifierService(),
+    sessionRepository,
+  })
+}
+
+export { provideSessionService }

package/src/provideSessionStorage.ts

@@ -0,0 +1,21 @@
+import { getStorageDriver } from '@luxfi/api/src/storage/getStorageDriver'
+import { createSessionStorage, type SessionStorage } from '@luxfi/sessions'
+
+const SESSION_ID_KEY = 'LUX_SESSION_ID'
+
+function provideSessionStorage(): SessionStorage {
+  const driver = getStorageDriver()
+  return createSessionStorage({
+    getSessionId: async () => {
+      return driver.get(SESSION_ID_KEY)
+    },
+    setSessionId: async (sessionId) => {
+      await driver.set(SESSION_ID_KEY, sessionId)
+    },
+    clearSessionId: async () => {
+      await driver.remove(SESSION_ID_KEY)
+    },
+  })
+}
+
+export { provideSessionStorage }

package/src/session/createSessionTransport.test.ts

@@ -0,0 +1,79 @@
+import { createSessionTransport } from '@luxexchange/api/src/session/createSessionTransport'
+import { describe, expect, it } from 'vitest'
+
+describe('createSessionTransport', () => {
+  it('creates transport with baseUrl', () => {
+    const transport = createSessionTransport({
+      baseUrl: 'https://api.example.com',
+    })
+
+    expect(transport).toBeDefined()
+  })
+
+  it('includes credentials option when specified', () => {
+    const transport = createSessionTransport({
+      baseUrl: 'https://api.example.com',
+      credentials: 'include',
+    })
+
+    expect(transport).toBeDefined()
+  })
+
+  it('includes transportOptions when specified', () => {
+    const transport = createSessionTransport({
+      baseUrl: 'https://api.example.com',
+      transportOptions: {
+        useBinaryFormat: true,
+      },
+    })
+
+    expect(transport).toBeDefined()
+  })
+
+  it('creates transport with all options combined', () => {
+    const transport = createSessionTransport({
+      baseUrl: 'https://api.example.com',
+      headers: {
+        'x-request-source': 'test',
+        'x-lux-timezone': 'UTC',
+      },
+      cookie: 'session=abc123',
+      credentials: 'include',
+      getSessionId: async () => 'session-id',
+      getDeviceId: async () => 'device-id',
+      transportOptions: {
+        useBinaryFormat: true,
+      },
+    })
+
+    expect(transport).toBeDefined()
+  })
+
+  it('handles undefined getSessionId/getDeviceId', () => {
+    const transport = createSessionTransport({
+      baseUrl: 'https://api.example.com',
+      getSessionId: undefined,
+      getDeviceId: undefined,
+    })
+
+    expect(transport).toBeDefined()
+  })
+
+  it('handles empty headers object', () => {
+    const transport = createSessionTransport({
+      baseUrl: 'https://api.example.com',
+      headers: {},
+    })
+
+    expect(transport).toBeDefined()
+  })
+
+  it('handles undefined cookie', () => {
+    const transport = createSessionTransport({
+      baseUrl: 'https://api.example.com',
+      cookie: undefined,
+    })
+
+    expect(transport).toBeDefined()
+  })
+})