@luxexchange/api 1.0.0

package/src/clients/base/auth.ts

@@ -0,0 +1,43 @@
+import { objectToQueryString } from '@luxfi/api/src/clients/base/utils'
+
+export type AuthData = {
+  'x-uni-address': Address
+  'x-uni-timestamp': number
+}
+
+export type SignMessageFunc = (message: string) => Promise<string>
+export type SignedRequestParams<T> = {
+  data: T
+  address: string
+  signMessage: SignMessageFunc
+}
+
+export async function createSignedRequestBody<T>({
+  data,
+  address,
+  signMessage,
+}: SignedRequestParams<T>): Promise<{ requestBody: T & AuthData; signature: string }> {
+  const requestBody: T & AuthData = {
+    ...data,
+    'x-uni-address': address,
+    'x-uni-timestamp': Date.now(),
+  }
+  const message = JSON.stringify(requestBody)
+  const signature = await signMessage(message)
+  return { requestBody, signature }
+}
+
+export async function createSignedRequestParams<T>({
+  data,
+  address,
+  signMessage,
+}: SignedRequestParams<T>): Promise<{ requestParams: T & AuthData; signature: string }> {
+  const requestParams: T & AuthData = {
+    ...data,
+    'x-uni-address': address,
+    'x-uni-timestamp': Date.now(),
+  }
+  const message = objectToQueryString(requestParams)
+  const signature = await signMessage(message)
+  return { requestParams, signature }
+}

package/src/clients/base/createFetchClient.ts

@@ -0,0 +1,133 @@
+import { FetchError } from '@luxfi/api/src/clients/base/errors'
+import type {
+  CustomOptions,
+  FetchClient,
+  FetchClientContext,
+  StandardFetchOptions,
+} from '@luxfi/api/src/clients/base/types'
+
+export function createFetchClient({
+  baseUrl,
+  getBaseUrl,
+  getHeaders,
+  getSessionService,
+  defaultOptions = {},
+}: FetchClientContext): FetchClient {
+  // Helper to resolve the base URL - prefers getBaseUrl for dynamic resolution
+  const resolveBaseUrl = (): string => getBaseUrl?.() ?? baseUrl ?? ''
+
+  return {
+    get context() {
+      return () => {
+        return {
+          baseUrl: resolveBaseUrl(),
+          getBaseUrl,
+          getHeaders,
+          getSessionService,
+          defaultOptions,
+        }
+      }
+    },
+
+    get fetch() {
+      return async <T = Response>(path: string, options: StandardFetchOptions): Promise<T> => {
+        const sessionService = getSessionService()
+        const sessionState = await sessionService.getSessionState()
+
+        const additionalHeaders = getHeaders?.() ?? {}
+
+        const headers = new Headers({
+          ...additionalHeaders,
+          ...options?.headers,
+        })
+        if (sessionState?.sessionId) {
+          headers.set('x-session-id', sessionState.sessionId)
+        }
+        return fetch(`${resolveBaseUrl()}${path}`, {
+          ...defaultOptions,
+          ...options,
+          headers,
+        }) as Promise<T>
+      }
+    },
+
+    get get() {
+      return async <T>(path: string, options?: CustomOptions): Promise<T> => {
+        if (options?.params) {
+          const searchParams = new URLSearchParams()
+          for (const [key, value] of Object.entries(options.params)) {
+            if (value !== undefined && value !== null) {
+              searchParams.append(key, value.toString())
+            }
+          }
+          path += '?' + searchParams.toString()
+        }
+
+        const { on404, ...standardOptions } = options ?? {}
+
+        const response = await this.fetch(path, standardOptions)
+
+        if (on404 && response.status === 404) {
+          on404()
+        }
+
+        if (!response.ok) {
+          let data: object | undefined
+          try {
+            data = await response.json()
+          } catch (e) {
+            throw new FetchError({ response, cause: e })
+          }
+          throw new FetchError({ response, data })
+        }
+
+        return (await response.json()) as T
+      }
+    },
+
+    get post() {
+      return async <T>(path: string, options: CustomOptions): Promise<T> => {
+        const _options = options
+
+        _options.headers = {
+          'Content-Type': 'application/json',
+          ...(options.headers ?? {}),
+        }
+
+        return (await this.get(path, { ..._options, method: 'POST' })) as T
+      }
+    },
+
+    get put() {
+      return async <T>(path: string, options: CustomOptions): Promise<T> => {
+        const _options = options
+
+        _options.headers = {
+          'Content-Type': 'application/json',
+          ...(options.headers ?? {}),
+        }
+
+        return (await this.get(path, { ..._options, method: 'PUT' })) as T
+      }
+    },
+
+    get delete() {
+      return async <T>(path: string, options: CustomOptions = {}): Promise<T> => {
+        return (await this.get(path, { ...options, method: 'DELETE' })) as T
+      }
+    },
+
+    get patch() {
+      return async <T>(path: string, options: CustomOptions): Promise<T> => {
+        const _options = options
+
+        _options.headers = {
+          'Content-Type': 'application/json',
+          ...(options.headers ?? {}),
+        }
+
+        return await this.get(path, { ..._options, method: 'PATCH' })
+      }
+    },
+  }
+}

package/src/clients/base/errors.ts

@@ -0,0 +1,32 @@
+export class FetchError extends Error {
+  response: Response
+  // biome-ignore lint/suspicious/noExplicitAny: Error data can be any shape from API responses
+  data?: any
+
+  // biome-ignore lint/suspicious/noExplicitAny: Error data can be any shape from API responses
+  constructor({ response, data, cause }: { response: Response; data?: any; cause?: unknown }) {
+    super(`Response status: ${response.status}`)
+    this.name = 'FetchError'
+    this.response = response
+    this.data = data
+    this.cause = cause
+  }
+}
+
+export function isRateLimitFetchError(error: unknown): boolean {
+  return (
+    error instanceof FetchError &&
+    !!error.response.status &&
+    // This checks for our backend non-standard rate limit error codes.
+    error.response.status >= 412 &&
+    error.response.status <= 429
+  )
+}
+
+export function is401Error(error: unknown): boolean {
+  return error instanceof FetchError && error.response.status === 401
+}
+
+export function is404Error(error: unknown): boolean {
+  return error instanceof FetchError && !!error.response.status && error.response.status === 404
+}

package/src/clients/base/types.ts

@@ -0,0 +1,26 @@
+import type { SessionService } from '@luxfi/sessions'
+
+export type StandardFetchOptions = Parameters<typeof fetch>[1]
+
+export type CustomOptions = StandardFetchOptions & {
+  params?: Record<string, string | number | boolean | undefined | null>
+  on404?: () => void
+}
+
+export interface FetchClientContext {
+  baseUrl?: string
+  getBaseUrl?: () => string
+  getHeaders?: () => HeadersInit
+  getSessionService: () => SessionService
+  defaultOptions?: Omit<StandardFetchOptions, 'headers'>
+}
+
+export interface FetchClient {
+  readonly context: () => FetchClientContext
+  readonly fetch: <T = Response>(path: string, options: StandardFetchOptions) => Promise<T>
+  readonly get: <T>(path: string, options?: CustomOptions) => Promise<T>
+  readonly post: <T>(path: string, options: CustomOptions) => Promise<T>
+  readonly put: <T>(path: string, options: CustomOptions) => Promise<T>
+  readonly delete: <T>(path: string, options: CustomOptions) => Promise<T>
+  readonly patch: <T>(path: string, options: CustomOptions) => Promise<T>
+}

package/src/clients/base/urls.test.ts

@@ -0,0 +1,297 @@
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+
+import { TrafficFlows } from '@luxexchange/api/src/clients/base/urls'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Mock the platform and environment utilities
+vi.mock('@luxfi/utilities/src/environment/env')
+vi.mock('@luxfi/utilities/src/platform')
+
+const envConfigs = {
+  webProd: {
+    isWebApp: true,
+    isDevEnv: false,
+  },
+  webDev: {
+    isWebApp: true,
+    isDevEnv: true,
+  },
+  webBeta: {
+    isWebApp: true,
+    isBetaEnv: true,
+  },
+  mobileIosProd: {
+    isMobileApp: true,
+    isIOS: true,
+    isAndroid: false,
+    isDevEnv: false,
+  },
+  mobileIosDev: {
+    isMobileApp: true,
+    isIOS: true,
+    isAndroid: false,
+    isDevEnv: true,
+  },
+  mobileIosBeta: {
+    isMobileApp: true,
+    isIOS: true,
+    isAndroid: false,
+    isBetaEnv: true,
+  },
+  mobileAndroidProd: {
+    isMobileApp: true,
+    isAndroid: true,
+    isDevEnv: false,
+  },
+  mobileAndroidDev: {
+    isMobileApp: true,
+    isAndroid: true,
+    isDevEnv: true,
+  },
+  mobileAndroidBeta: {
+    isMobileApp: true,
+    isAndroid: true,
+    isBetaEnv: true,
+  },
+  extensionProd: {
+    isExtensionApp: true,
+    isDevEnv: false,
+  },
+  extensionDev: {
+    isExtensionApp: true,
+    isDevEnv: true,
+  },
+  extensionBeta: {
+    isExtensionApp: true,
+    isBetaEnv: true,
+  },
+  playwrightDev: {
+    isWebApp: true,
+    isPlaywrightEnv: true,
+    isDevEnv: true,
+  },
+  playwrightProd: {
+    isWebApp: true,
+    isPlaywrightEnv: true,
+    isDevEnv: false,
+  },
+}
+describe('urls', () => {
+  beforeEach(async () => {
+    // Reset modules to clear cached imports
+    vi.resetModules()
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('getCloudflareApiBaseUrl', () => {
+    describe('TradingApi', () => {
+      it.each([
+        // Web
+        {
+          expectedUrl: 'https://trading-api-labs.interface.gateway.lux.org',
+          env: envConfigs.webProd,
+        },
+        {
+          expectedUrl: 'https://beta.trading-api-labs.interface.gateway.lux.org',
+          env: envConfigs.webDev,
+        },
+        {
+          expectedUrl: 'https://trading-api-labs.interface.gateway.lux.org',
+          env: envConfigs.webBeta,
+        },
+        // Mobile iOS
+        {
+          expectedUrl: 'https://trading-api-labs.ios.wallet.gateway.lux.org',
+          env: envConfigs.mobileIosProd,
+        },
+        {
+          expectedUrl: 'https://beta.trading-api-labs.ios.wallet.gateway.lux.org',
+          env: envConfigs.mobileIosDev,
+        },
+        {
+          expectedUrl: 'https://trading-api-labs.ios.wallet.gateway.lux.org',
+          env: envConfigs.mobileIosBeta,
+        },
+        // Mobile Android
+        {
+          expectedUrl: 'https://trading-api-labs.android.wallet.gateway.lux.org',
+          env: envConfigs.mobileAndroidProd,
+        },
+        {
+          expectedUrl: 'https://beta.trading-api-labs.android.wallet.gateway.lux.org',
+          env: envConfigs.mobileAndroidDev,
+        },
+        {
+          expectedUrl: 'https://trading-api-labs.android.wallet.gateway.lux.org',
+          env: envConfigs.mobileAndroidBeta,
+        },
+        // Extension
+        {
+          expectedUrl: 'https://trading-api-labs.extension.gateway.lux.org',
+          env: envConfigs.extensionProd,
+        },
+        {
+          expectedUrl: 'https://beta.trading-api-labs.extension.gateway.lux.org',
+          env: envConfigs.extensionDev,
+        },
+        {
+          expectedUrl: 'https://trading-api-labs.extension.gateway.lux.org',
+          env: envConfigs.extensionBeta,
+        },
+        // Playwright
+        {
+          expectedUrl: 'https://trading-api-labs.interface.gateway.lux.org',
+          env: envConfigs.playwrightDev,
+        },
+        {
+          expectedUrl: 'https://trading-api-labs.interface.gateway.lux.org',
+          env: envConfigs.playwrightProd,
+        },
+      ])('generates correct URL for $env', async ({ expectedUrl, env }) => {
+        mockEnvironmentAndPlatform(env)
+        const { getCloudflareApiBaseUrl } = await import('./urls')
+        expect(getCloudflareApiBaseUrl({ flow: TrafficFlows.TradingApi })).toBe(expectedUrl)
+      })
+    })
+
+    describe('DataApi', () => {
+      it.each([
+        // Web
+        { expectedUrl: 'https://beta.gateway.lux.org', env: envConfigs.webDev },
+        { expectedUrl: 'https://interface.gateway.lux.org', env: envConfigs.webBeta },
+        { expectedUrl: 'https://interface.gateway.lux.org', env: envConfigs.webProd },
+        // Mobile iOS
+        { expectedUrl: 'https://beta.gateway.lux.org', env: envConfigs.mobileIosDev },
+        { expectedUrl: 'https://ios.wallet.gateway.lux.org', env: envConfigs.mobileIosBeta },
+        { expectedUrl: 'https://ios.wallet.gateway.lux.org', env: envConfigs.mobileIosProd },
+        // Mobile Android
+        { expectedUrl: 'https://beta.gateway.lux.org', env: envConfigs.mobileAndroidDev },
+        { expectedUrl: 'https://android.wallet.gateway.lux.org', env: envConfigs.mobileAndroidBeta },
+        { expectedUrl: 'https://android.wallet.gateway.lux.org', env: envConfigs.mobileAndroidProd },
+        // Extension
+        { expectedUrl: 'https://beta.gateway.lux.org', env: envConfigs.extensionDev },
+        { expectedUrl: 'https://extension.gateway.lux.org', env: envConfigs.extensionBeta },
+        { expectedUrl: 'https://extension.gateway.lux.org', env: envConfigs.extensionProd },
+        // Playwright
+        { expectedUrl: 'https://interface.gateway.lux.org', env: envConfigs.playwrightDev },
+        { expectedUrl: 'https://interface.gateway.lux.org', env: envConfigs.playwrightProd },
+      ])('generates correct URL for $env', async ({ expectedUrl, env }) => {
+        mockEnvironmentAndPlatform(env)
+        const { getCloudflareApiBaseUrl } = await import('./urls')
+        expect(getCloudflareApiBaseUrl({ flow: TrafficFlows.DataApi })).toBe(expectedUrl)
+      })
+    })
+  })
+
+  describe('Default Flow', () => {
+    it.each([
+      // Web
+      { expectedUrl: 'https://interface.gateway.lux.org', env: envConfigs.webDev },
+      { expectedUrl: 'https://interface.gateway.lux.org', env: envConfigs.webBeta },
+      { expectedUrl: 'https://interface.gateway.lux.org', env: envConfigs.webProd },
+      // Mobile iOS
+      { expectedUrl: 'https://ios.wallet.gateway.lux.org', env: envConfigs.mobileIosDev },
+      { expectedUrl: 'https://ios.wallet.gateway.lux.org', env: envConfigs.mobileIosBeta },
+      { expectedUrl: 'https://ios.wallet.gateway.lux.org', env: envConfigs.mobileIosProd },
+      // Mobile Android
+      { expectedUrl: 'https://android.wallet.gateway.lux.org', env: envConfigs.mobileAndroidDev },
+      { expectedUrl: 'https://android.wallet.gateway.lux.org', env: envConfigs.mobileAndroidBeta },
+      { expectedUrl: 'https://android.wallet.gateway.lux.org', env: envConfigs.mobileAndroidProd },
+      // Extension
+      { expectedUrl: 'https://extension.gateway.lux.org', env: envConfigs.extensionDev },
+      { expectedUrl: 'https://extension.gateway.lux.org', env: envConfigs.extensionBeta },
+      { expectedUrl: 'https://extension.gateway.lux.org', env: envConfigs.extensionProd },
+      // Playwright
+      { expectedUrl: 'https://interface.gateway.lux.org', env: envConfigs.playwrightDev },
+      { expectedUrl: 'https://interface.gateway.lux.org', env: envConfigs.playwrightProd },
+    ])('generates correct URL for $env', async ({ expectedUrl, env }) => {
+      mockEnvironmentAndPlatform(env)
+      const { getCloudflareApiBaseUrl } = await import('./urls')
+      expect(getCloudflareApiBaseUrl()).toBe(expectedUrl)
+    })
+  })
+
+  it.each(Object.values(TrafficFlows))(
+    'getCloudflareApiBaseUrl appends postfix correctly for flow: %s',
+    async (flow) => {
+      mockEnvironmentAndPlatform(envConfigs.webProd)
+      const { getCloudflareApiBaseUrl } = await import('./urls')
+      const postfix = 'my-postfix'
+
+      const baseUrl = getCloudflareApiBaseUrl({ flow })
+      const urlWithPostfix = getCloudflareApiBaseUrl({ flow, postfix })
+
+      expect(urlWithPostfix).toBe(`${baseUrl}/${postfix}`)
+    },
+  )
+
+  it('generates correct URL for GraphQL flow in web/Playwright', async () => {
+    vi.doMock('@luxfi/utilities/src/environment/env', () => ({
+      isBetaEnv: () => false,
+      isDevEnv: () => false,
+      isRNDev: () => false,
+      isPlaywrightEnv: () => true,
+      isTestEnv: () => false,
+    }))
+
+    vi.doMock('@luxfi/utilities/src/platform', () => ({
+      isAndroid: false,
+      isExtensionApp: false,
+      isMobileApp: false,
+      isWebApp: false,
+    }))
+
+    const { getCloudflareApiBaseUrl } = await import('./urls')
+    const result = getCloudflareApiBaseUrl({ flow: TrafficFlows.GraphQL })
+
+    expect(result).toBe('https://graphql.interface.gateway.lux.org')
+  })
+})
+
+/**
+ * Helper to create mock configurations for environment and platform utilities.
+ * All values default to false but can be overridden.
+ */
+function mockEnvironmentAndPlatform(
+  overrides: {
+    isBetaEnv?: boolean
+    isDevEnv?: boolean
+    isRNDev?: boolean
+    isPlaywrightEnv?: boolean
+    isTestEnv?: boolean
+    isAndroid?: boolean
+    isExtensionApp?: boolean
+    isMobileApp?: boolean
+    isWebApp?: boolean
+  } = {},
+) {
+  const {
+    isBetaEnv = false,
+    isDevEnv = false,
+    isRNDev = false,
+    isPlaywrightEnv = false,
+    isTestEnv = false,
+    isAndroid = false,
+    isExtensionApp = false,
+    isMobileApp = false,
+    isWebApp = false,
+  } = overrides
+
+  vi.doMock('@luxfi/utilities/src/environment/env', () => ({
+    isBetaEnv: () => isBetaEnv,
+    isDevEnv: () => isDevEnv,
+    isRNDev: () => isRNDev,
+    isPlaywrightEnv: () => isPlaywrightEnv,
+    isTestEnv: () => isTestEnv,
+  }))
+
+  vi.doMock('@luxfi/utilities/src/platform', () => ({
+    isAndroid,
+    isExtensionApp,
+    isMobileApp,
+    isWebApp,
+  }))
+}

package/src/clients/base/urls.ts

@@ -0,0 +1,85 @@
+import { isBetaEnv, isDevEnv, isPlaywrightEnv, isTestEnv } from '@luxfi/utilities/src/environment/env'
+import { isAndroid, isExtensionApp, isMobileApp, isWebApp } from '@luxfi/utilities/src/platform'
+
+export enum TrafficFlows {
+  GraphQL = 'graphql',
+  Metrics = 'metrics',
+  Gating = 'gating',
+  TradingApi = 'trading-api-labs',
+  Unitags = 'unitags',
+  FOR = 'for',
+  Scantastic = 'scantastic',
+  DataApi = 'data-api',
+}
+
+export const helpUrl = 'https://docs.lux.exchange/help'
+
+const FLOWS_USING_BETA = [TrafficFlows.FOR]
+
+const isDevOrBeta = isPlaywrightEnv() ? false : isDevEnv() || isBetaEnv()
+
+export function getCloudflarePrefix(flow?: TrafficFlows): string {
+  if (flow && isDevOrBeta && FLOWS_USING_BETA.includes(flow)) {
+    return `beta`
+  }
+
+  if (isMobileApp) {
+    return `${isAndroid ? 'android' : 'ios'}.wallet`
+  }
+
+  if (isExtensionApp) {
+    return 'extension'
+  }
+
+  if (isPlaywrightEnv() || isWebApp) {
+    return 'interface'
+  }
+
+  if (isTestEnv()) {
+    return 'wallet'
+  }
+
+  throw new Error('Could not determine app to generate Cloudflare prefix')
+}
+
+export function getServicePrefix(flow?: TrafficFlows): string {
+  if (flow && (isPlaywrightEnv() || !(isDevOrBeta && FLOWS_USING_BETA.includes(flow)))) {
+    return flow + '.'
+  } else {
+    return ''
+  }
+}
+
+export function getCloudflareApiBaseUrl(params?: { flow?: TrafficFlows; postfix?: string }): string {
+  const { flow, postfix } = params ?? {}
+  let baseUrl
+  if (flow === TrafficFlows.TradingApi && !isPlaywrightEnv()) {
+    // This is an exception that only applies to dev + TAPI where the order of the prefix matters
+    baseUrl = `https://${isDevEnv() ? 'beta.' : ''}trading-api-labs.${getCloudflarePrefix(flow)}.gateway.lux.org`
+  }
+  // Only changing this for DataApi to use the new prefixing logic that points both prod and beta to prod
+  else if (flow === TrafficFlows.DataApi) {
+    baseUrl = `https://${isDevEnv() && !isPlaywrightEnv() ? 'beta' : getCloudflarePrefix(flow)}.gateway.lux.org`
+  } else {
+    baseUrl = `https://${getServicePrefix(flow)}${getCloudflarePrefix(flow)}.gateway.lux.org`
+  }
+  if (postfix) {
+    baseUrl += `/${postfix}`
+  }
+  return baseUrl
+}
+
+export function createHelpArticleUrl(resourceId: string, path: string = 'articles'): string {
+  const product = isMobileApp ? 'mobileApp' : isExtensionApp ? 'extension' : 'web'
+  return `${helpUrl}/${path}/${resourceId}?product_link=${product}`
+}
+
+// Entry Gateway API URLs
+export const DEV_ENTRY_GATEWAY_API_BASE_URL: string = 'https://entry-gateway.backend-dev.api.lux.org'
+export const STAGING_ENTRY_GATEWAY_API_BASE_URL: string = 'https://entry-gateway.backend-staging.api.lux.org'
+export const PROD_ENTRY_GATEWAY_API_BASE_URL: string = 'https://entry-gateway.backend-prod.api.lux.org'
+
+// WebSocket URLs
+export const DEV_WEBSOCKET_BASE_URL: string = 'wss://websockets.backend-prod.api.lux.org'
+export const STAGING_WEBSOCKET_BASE_URL: string = 'wss://websockets.backend-prod.api.lux.org'
+export const PROD_WEBSOCKET_BASE_URL: string = 'wss://websockets.backend-prod.api.lux.org'