@luxexchange/api 1.0.0

package/src/session/createSessionTransport.ts

@@ -0,0 +1,107 @@
+import { type ConnectTransportOptions, createConnectTransport } from '@connectrpc/connect-web'
+
+/**
+ * Options for creating a session transport.
+ * All configuration is explicit - no platform detection.
+ */
+export interface CreateSessionTransportOptions {
+  /** Entry gateway URL */
+  baseUrl: string
+
+  /** Static headers to include in all requests (e.g., x-request-source, x-lux-timezone) */
+  headers?: Record<string, string>
+
+  /** Cookie header for SSR forwarding */
+  cookie?: string
+
+  /** Use browser credentials for automatic cookie handling (for web with cookies) */
+  credentials?: 'include' | 'omit' | 'same-origin'
+
+  /** Dynamic session ID getter (for mobile/extension that use headers instead of cookies) */
+  getSessionId?: () => Promise<string | null>
+
+  /** Dynamic device ID getter (for mobile/extension that use headers instead of cookies) */
+  getDeviceId?: () => Promise<string | null>
+
+  /** Additional ConnectRPC transport options */
+  transportOptions?: Partial<ConnectTransportOptions>
+}
+
+/**
+ * Creates a ConnectRPC transport with explicit configuration.
+ *
+ * This is a pure factory function with no platform detection.
+ * The caller (app-level provider) is responsible for providing
+ * the correct configuration for their platform/context.
+ *
+ * @example
+ * // Web browser - uses cookies automatically
+ * const transport = createSessionTransport({
+ *   baseUrl: entryGatewayUrl,
+ *   credentials: 'include',
+ *   headers: {
+ *     'x-request-source': 'lux-web',
+ *     'x-lux-timezone': Intl.DateTimeFormat().resolvedOptions().timeZone,
+ *   },
+ * })
+ *
+ * @example
+ * // SSR - forwards cookies from incoming request
+ * const transport = createSessionTransport({
+ *   baseUrl: config.entryGatewayUrl,
+ *   cookie: request.headers.get('Cookie'),
+ *   headers: {
+ *     'x-request-source': 'lux-web',
+ *     'x-lux-timezone': timezone,
+ *   },
+ * })
+ *
+ * @example
+ * // Mobile - uses headers for session/device IDs
+ * const transport = createSessionTransport({
+ *   baseUrl: entryGatewayUrl,
+ *   headers: { 'x-request-source': 'lux-mobile' },
+ *   getSessionId: () => sessionStorage.get().then(s => s?.sessionId ?? null),
+ *   getDeviceId: () => deviceIdService.getDeviceId(),
+ * })
+ */
+export function createSessionTransport(
+  options: CreateSessionTransportOptions,
+): ReturnType<typeof createConnectTransport> {
+  const { baseUrl, headers, cookie, credentials, getSessionId, getDeviceId, transportOptions } = options
+
+  return createConnectTransport({
+    baseUrl,
+    credentials,
+    interceptors: [
+      (next) => async (request) => {
+        if (headers) {
+          for (const [key, value] of Object.entries(headers)) {
+            request.header.set(key, value)
+          }
+        }
+
+        if (cookie) {
+          request.header.set('Cookie', cookie)
+        }
+
+        if (getSessionId) {
+          const sessionId = await getSessionId()
+          if (sessionId) {
+            request.header.set('X-Session-ID', sessionId)
+          }
+        }
+
+        if (getDeviceId) {
+          const deviceId = await getDeviceId()
+          if (deviceId) {
+            request.header.set('X-Device-ID', deviceId)
+          }
+        }
+
+        return next(request)
+      },
+    ],
+    ...transportOptions,
+  })
+}

package/src/session/createWithSessionRetry.ts

@@ -0,0 +1,33 @@
+import { is401Error } from '@luxexchange/api'
+
+/** Creates a function that will attempt to reinitialize the app session and retry the input function once, if the first invocation of the function fails. */
+export function createWithSessionRetry(ctx: {
+  reinitializeSession: () => Promise<void>
+  onReinitializationFailed?: () => void
+}) {
+  return async function withSessionRetry<T>(fn: () => Promise<T>): Promise<T> {
+    // Attempt 1
+    try {
+      return await fn()
+    } catch (error) {
+      // After first 401, reinitialize session and do not throw
+      if (is401Error(error)) {
+        await ctx.reinitializeSession()
+      } else {
+        throw error
+      }
+    }
+
+    // Attempt 2
+    try {
+      return await fn()
+    } catch (errorAfterReinitialization) {
+      if (is401Error(errorAfterReinitialization)) {
+        // Handle any side effects of reinitialization failure
+        ctx.onReinitializationFailed?.()
+      }
+      // Always throw error after reinitialization failure
+      throw errorAfterReinitialization
+    }
+  }
+}

package/src/session/index.ts

@@ -0,0 +1,12 @@
+/* eslint-disable check-file/no-index */
+/**
+ * Session Transport
+ *
+ * Pure factory functions for creating session-aware transports.
+ * These have no platform detection - the caller provides all configuration.
+ */
+
+export {
+  type CreateSessionTransportOptions,
+  createSessionTransport,
+} from '@luxexchange/api/src/session/createSessionTransport'

package/src/storage/createExtensionStorageDriver.ts

@@ -0,0 +1,29 @@
+import type { StorageDriver } from '@luxfi/api/src/storage/types'
+import { getChromeWithThrow } from '@luxfi/utilities/src/chrome/chrome'
+
+export function createExtensionStorageDriver(): StorageDriver {
+  return {
+    async get(key: string): Promise<string | null> {
+      const chrome = getChromeWithThrow()
+      const result = await chrome.storage.local.get(key)
+      const value = result[key]
+      if (value === undefined || value === null) {
+        return null
+      }
+      if (typeof value !== 'string') {
+        throw new Error(`[StorageDriver.web.ts] Storage driver currently expects string values, got ${typeof value}`)
+      }
+      return value
+    },
+
+    async set(key: string, value: string): Promise<void> {
+      const chrome = getChromeWithThrow()
+      await chrome.storage.local.set({ [key]: value })
+    },
+
+    async remove(key: string): Promise<void> {
+      const chrome = getChromeWithThrow()
+      await chrome.storage.local.remove(key)
+    },
+  }
+}

package/src/storage/createNativeStorageDriver.ts

@@ -0,0 +1,19 @@
+import { StorageDriver } from '@luxfi/api/src/storage/types'
+import * as SecureStore from 'expo-secure-store'
+
+export function createNativeStorageDriver(): StorageDriver {
+  return {
+    async get(key: string): Promise<string | null> {
+      const value = await SecureStore.getItemAsync(key)
+      return value ?? null
+    },
+
+    async set(key: string, value: string): Promise<void> {
+      await SecureStore.setItemAsync(key, value)
+    },
+
+    async remove(key: string): Promise<void> {
+      await SecureStore.deleteItemAsync(key)
+    },
+  }
+}

package/src/storage/createWebStorageDriver.ts

@@ -0,0 +1,17 @@
+import { type StorageDriver } from '@luxfi/api/src/storage/types'
+
+export function createWebStorageDriver(): StorageDriver {
+  return {
+    async get(key: string): Promise<string | null> {
+      return localStorage.getItem(key)
+    },
+
+    async set(key: string, value: string): Promise<void> {
+      localStorage.setItem(key, value)
+    },
+
+    async remove(key: string): Promise<void> {
+      localStorage.removeItem(key)
+    },
+  }
+}

package/src/storage/getStorageDriver.native.ts

@@ -0,0 +1,6 @@
+import { createNativeStorageDriver } from '@luxfi/api/src/storage/createNativeStorageDriver'
+import { type StorageDriver } from '@luxfi/api/src/storage/types'
+
+export function getStorageDriver(): StorageDriver {
+  return createNativeStorageDriver()
+}

package/src/storage/getStorageDriver.ts

@@ -0,0 +1,8 @@
+import { StorageDriver } from '@luxfi/api/src/storage/types'
+import { PlatformSplitStubError } from '@luxfi/utilities/src/errors'
+
+export function getStorageDriver(): StorageDriver {
+  throw new PlatformSplitStubError('getStorageDriver')
+}
+
+export type { StorageDriver } from '@luxfi/api/src/storage/types'

package/src/storage/getStorageDriver.web.ts

@@ -0,0 +1,11 @@
+import { createExtensionStorageDriver } from '@luxfi/api/src/storage/createExtensionStorageDriver'
+import { createWebStorageDriver } from '@luxfi/api/src/storage/createWebStorageDriver'
+import { type StorageDriver } from '@luxfi/api/src/storage/types'
+import { isExtensionApp } from '@luxfi/utilities/src/platform'
+
+export function getStorageDriver(): StorageDriver {
+  if (isExtensionApp) {
+    return createExtensionStorageDriver()
+  }
+  return createWebStorageDriver()
+}

package/src/storage/types.ts

@@ -0,0 +1,9 @@
+/**
+ * Storage driver interface for key-value storage
+ * Platform-specific implementations handle the actual storage mechanism
+ */
+export interface StorageDriver {
+  get(key: string): Promise<string | null>
+  set(key: string, value: string): Promise<void>
+  remove(key: string): Promise<void>
+}

package/src/transport.ts

@@ -0,0 +1,85 @@
+import { type ConnectTransportOptions, createConnectTransport } from '@connectrpc/connect-web'
+import { provideDeviceIdService } from '@luxfi/api/src/provideDeviceIdService'
+import { provideSessionStorage } from '@luxfi/api/src/provideSessionStorage'
+import { isWebApp } from '@luxfi/utilities/src/platform'
+
+interface SessionTransportOptions {
+  getSessionId?: () => Promise<string | null>
+  getDeviceId?: () => Promise<string | null>
+  getBaseUrl: () => string
+  getHeaders?: () => object
+  options?: Partial<ConnectTransportOptions>
+}
+
+/**
+ * Creates a Connect transport that includes session and device headers.
+ *
+ * This is the most basic transport util. Use this if you have a new use case for a transport.
+ * (For example, a TestTransport that doesn't use the Session storage)
+ * Otherwise, you can use the getTransport util.
+ */
+function createTransport(ctx: SessionTransportOptions): ReturnType<typeof createConnectTransport> {
+  const { getSessionId, getDeviceId, getBaseUrl, getHeaders, options } = ctx
+
+  const transportOptions: ConnectTransportOptions = {
+    baseUrl: getBaseUrl(),
+    interceptors: [
+      (next) => async (request) => {
+        // Add session ID header for mobile/extension
+        // Web uses cookies automatically
+        if (!isWebApp) {
+          const [sessionId, deviceId] = await Promise.all([getSessionId?.(), getDeviceId?.()])
+          if (sessionId) {
+            request.header.set('X-Session-ID', sessionId)
+          }
+          if (deviceId) {
+            request.header.set('X-Device-ID', deviceId)
+          }
+        }
+
+        const extraHeaders = getHeaders?.()
+        if (extraHeaders) {
+          Object.entries(extraHeaders).forEach(([key, value]) => {
+            request.header.set(key, value)
+          })
+        }
+
+        return next(request)
+      },
+    ],
+    ...options,
+  }
+
+  return createConnectTransport(transportOptions)
+}
+
+/**
+ * Configures a Connect transport that uses the primary Session storage.
+ */
+function getTransport(ctx: {
+  getBaseUrl: () => string
+  getHeaders?: () => object
+  options?: Partial<ConnectTransportOptions>
+}): ReturnType<typeof createConnectTransport> {
+  return createTransport({
+    getBaseUrl: ctx.getBaseUrl,
+    async getSessionId() {
+      if (isWebApp) {
+        return null
+      }
+      return provideSessionStorage()
+        .get()
+        .then((session) => session?.sessionId ?? null)
+    },
+    async getDeviceId() {
+      if (isWebApp) {
+        return null
+      }
+      return provideDeviceIdService().getDeviceId()
+    },
+    getHeaders: ctx.getHeaders,
+    options: ctx.options,
+  })
+}
+
+export { getTransport }

package/stubs/privy-service-connect.d.ts

@@ -0,0 +1,3 @@
+// Type stub for @uniswap/client-privy-embedded-wallet when the private package is not installed.
+import type { ServiceType } from '@bufbuild/protobuf'
+export declare const EmbeddedWalletService: ServiceType

package/stubs/privy-service-pb.d.ts

@@ -0,0 +1,60 @@
+// Type stubs for @uniswap/client-privy-embedded-wallet when the private package is not installed.
+
+export declare enum AuthenticationTypes {
+  AUTHENTICATION_TYPE_UNSPECIFIED = 0,
+  PASSKEY_REGISTRATION = 1,
+  PASSKEY_AUTHENTICATION = 2,
+}
+
+export declare enum Action {
+  ACTION_UNSPECIFIED = 0,
+  CREATE_WALLET = 1,
+  SIGN_MESSAGE = 2,
+  SIGN_TRANSACTION = 3,
+  SIGN_TYPED_DATA = 4,
+  WALLET_SIGNIN = 5,
+  EXPORT_SEED_PHRASE = 6,
+  DELETE_RECORD = 7,
+  REGISTER_NEW_AUTHENTICATION_TYPES = 8,
+  LIST_AUTHENTICATORS = 9,
+}
+
+export declare enum RegistrationOptions_AuthenticatorAttachment {
+  AUTHENTICATOR_ATTACHMENT_UNSPECIFIED = 0,
+  PLATFORM = 1,
+  CROSS_PLATFORM = 2,
+}
+
+export declare class ChallengeResponse {
+  challengeOptions: string
+}
+
+export declare class CreateWalletResponse {
+  walletAddress: string
+  walletId: string
+}
+
+export declare class DisconnectResponse {}
+
+export declare class RegistrationOptions {
+  authenticatorAttachment?: RegistrationOptions_AuthenticatorAttachment
+  username?: string
+}
+
+export declare class WalletSignInResponse {
+  walletAddress: string
+  walletId: string
+  exported?: boolean
+}
+
+export declare class SignMessageResponse {
+  signature: string
+}
+
+export declare class SignTransactionResponse {
+  signature: string
+}
+
+export declare class SignTypedDataResponse {
+  signature: string
+}

package/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "extends": "../../config/tsconfig/app.json",
+  "include": [
+    "src/**/*.ts",
+    "src/*.ts",
+    "src/**/*.d.ts",
+    "src/**/*.json",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "src/**/*.mts"
+  ],
+  "exclude": ["src/**/*.spec.ts", "src/**/*.spec.tsx", "src/**/*.test.ts", "src/**/*.test.tsx"],
+  "compilerOptions": {
+    "emitDeclarationOnly": true,
+    "noEmit": false,
+    "paths": {
+      "@universe/api/*": ["./src/*"],
+      "@uniswap/client-privy-embedded-wallet/dist/uniswap/privy-embedded-wallet/v1/service_pb": [
+        "../../node_modules/@uniswap/client-privy-embedded-wallet/dist/uniswap/privy-embedded-wallet/v1/service_pb",
+        "./stubs/privy-service-pb"
+      ]
+    },
+    "types": ["chrome", "node"]
+  },
+  "types": ["vitest/globals"],
+  "references": [
+    {
+      "path": "../utilities"
+    },
+    {
+      "path": "../sessions"
+    },
+    {
+      "path": "../config"
+    }
+  ]
+}

package/tsconfig.lint.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "preserveSymlinks": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": []
+}

package/tsconfig.spec.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "types": ["node"]
+  },
+  "include": ["src/**/*.test.ts", "src/**/*.spec.ts", "src/**/*.d.ts"],
+  "exclude": []
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    watch: false,
+    environment: 'jsdom',
+    coverage: {
+      exclude: ['**/__generated__/**', '**/node_modules/**', '**/dist/**', '**/*.config.*', '**/scripts/**'],
+    },
+  },
+  resolve: {
+    extensions: ['.web.ts', '.web.tsx', '.ts', '.tsx', '.js', '.jsx', '.json'],
+  },
+})