@luxexchange/api 1.0.0

package/src/clients/unitags/types.ts

@@ -0,0 +1,122 @@
+// Internal types
+
+export type UnitagClaim = {
+  address?: string
+  username: string
+  avatarUri?: string
+}
+
+export type UnitagClaimSource = 'onboarding' | 'home' | 'settings'
+
+export type UnitagClaimContext = {
+  source: UnitagClaimSource
+  hasENSAddress: boolean
+}
+
+// API types
+
+export type UnitagUsernameRequest = {
+  username: string
+}
+
+export type UnitagUsernameResponse = {
+  available: boolean
+  requiresEnsMatch: boolean
+  metadata?: ProfileMetadata
+  username?: string
+  address?: {
+    address: Address
+  }
+}
+
+export type UnitagAddressRequest = {
+  address: string
+}
+
+export type UnitagAddressResponse = {
+  username?: string
+  address?: Address
+  metadata?: ProfileMetadata
+}
+
+export type UnitagAddressesRequest = {
+  addresses: Address[]
+}
+
+export type UnitagAddressesResponse = {
+  usernames: {
+    [address: Address]: UnitagAddressResponse
+  }
+}
+
+export type UnitagResponse = {
+  success: boolean
+  errorCode?: UnitagErrorCodes
+}
+
+export type UnitagClaimEligibilityResponse = {
+  canClaim: boolean
+  errorCode?: UnitagErrorCodes
+}
+
+export type ProfileMetadata = {
+  avatar?: string
+  description?: string
+  twitter?: string
+}
+
+export type UnitagClaimUsernameRequestBody = {
+  username: string
+  deviceId: string
+  metadata?: ProfileMetadata
+}
+
+export type UnitagClaimEligibilityRequest = {
+  address?: Address
+  deviceId: string
+  isUsernameChange?: boolean
+}
+
+export type UnitagUpdateMetadataRequestBody = {
+  metadata: ProfileMetadata
+  clearAvatar?: boolean
+}
+
+export type UnitagUpdateMetadataResponse = {
+  success: boolean
+  metadata?: ProfileMetadata
+}
+
+export type UnitagGetAvatarUploadUrlResponse = {
+  success: boolean
+  avatarUrl?: string
+  preSignedUrl?: string
+  s3UploadFields?: Record<string, string>
+}
+
+export type UnitagDeleteUsernameRequestBody = {
+  username: string
+}
+
+export type UnitagAvatarUploadCredentials = {
+  preSignedUrl?: string
+  s3UploadFields?: Record<string, string>
+}
+
+export type UnitagChangeUsernameRequestBody = {
+  username: string
+  deviceId: string
+}
+
+// Copied enum from unitags backend code -- needs to be up-to-date
+export enum UnitagErrorCodes {
+  UnitagNotAvailable = 'unitags-1',
+  RequiresENSMatch = 'unitags-2',
+  IPLimitReached = 'unitags-3',
+  AddressLimitReached = 'unitags-4',
+  DeviceLimitReached = 'unitags-5',
+  DeviceActiveLimitReached = 'unitags-6',
+  AddressActiveLimitReached = 'unitags-7',
+  NoUnitagForAddress = 'unitags-8',
+  UnitagNotActive = 'unitags-9',
+}

package/src/components/ApiInit.test.tsx

@@ -0,0 +1,364 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { render, waitFor } from '@testing-library/react'
+import { ApiInit } from '@luxfi/api/src/components/ApiInit'
+import {
+  ChallengeType,
+  createChallengeSolverService,
+  createDeviceIdService,
+  createNoopPerformanceTracker,
+  createSessionInitializationService,
+  createSessionRepository,
+  createSessionService,
+  createSessionStorage,
+  createLuxIdentifierService,
+  type DeviceIdService,
+  type SessionInitializationService,
+  type SessionService,
+  type SessionStorage,
+  type LuxIdentifierService,
+} from '@luxfi/sessions'
+import React from 'react'
+import { sleep } from '@luxfi/utilities/src/time/timing'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Mock platform detection - we're testing as extension by default
+vi.mock('@luxfi/utilities/src/platform', () => ({
+  isWeb: false,
+  isExtension: true,
+  isInterface: false,
+}))
+
+describe('ApiInit Integration', () => {
+  // Services and mocked boundaries
+  let queryClient: QueryClient
+  let mockStorage: Map<string, any>
+  let mockApiClient: {
+    initSession: ReturnType<typeof vi.fn>
+    challenge: ReturnType<typeof vi.fn>
+    verify: ReturnType<typeof vi.fn>
+  }
+  let sessionStorage: SessionStorage
+  let deviceIdService: DeviceIdService
+  let luxIdentifierService: LuxIdentifierService
+  let sessionService: SessionService
+  let initService: SessionInitializationService
+  let isSessionServiceEnabled: boolean
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // Default to enabled
+    isSessionServiceEnabled = true
+
+    // Mock only the boundaries (storage and network)
+    mockStorage = new Map()
+    mockApiClient = {
+      initSession: vi.fn().mockResolvedValue({
+        sessionId: 'test-session-123',
+        needChallenge: false,
+        extra: {},
+      }),
+      challenge: vi.fn().mockResolvedValue({
+        challengeId: 'challenge-456',
+        challengeType: ChallengeType.TURNSTILE,
+        extra: { sitekey: 'mock-sitekey' },
+        challengeData: { case: undefined },
+      }),
+      verify: vi.fn().mockResolvedValue({
+        retry: false,
+      }),
+    }
+
+    // Create REAL service instances with mocked boundaries
+    sessionStorage = createSessionStorage({
+      getSessionId: async () => mockStorage.get('sessionId') || null,
+      setSessionId: async (id) => {
+        mockStorage.set('sessionId', id)
+      },
+      clearSessionId: async () => {
+        mockStorage.delete('sessionId')
+      },
+    })
+
+    deviceIdService = createDeviceIdService({
+      getDeviceId: async () => mockStorage.get('deviceId') || '',
+      setDeviceId: async (id) => {
+        mockStorage.set('deviceId', id)
+      },
+      removeDeviceId: async () => {
+        mockStorage.delete('deviceId')
+      },
+    })
+
+    luxIdentifierService = createLuxIdentifierService({
+      getLuxIdentifier: async () => mockStorage.get('luxIdentifier') || null,
+      setLuxIdentifier: async (identifier) => {
+        mockStorage.set('luxIdentifier', identifier)
+      },
+      removeLuxIdentifier: async () => {
+        mockStorage.delete('luxIdentifier')
+      },
+    })
+
+    const sessionRepository = createSessionRepository({
+      client: mockApiClient as any,
+    })
+
+    sessionService = createSessionService({
+      sessionStorage,
+      deviceIdService,
+      luxIdentifierService,
+      sessionRepository,
+    })
+
+    const challengeSolverService = createChallengeSolverService()
+    // Add a mock solver for Turnstile
+    challengeSolverService.getSolver = vi.fn().mockReturnValue({
+      solve: vi.fn().mockResolvedValue('mock-solution'),
+    })
+
+    initService = createSessionInitializationService({
+      getSessionService: () => sessionService,
+      challengeSolverService,
+      performanceTracker: createNoopPerformanceTracker(),
+      getIsSessionUpgradeAutoEnabled: () => true,
+    })
+
+    // Fresh query client for each test
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false,
+          gcTime: 0,
+        },
+      },
+    })
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('initializes session and makes it available for API requests', async () => {
+    // Act: Render the component
+    render(
+      <QueryClientProvider client={queryClient}>
+        <ApiInit getSessionInitService={() => initService} isSessionServiceEnabled={isSessionServiceEnabled} />
+      </QueryClientProvider>,
+    )
+
+    // Assert: Session was initialized
+    await waitFor(() => {
+      expect(mockApiClient.initSession).toHaveBeenCalled()
+    })
+
+    // Wait a bit for async storage operations to complete
+    await sleep(50)
+
+    // Assert: Session is now stored and retrievable
+    const storedSession = await sessionStorage.get()
+    expect(storedSession?.sessionId).toBe('test-session-123')
+
+    // Verify storage was actually set
+    expect(mockStorage.get('sessionId')).toBe('test-session-123')
+  })
+
+  it('completes challenge flow when required by server', async () => {
+    // Setup: Server requires challenge
+    mockApiClient.initSession.mockResolvedValue({
+      sessionId: 'challenge-session',
+      needChallenge: true,
+      extra: {},
+    })
+
+    // Act
+    render(
+      <QueryClientProvider client={queryClient}>
+        <ApiInit getSessionInitService={() => initService} isSessionServiceEnabled={isSessionServiceEnabled} />
+      </QueryClientProvider>,
+    )
+
+    // Assert: Full flow completes
+    await waitFor(() => {
+      expect(mockApiClient.initSession).toHaveBeenCalled()
+      expect(mockApiClient.challenge).toHaveBeenCalled()
+      expect(mockApiClient.verify).toHaveBeenCalled()
+    })
+
+    // Assert: Session is stored after challenge
+    const storedSession = await sessionStorage.get()
+    expect(storedSession?.sessionId).toBe('challenge-session')
+  })
+
+  it('always calls initSession - backend handles session reuse', async () => {
+    // Setup: Pre-populate storage with existing session
+    await sessionStorage.set({ sessionId: 'existing-session' })
+
+    // Mock backend to return the same session ID (simulating session reuse)
+    mockApiClient.initSession.mockResolvedValue({
+      sessionId: 'existing-session',
+      needChallenge: false,
+      extra: {},
+    })
+
+    // Act
+    render(
+      <QueryClientProvider client={queryClient}>
+        <ApiInit getSessionInitService={() => initService} isSessionServiceEnabled={isSessionServiceEnabled} />
+      </QueryClientProvider>,
+    )
+
+    // Wait for initialization
+    await waitFor(() => {
+      expect(mockApiClient.initSession).toHaveBeenCalled()
+    })
+
+    // Assert: initSession IS called (backend decides to reuse based on X-Session-ID header)
+    expect(mockApiClient.initSession).toHaveBeenCalledTimes(1)
+
+    // Session in storage should match what backend returned
+    const storedSession = await sessionStorage.get()
+    expect(storedSession?.sessionId).toBe('existing-session')
+  })
+
+  it('retries initialization on transient failures', async () => {
+    // Use fake timers to speed up retry delays
+    vi.useFakeTimers()
+
+    let attemptCount = 0
+
+    // Mock the initialize method of the initService directly
+    // This will properly trigger React Query's retry logic
+    initService.initialize = vi.fn().mockImplementation(async () => {
+      attemptCount++
+      if (attemptCount < 3) {
+        throw new Error('Network error')
+      }
+      // Mock successful initialization after retries
+      await sessionStorage.set({ sessionId: 'retry-success' })
+      return { sessionId: 'retry-success', needChallenge: false, extra: {} }
+    })
+
+    // Use query client with no default retries - component controls retry
+    const retryClient = new QueryClient({
+      defaultOptions: {
+        queries: {
+          retry: false, // Let component control retries
+        },
+      },
+    })
+
+    // Act
+    render(
+      <QueryClientProvider client={retryClient}>
+        <ApiInit getSessionInitService={() => initService} isSessionServiceEnabled={isSessionServiceEnabled} />
+      </QueryClientProvider>,
+    )
+
+    // Fast-forward through the retry delays
+    await vi.waitFor(
+      async () => {
+        // Advance timers to trigger retries
+        await vi.advanceTimersByTimeAsync(1000) // First retry after 1000ms
+        await vi.advanceTimersByTimeAsync(2000) // Second retry after 2000ms
+        expect(initService.initialize).toHaveBeenCalledTimes(3)
+      },
+      { timeout: 500 }, // Much faster with fake timers
+    )
+
+    const storedSession = await sessionStorage.get()
+    expect(storedSession?.sessionId).toBe('retry-success')
+
+    // Restore real timers
+    vi.useRealTimers()
+  })
+
+  it('prevents duplicate initialization on re-renders', async () => {
+    const { rerender } = render(
+      <QueryClientProvider client={queryClient}>
+        <ApiInit getSessionInitService={() => initService} isSessionServiceEnabled={isSessionServiceEnabled} />
+      </QueryClientProvider>,
+    )
+
+    await waitFor(() => {
+      expect(mockApiClient.initSession).toHaveBeenCalledTimes(1)
+    })
+
+    // Re-render multiple times
+    rerender(
+      <QueryClientProvider client={queryClient}>
+        <ApiInit getSessionInitService={() => initService} isSessionServiceEnabled={isSessionServiceEnabled} />
+      </QueryClientProvider>,
+    )
+
+    rerender(
+      <QueryClientProvider client={queryClient}>
+        <ApiInit getSessionInitService={() => initService} isSessionServiceEnabled={isSessionServiceEnabled} />
+      </QueryClientProvider>,
+    )
+
+    // Wait to ensure no additional calls
+    await sleep(100)
+
+    // Assert: Still only initialized once due to React Query caching
+    expect(mockApiClient.initSession).toHaveBeenCalledTimes(1)
+  })
+
+  it('should not initialize session when feature flag is disabled', async () => {
+    // Set feature flag as disabled
+    isSessionServiceEnabled = false
+
+    render(
+      <QueryClientProvider client={queryClient}>
+        <ApiInit getSessionInitService={() => initService} isSessionServiceEnabled={isSessionServiceEnabled} />
+      </QueryClientProvider>,
+    )
+
+    // Wait to ensure no calls are made
+    await new Promise((resolve) => setTimeout(resolve, 100))
+
+    // Assert: No session initialization should occur
+    expect(mockApiClient.initSession).not.toHaveBeenCalled()
+    expect(mockApiClient.challenge).not.toHaveBeenCalled()
+    expect(mockApiClient.verify).not.toHaveBeenCalled()
+  })
+
+  it('should wait for feature flag to be enabled before initializing session', async () => {
+    // Start with feature flag disabled (simulating Statsig loading)
+    isSessionServiceEnabled = false
+
+    const { rerender } = render(
+      <QueryClientProvider client={queryClient}>
+        <ApiInit getSessionInitService={() => initService} isSessionServiceEnabled={isSessionServiceEnabled} />
+      </QueryClientProvider>,
+    )
+
+    // Assert that initialization does not happen while flag is disabled
+    // Use a try/catch with waitFor to verify the call never happens
+    await expect(
+      waitFor(
+        () => {
+          expect(mockApiClient.initSession).toHaveBeenCalled()
+        },
+        { timeout: 100 },
+      ),
+    ).rejects.toThrow()
+
+    // Verify it still hasn't been called
+    expect(mockApiClient.initSession).not.toHaveBeenCalled()
+
+    // Now simulate feature flag becoming enabled (Statsig loaded)
+    isSessionServiceEnabled = true
+
+    // Trigger a re-render
+    rerender(
+      <QueryClientProvider client={queryClient}>
+        <ApiInit getSessionInitService={() => initService} isSessionServiceEnabled={isSessionServiceEnabled} />
+      </QueryClientProvider>,
+    )
+
+    // Now session initialization should occur
+    await waitFor(() => {
+      expect(mockApiClient.initSession).toHaveBeenCalled()
+    })
+  })
+})

package/src/components/ApiInit.tsx

@@ -0,0 +1,71 @@
+import { queryOptions, useQuery } from '@tanstack/react-query'
+import { SharedQueryClient } from '@luxexchange/api/src/clients/base/SharedQueryClient'
+import type { SessionInitializationService, SessionInitResult } from '@luxexchange/sessions'
+import { SessionError } from '@luxexchange/sessions'
+import { useState } from 'react'
+import type { Logger } from '@luxfi/utilities/src/logger/logger'
+import { ReactQueryCacheKey } from '@luxfi/utilities/src/reactQuery/cache'
+
+interface ApiInitProps {
+  getSessionInitService: () => SessionInitializationService
+  isSessionServiceEnabled: boolean
+}
+
+/**
+ * Query key for session initialization.
+ * Shared between ApiInit (which triggers the query) and InitializationStatusProvider (which observes it).
+ */
+export const SESSION_INIT_QUERY_KEY = [ReactQueryCacheKey.Session, 'initialization'] as const
+
+function createInitServiceQuery(ctx: {
+  getSessionInitService: () => SessionInitializationService
+  getLogger?: () => Logger
+}): ReturnType<typeof queryOptions<SessionInitResult>> {
+  return queryOptions<SessionInitResult>({
+    queryKey: SESSION_INIT_QUERY_KEY,
+    queryFn: async (): Promise<SessionInitResult> => {
+      const service = ctx.getSessionInitService()
+      return service.initialize()
+    },
+    retry: (failureCount, error) => {
+      const logger = ctx.getLogger?.()
+      // Don't retry any session-related errors - these are terminal errors
+      if (error instanceof SessionError) {
+        logger?.error(error, {
+          tags: {
+            file: 'ApiInit.tsx',
+            function: 'createInitServiceQuery',
+          },
+        })
+        return false
+      }
+
+      logger?.warn('ApiInit.tsx', 'createInitServiceQuery', 'retry', failureCount, error)
+      // For other errors (network issues, etc.), retry up to 3 times
+      return failureCount < 3
+    },
+    retryDelay: (attemptIndex: number) => Math.min(1000 * 2 ** attemptIndex, 30000), // Exponential backoff
+    refetchOnMount: false,
+    refetchOnWindowFocus: false,
+    refetchOnReconnect: false,
+  })
+}
+
+function ApiInit({ getSessionInitService, isSessionServiceEnabled }: ApiInitProps): null {
+  const [query] = useState(() => createInitServiceQuery({ getSessionInitService }))
+
+  useQuery({
+    ...query,
+    enabled: isSessionServiceEnabled,
+  })
+
+  return null
+}
+
+/** Reinitializes the session by invalidating the session initialization query. Resolves once the query has re-run. */
+export async function reinitializeSession(): Promise<void> {
+  await SharedQueryClient.invalidateQueries({ queryKey: SESSION_INIT_QUERY_KEY })
+}
+
+export { ApiInit }
+export type { ApiInitProps }

package/src/connectRpc/base.ts

@@ -0,0 +1,33 @@
+import { type StreamResponse, type Transport, type UnaryResponse } from '@connectrpc/connect'
+import { type ConnectTransportOptions, createConnectTransport } from '@connectrpc/connect-web'
+
+// The string arg to pass to the BE for chainId to get data for all networks
+export const ALL_NETWORKS_ARG = 'ALL_NETWORKS'
+
+export interface ConnectRpcContext {
+  baseUrl: string
+  additionalHeaders?: HeadersInit
+}
+
+export const createConnectTransportWithDefaults = (
+  context: ConnectRpcContext,
+  transportOptions: Partial<ConnectTransportOptions> = {},
+): Transport =>
+  createConnectTransport({
+    baseUrl: context.baseUrl,
+    interceptors: context.additionalHeaders
+      ? [
+          (next) =>
+            (request): Promise<UnaryResponse | StreamResponse> => {
+              if (context.additionalHeaders) {
+                const headers = new Headers(context.additionalHeaders)
+                headers.forEach((value, key) => {
+                  request.header.set(key, value)
+                })
+              }
+              return next(request)
+            },
+        ]
+      : [],
+    ...transportOptions,
+  })