@luxexchange/api 1.0.0

package/src/clients/jupiter/createJupiterApiClient.ts

@@ -0,0 +1,42 @@
+import type { FetchClient } from '@luxfi/api/src/clients/base/types'
+import {
+  type JupiterExecuteResponse,
+  type JupiterExecuteUrlParams,
+  type JupiterOrderResponse,
+  type JupiterOrderUrlParams,
+  jupiterExecuteResponseSchema,
+  jupiterOrderResponseSchema,
+} from '@luxfi/api/src/clients/jupiter/types'
+import { buildQuery } from '@luxfi/api/src/clients/jupiter/utils'
+
+export interface JupiterApiClient {
+  fetchOrder: (params: JupiterOrderUrlParams) => Promise<JupiterOrderResponse>
+  execute: (params: JupiterExecuteUrlParams) => Promise<JupiterExecuteResponse>
+}
+
+export const JUPITER_API_PATHS = {
+  order: '/order',
+  execute: '/execute',
+}
+
+export function createJupiterApiClient(ctx: { fetchClient: FetchClient }): JupiterApiClient {
+  async function fetchOrder(params: JupiterOrderUrlParams): Promise<JupiterOrderResponse> {
+    const query = buildQuery(params)
+    const result = await ctx.fetchClient.get(JUPITER_API_PATHS.order + '?' + query.toString())
+
+    return jupiterOrderResponseSchema.parse(result)
+  }
+
+  async function execute(params: JupiterExecuteUrlParams): Promise<JupiterExecuteResponse> {
+    const result = await ctx.fetchClient.post(JUPITER_API_PATHS.execute, {
+      body: JSON.stringify(params),
+    })
+
+    return jupiterExecuteResponseSchema.parse(result)
+  }
+
+  return {
+    fetchOrder,
+    execute,
+  }
+}

package/src/clients/jupiter/types.ts

@@ -0,0 +1,92 @@
+import { Prettify } from 'viem'
+import { z } from 'zod'
+
+// Input types based on https://dev.jup.ag/docs/api/ultra-api/order, although some are missing from their documentation.
+// Non-documented fields are discoverable via inspecting jup.ag's network requests.
+
+export type JupiterOrderUrlParams = {
+  inputMint: string
+  outputMint: string
+  amount: string
+  taker?: string
+  referralAccount?: string
+  referralFee?: string
+  slippageBps?: string
+  swapMode: 'ExactIn' | 'ExactOut'
+}
+
+// Output types derived from https://dev.jup.ag/docs/api/ultra-api/order
+// Some unused fields are commented out for potential future use.
+
+const swapInfoSchema = z.looseObject({
+  ammKey: z.string().nullish(),
+  label: z.string().nullish(),
+  inputMint: z.string(),
+  outputMint: z.string(),
+})
+
+const routePlanSchema = z.array(
+  z.looseObject({
+    swapInfo: swapInfoSchema,
+    percent: z.number(),
+  }),
+)
+
+const platformFeeSchema = z.looseObject({
+  // amount: z.string(), // amount is documented as required but occasionally returns undefined -- we calculate it on our own
+  feeBps: z.number().nullish(),
+})
+
+const routerTypeSchema = z.string().transform((val) => {
+  const normalized = val === 'iris' || val === 'jupiterz' || val === 'dflow' || val === 'okx' ? val : 'unknown'
+  return { raw: val, normalized } as const
+})
+
+export const jupiterOrderResponseSchema = z.looseObject({
+  inputMint: z.string(),
+  outputMint: z.string(),
+  inAmount: z.string(),
+  outAmount: z.string(),
+  otherAmountThreshold: z.string(),
+  swapMode: z.enum(['ExactIn', 'ExactOut']),
+  slippageBps: z.number(),
+  priceImpactPct: z.string().nullish(),
+  routePlan: routePlanSchema.nullish(),
+  // Represents just swap fee
+  platformFee: platformFeeSchema.nullish(),
+  // feeBps: z.number().nullish(), // `response.feeBps` represents total fee (for example, swap fee + fee for gasless support); currently we use `response.platformFee` to get the swap fee and ignore gasless support fee specifics.
+  feeMint: z.string().nullish(),
+  prioritizationFeeLamports: z.number(),
+  router: routerTypeSchema,
+  transaction: z.string().nullish(),
+  gasless: z.boolean().nullish(),
+  requestId: z.string(),
+  // totalTime: z.number(),
+  taker: z.string().nullish(),
+  quoteId: z.string().nullish(),
+  maker: z.string().nullish(),
+  // expireAt: z.string().nullish(),
+  // dynamicSlippageReport: dynamicSlippageReportSchema.nullish(),
+  errorMessage: z.string().nullish(),
+  errorCode: z.number().nullish(),
+})
+
+export type JupiterOrderResponse = Prettify<z.infer<typeof jupiterOrderResponseSchema>>
+
+// Types derived from https://dev.jup.ag/docs/api/ultra-api/execute
+
+const StatusEnum = z.enum(['Success', 'Failed'])
+
+export const jupiterExecuteResponseSchema = z.looseObject({
+  status: StatusEnum,
+  signature: z.string().nullish(),
+  error: z.string().nullish(),
+  code: z.number(),
+})
+
+export type JupiterExecuteResponse = z.infer<typeof jupiterExecuteResponseSchema>
+
+export type JupiterExecuteUrlParams = {
+  signedTransaction: string
+  requestId: string
+}

package/src/clients/jupiter/utils.ts

@@ -0,0 +1,27 @@
+import type { JupiterOrderUrlParams } from '@luxfi/api/src/clients/jupiter/types'
+
+export function buildQuery(params: JupiterOrderUrlParams): URLSearchParams {
+  const query = new URLSearchParams()
+
+  query.set('inputMint', params.inputMint)
+
+  query.set('outputMint', params.outputMint)
+
+  query.set('amount', params.amount.toString())
+
+  query.set('swapMode', params.swapMode)
+
+  if (params.taker) {
+    query.set('taker', params.taker)
+  }
+  if (params.referralAccount) {
+    query.set('referralAccount', params.referralAccount)
+  }
+  if (params.referralFee) {
+    query.set('referralFee', params.referralFee.toString())
+  }
+  if (params.slippageBps) {
+    query.set('slippageBps', params.slippageBps.toString())
+  }
+  return query
+}

package/src/clients/liquidity/createAuctionMutationClient.ts

@@ -0,0 +1,41 @@
+import { type PartialMessage } from '@bufbuild/protobuf'
+import { type PromiseClient } from '@connectrpc/connect'
+import { type AuctionService } from '@uniswap/client-liquidity/dist/uniswap/liquidity/v1/auction_connect'
+import type {
+  ExitBidAndClaimTokensRequest,
+  ExitBidAndClaimTokensResponse,
+  ExitBidPositionRequest,
+  ExitBidPositionResponse,
+  SubmitBidRequest,
+  SubmitBidResponse,
+  TokenCountAllocatedToLpForAuctionRequest,
+  TokenCountAllocatedToLpForAuctionResponse,
+  VerifyWalletRequest,
+  VerifyWalletResponse,
+} from '@uniswap/client-liquidity/dist/uniswap/liquidity/v1/auction_pb'
+
+interface AuctionMutationClientContext {
+  rpcClient: PromiseClient<typeof AuctionService>
+}
+
+export interface AuctionMutationClient {
+  submitBid: (params: PartialMessage<SubmitBidRequest>) => Promise<SubmitBidResponse>
+  exitBidAndClaimTokens: (
+    params: PartialMessage<ExitBidAndClaimTokensRequest>,
+  ) => Promise<ExitBidAndClaimTokensResponse>
+  exitBidPosition: (params: PartialMessage<ExitBidPositionRequest>) => Promise<ExitBidPositionResponse>
+  tokenCountAllocatedToLpForAuction: (
+    params: PartialMessage<TokenCountAllocatedToLpForAuctionRequest>,
+  ) => Promise<TokenCountAllocatedToLpForAuctionResponse>
+  verifyWallet: (params: PartialMessage<VerifyWalletRequest>) => Promise<VerifyWalletResponse>
+}
+
+export function createAuctionMutationClient({ rpcClient }: AuctionMutationClientContext): AuctionMutationClient {
+  return {
+    submitBid: (params) => rpcClient.submitBid(params),
+    exitBidAndClaimTokens: (params) => rpcClient.exitBidAndClaimTokens(params),
+    exitBidPosition: (params) => rpcClient.exitBidPosition(params),
+    tokenCountAllocatedToLpForAuction: (params) => rpcClient.tokenCountAllocatedToLpForAuction(params),
+    verifyWallet: (params) => rpcClient.verifyWallet(params),
+  }
+}

package/src/clients/liquidity/createLiquidityServiceClient.ts

@@ -0,0 +1,56 @@
+import { type PromiseClient } from '@connectrpc/connect'
+import { type LiquidityService } from '@uniswap/client-liquidity/dist/uniswap/liquidity/v1/api_connect'
+import type {
+  CheckApprovalLPRequest,
+  CheckApprovalLPResponse,
+  ClaimLPFeesRequest,
+  ClaimLPFeesResponse,
+  ClaimLPRewardsRequest,
+  ClaimLPRewardsResponse,
+  CreateLPPositionRequest,
+  CreateLPPositionResponse,
+  DecreaseLPPositionRequest,
+  DecreaseLPPositionResponse,
+  GetLPPriceDiscrepancyRequest,
+  GetLPPriceDiscrepancyResponse,
+  IncreaseLPPositionRequest,
+  IncreaseLPPositionResponse,
+  MigrateV2ToV3LPPositionRequest,
+  MigrateV2ToV3LPPositionResponse,
+  MigrateV3ToV4LPPositionRequest,
+  MigrateV3ToV4LPPositionResponse,
+  PoolInfoRequest,
+  PoolInfoResponse,
+} from '@uniswap/client-liquidity/dist/uniswap/liquidity/v1/api_pb'
+
+interface LiquidityServiceClientContext {
+  rpcClient: PromiseClient<typeof LiquidityService>
+}
+
+export interface LiquidityServiceClient {
+  checkApproval: (params: CheckApprovalLPRequest) => Promise<CheckApprovalLPResponse>
+  claimLpFees: (params: ClaimLPFeesRequest) => Promise<ClaimLPFeesResponse>
+  claimRewards: (params: ClaimLPRewardsRequest) => Promise<ClaimLPRewardsResponse>
+  createLpPosition: (params: CreateLPPositionRequest) => Promise<CreateLPPositionResponse>
+  decreaseLpPosition: (params: DecreaseLPPositionRequest) => Promise<DecreaseLPPositionResponse>
+  getLPPriceDiscrepancy: (params: GetLPPriceDiscrepancyRequest) => Promise<GetLPPriceDiscrepancyResponse>
+  increaseLpPosition: (params: IncreaseLPPositionRequest) => Promise<IncreaseLPPositionResponse>
+  migrateV2ToV3LpPosition: (params: MigrateV2ToV3LPPositionRequest) => Promise<MigrateV2ToV3LPPositionResponse>
+  migrateV3ToV4LpPosition: (params: MigrateV3ToV4LPPositionRequest) => Promise<MigrateV3ToV4LPPositionResponse>
+  poolInfo: (params: PoolInfoRequest) => Promise<PoolInfoResponse>
+}
+
+export function createLiquidityServiceClient({ rpcClient }: LiquidityServiceClientContext): LiquidityServiceClient {
+  return {
+    checkApproval: (params) => rpcClient.checkLPApproval(params),
+    claimLpFees: (params) => rpcClient.claimLPFees(params),
+    claimRewards: (params) => rpcClient.claimLPRewards(params),
+    createLpPosition: (params) => rpcClient.createLPPosition(params),
+    decreaseLpPosition: (params) => rpcClient.decreaseLPPosition(params),
+    getLPPriceDiscrepancy: (params) => rpcClient.getLPPriceDiscrepancy(params),
+    increaseLpPosition: (params) => rpcClient.increaseLPPosition(params),
+    migrateV2ToV3LpPosition: (params) => rpcClient.migrateV2ToV3LPPosition(params),
+    migrateV3ToV4LpPosition: (params) => rpcClient.migrateV3ToV4LPPosition(params),
+    poolInfo: (params) => rpcClient.poolInfo(params),
+  }
+}

package/src/clients/lux/createLuxApiClient.ts

@@ -0,0 +1,100 @@
+import type { TransactionRequest } from '@ethersproject/providers'
+import type { FetchClient } from '@luxexchange/api/src/clients/base/types'
+import {
+  type GasFeeResponse,
+  type GasFeeResultWithoutState,
+  type GasStrategy,
+} from '@luxexchange/api/src/clients/trading/types'
+import { isWebApp } from '@luxfi/utilities/src/platform'
+
+// TODO(app-infra), de-duplicate with luxUrls when other consumers are migrated to use this client
+const LUX_API_PATHS = {
+  gasFee: '/v1/gas-fee',
+  trmScreen: '/v1/screen',
+}
+
+type FetchGasFn = ({
+  tx,
+  fallbackGasLimit,
+}: {
+  tx: TransactionRequest
+  gasStrategy: GasStrategy
+  fallbackGasLimit?: number
+  smartContractDelegationAddress?: Address
+}) => Promise<GasFeeResultWithoutState>
+
+export type ScreenResponse = {
+  block: boolean
+}
+
+export type ScreenRequest = {
+  address: string
+}
+
+export interface LuxApiClientContext {
+  fetchClient: FetchClient
+  processGasFeeResponse: (gasFeeResponse: GasFeeResponse, gasStrategy: GasStrategy) => GasFeeResultWithoutState
+  estimateGasWithClientSideProvider: (params: {
+    tx: TransactionRequest
+    fallbackGasLimit?: number
+  }) => Promise<GasFeeResultWithoutState>
+}
+
+export interface LuxApiClient {
+  fetchGasFee: FetchGasFn
+  fetchTrmScreen: (params: ScreenRequest) => Promise<ScreenResponse>
+}
+
+export function createLuxApiClient(ctx: LuxApiClientContext): LuxApiClient {
+  const { fetchClient: client, processGasFeeResponse, estimateGasWithClientSideProvider } = ctx
+
+  const injectGasStrategies = (
+    tx: TransactionRequest,
+    gasStrategy: GasStrategy,
+  ): TransactionRequest & { gasStrategies: GasStrategy[] } => {
+    return { ...tx, gasStrategies: [gasStrategy] }
+  }
+
+  const injectSmartContractDelegationAddress = (
+    tx: TransactionRequest,
+    smartContractDelegationAddress?: Address,
+  ): TransactionRequest => ({
+    ...tx,
+    ...(smartContractDelegationAddress ? { smartContractDelegationAddress } : {}),
+  })
+
+  const fetchGasFee: FetchGasFn = async ({ tx, fallbackGasLimit, smartContractDelegationAddress, gasStrategy }) => {
+    const txWithScDelegationAddress = injectSmartContractDelegationAddress(tx, smartContractDelegationAddress)
+    const body = JSON.stringify(injectGasStrategies(txWithScDelegationAddress, gasStrategy))
+
+    try {
+      const gasFeeResponse = await client.post<GasFeeResponse>(LUX_API_PATHS.gasFee, {
+        body,
+        headers: smartContractDelegationAddress
+          ? {
+              'x-viem-provider-enabled': 'true',
+            }
+          : {},
+      })
+      return processGasFeeResponse(gasFeeResponse, gasStrategy)
+    } catch (error) {
+      if (isWebApp) {
+        // Gas Fee API currently errors on gas estimations on disconnected state & insufficient funds
+        // Fallback to clientside estimate using provider.estimateGas
+        return estimateGasWithClientSideProvider({ tx, fallbackGasLimit })
+      }
+      throw error
+    }
+  }
+
+  const fetchTrmScreen = async (params: ScreenRequest): Promise<ScreenResponse> => {
+    return await client.post<ScreenResponse>(LUX_API_PATHS.trmScreen, {
+      body: JSON.stringify(params),
+    })
+  }
+
+  return {
+    fetchGasFee,
+    fetchTrmScreen,
+  }
+}

package/src/clients/notifications/createNotificationsApiClient.ts

@@ -0,0 +1,72 @@
+import { JsonValue } from '@bufbuild/protobuf'
+import { GetNotificationsResponse as GetNotificationsResponseMessage } from '@uniswap/client-notification-service/dist/uniswap/notificationservice/v1/api_pb'
+import type {
+  AckNotificationRequest,
+  AckNotificationResponse,
+  GetNotificationsRequest,
+  GetNotificationsResponse,
+  NotificationsApiClient,
+  NotificationsClientContext,
+} from '@luxfi/api/src/clients/notifications/types'
+
+/**
+ * Factory function to create a NotificationsApiClient
+ *
+ * Example usage:
+ * ```typescript
+ * const notificationsClient = createNotificationsApiClient({
+ *   fetchClient: myFetchClient,
+ *   getApiPathPrefix: () => '/notifications/v1'
+ * })
+ *
+ * const notifications = await notificationsClient.getNotifications()
+ * ```
+ *
+ * @param ctx - Context containing injected dependencies
+ * @returns NotificationsApiClient instance
+ */
+export function createNotificationsApiClient(ctx: NotificationsClientContext): NotificationsApiClient {
+  const { fetchClient, getApiPathPrefix = (): string => '' } = ctx
+
+  const getNotifications = async (params?: GetNotificationsRequest): Promise<GetNotificationsResponse> => {
+    const pathPrefix = getApiPathPrefix()
+    const path = `${pathPrefix}/lux.notificationservice.v1.NotificationService/GetNotifications`
+
+    try {
+      const response = await fetchClient.post<JsonValue>(path, {
+        body: JSON.stringify(params ?? {}),
+      })
+
+      return GetNotificationsResponseMessage.fromJson(response, { ignoreUnknownFields: true })
+    } catch (error) {
+      throw new Error(`Failed to fetch notifications: ${error instanceof Error ? error.message : String(error)}`, {
+        cause: error,
+      })
+    }
+  }
+
+  const ackNotification = async (request: AckNotificationRequest): Promise<AckNotificationResponse> => {
+    const pathPrefix = getApiPathPrefix()
+    const path = `${pathPrefix}/lux.notificationservice.v1.NotificationService/AckNotifications`
+
+    try {
+      const response = await fetchClient.post<AckNotificationResponse>(path, {
+        body: JSON.stringify(request),
+      })
+
+      return response
+    } catch (error) {
+      throw new Error(
+        `Failed to acknowledge notifications: ${error instanceof Error ? error.message : String(error)}`,
+        {
+          cause: error,
+        },
+      )
+    }
+  }
+
+  return {
+    getNotifications,
+    ackNotification,
+  }
+}

package/src/clients/notifications/types.ts

@@ -0,0 +1,102 @@
+import type { PlainMessage } from '@bufbuild/protobuf'
+import {
+  BackgroundType,
+  Button,
+  Content,
+  ContentStyle,
+  Notification,
+  OnClickAction,
+  AckNotificationRequest as ProtoAckNotificationRequest,
+  AckNotificationResponse as ProtoAckNotificationResponse,
+  GetNotificationsRequest as ProtoGetNotificationsRequest,
+  GetNotificationsResponse as ProtoGetNotificationsResponse,
+} from '@uniswap/client-notification-service/dist/uniswap/notificationservice/v1/api_pb'
+import { FetchClient } from '@luxfi/api/src/clients/base/types'
+
+export interface NotificationsClientContext {
+  fetchClient: FetchClient
+  getApiPathPrefix?: () => string
+}
+
+/**
+ * Content style types for notifications
+ */
+export { ContentStyle, BackgroundType, OnClickAction }
+
+/**
+ * Content style type for convenience (union of ContentStyle enum values)
+ */
+export type NotificationContentStyle = ContentStyle
+
+/**
+ * Button configuration for notification content
+ * Re-exported from @l.x/client-notification-service
+ * Note: This is the Message class instance, not a plain object.
+ * Used within Content which comes from deserialized notifications.
+ */
+export type NotificationButton = Button
+
+/**
+ * Notification content
+ * Re-exported from @l.x/client-notification-service
+ *
+ * Notification API Type Mapping:
+ * - content.title → Modal title
+ * - content.subtitle → Modal subtitle
+ * - content.background.link → Background image URL (when backgroundType is IMAGE)
+ * - content.body.items[] → Feature list with icons and text
+ * - content.buttons[] → Action buttons
+ *
+ * Note: This is the Message class instance, not a plain object.
+ * Enum values are numbers at runtime, but toJSON() serializes them as strings.
+ */
+export type NotificationContent = Content
+
+/**
+ * In-app notification returned by the notifications API
+ * Re-exported from @l.x/client-notification-service
+ * Note: This is a plain object (not a Message class instance) to prevent
+ * React Query's structural cloning from triggering toJSON() which would
+ * convert numeric enum values to strings.
+ */
+export type InAppNotification = PlainMessage<Notification>
+
+/**
+ * Request parameters for fetching notifications
+ * Re-exported from @l.x/client-notification-service
+ */
+export type GetNotificationsRequest = PlainMessage<ProtoGetNotificationsRequest>
+
+/**
+ * Response from the GetNotifications API endpoint
+ * Re-exported from @l.x/client-notification-service
+ * Note: This is the Message class instance from protobuf deserialization.
+ */
+export type GetNotificationsResponse = ProtoGetNotificationsResponse
+
+/**
+ * Request parameters for acknowledging notifications
+ * Re-exported from @l.x/client-notification-service
+ */
+export type AckNotificationRequest = PlainMessage<ProtoAckNotificationRequest>
+
+/**
+ * Response from the AckNotifications API endpoint
+ * Re-exported from @l.x/client-notification-service
+ */
+export type AckNotificationResponse = PlainMessage<ProtoAckNotificationResponse>
+
+export interface NotificationsApiClient {
+  /**
+   * Fetch notifications for the current user
+   * Uses session-based authentication (x-session-id header) via FetchClient
+   * Returns the raw GetNotificationsResponse message from protobuf deserialization
+   */
+  getNotifications: (params?: GetNotificationsRequest) => Promise<GetNotificationsResponse>
+
+  /**
+   * Acknowledge that a notification has been tracked/processed
+   * Uses session-based authentication (x-session-id header) via FetchClient
+   */
+  ackNotification: (request: AckNotificationRequest) => Promise<AckNotificationResponse>
+}

package/src/clients/trading/__generated__/core/ApiError.ts

@@ -0,0 +1,25 @@
+/* generated using openapi-typescript-codegen -- do no edit */
+/* istanbul ignore file */
+/* tslint:disable */
+/* eslint-disable */
+import type { ApiRequestOptions } from './ApiRequestOptions';
+import type { ApiResult } from './ApiResult';
+
+export class ApiError extends Error {
+    public readonly url: string;
+    public readonly status: number;
+    public readonly statusText: string;
+    public readonly body: any;
+    public readonly request: ApiRequestOptions;
+
+    constructor(request: ApiRequestOptions, response: ApiResult, message: string) {
+        super(message);
+
+        this.name = 'ApiError';
+        this.url = response.url;
+        this.status = response.status;
+        this.statusText = response.statusText;
+        this.body = response.body;
+        this.request = request;
+    }
+}

package/src/clients/trading/__generated__/core/ApiRequestOptions.ts

@@ -0,0 +1,17 @@
+/* generated using openapi-typescript-codegen -- do no edit */
+/* istanbul ignore file */
+/* tslint:disable */
+/* eslint-disable */
+export type ApiRequestOptions = {
+    readonly method: 'GET' | 'PUT' | 'POST' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'PATCH';
+    readonly url: string;
+    readonly path?: Record<string, any>;
+    readonly cookies?: Record<string, any>;
+    readonly headers?: Record<string, any>;
+    readonly query?: Record<string, any>;
+    readonly formData?: Record<string, any>;
+    readonly body?: any;
+    readonly mediaType?: string;
+    readonly responseHeader?: string;
+    readonly errors?: Record<number, string>;
+};

package/src/clients/trading/__generated__/core/ApiResult.ts

@@ -0,0 +1,11 @@
+/* generated using openapi-typescript-codegen -- do no edit */
+/* istanbul ignore file */
+/* tslint:disable */
+/* eslint-disable */
+export type ApiResult = {
+    readonly url: string;
+    readonly ok: boolean;
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: any;
+};