@lifi/perps-sdk 0.1.1-alpha.0

package/src/client/createPerpsClient.ts

@@ -0,0 +1,164 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { AgentManager } from '../agent/AgentManager.js'
+import type { StorageAdapter } from '../agent/types.js'
+import { PerpsErrorName } from '../errors/constants.js'
+import { PerpsError } from '../errors/PerpsError.js'
+import { sleep } from '../utils/sleep.js'
+
+const DEFAULT_API_URL = 'https://li.quest/v1/perps'
+const HEALTH_POLL_INTERVAL_MS = 500
+const HEALTH_MAX_ATTEMPTS = 50
+
+/**
+ * Configuration options for creating a Perps SDK client.
+ */
+export interface PerpsConfig {
+  /** Integrator identifier (required) */
+  integrator: string
+  /** Optional API key for authenticated requests */
+  apiKey?: string
+  /** Base API URL. Defaults to https://li.quest/v1/perps */
+  apiUrl?: string
+  /** Disable version update check in development mode */
+  disableVersionCheck?: boolean
+  /** Custom storage adapter for agent keys. Defaults to localStorage. */
+  storage?: StorageAdapter
+  /** Optional request interceptor for custom handling */
+  requestInterceptor?: RequestInterceptor
+  /** Whether to perform a health check on startup before allowing requests. Default: true */
+  healthCheck?: boolean
+}
+
+/**
+ * Resolved configuration with required fields.
+ */
+export interface PerpsBaseConfig {
+  /** Integrator identifier (required) */
+  integrator: string
+  /** Optional API key for authenticated requests */
+  apiKey?: string
+  /** Resolved API URL (always set) */
+  apiUrl: string
+  /** Disable version update check in development mode */
+  disableVersionCheck?: boolean
+  /** Optional request interceptor for custom handling */
+  requestInterceptor?: RequestInterceptor
+  /** Promise that resolves when the API is ready. Requests wait for this. */
+  readyPromise?: Promise<void>
+}
+
+/**
+ * Request interceptor function type.
+ * Called before each request is made, allowing modification of fetch options.
+ */
+export type RequestInterceptor = (
+  url: string,
+  options: RequestInit
+) => RequestInit | Promise<RequestInit>
+
+/**
+ * Options passed to service functions for request control.
+ */
+export interface SDKRequestOptions {
+  /** AbortSignal to cancel the request */
+  signal?: AbortSignal
+}
+
+/**
+ * The Perps SDK client instance.
+ * Holds configuration and agent manager for making API requests.
+ */
+export interface PerpsSDKClient {
+  /** SDK configuration */
+  readonly config: PerpsBaseConfig
+  /** Agent manager for USER_AGENT signing mode */
+  readonly agentManager: AgentManager
+  /** Promise that resolves when the API health check passes. */
+  readonly ready: Promise<void>
+}
+
+/**
+ * Create a new Perps SDK client.
+ *
+ * @param options - Configuration options
+ * @returns A new SDK client instance
+ * @throws {PerpsError} If integrator is not provided
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({
+ *   integrator: 'my-app',
+ *   apiKey: 'optional-api-key',
+ * })
+ *
+ * // Use with service functions
+ * const { dexes } = await getDexes(client)
+ * ```
+ */
+export function createPerpsClient(options: PerpsConfig): PerpsSDKClient {
+  if (!options.integrator) {
+    const error = new PerpsError(
+      PerpsErrorCode.ValidationError,
+      'Integrator is required. Please see documentation at https://docs.li.fi'
+    )
+    error.name = PerpsErrorName.ValidationError
+    throw error
+  }
+
+  const apiUrl = options.apiUrl ?? DEFAULT_API_URL
+
+  const readyPromise =
+    options.healthCheck !== false ? pollHealth(apiUrl) : Promise.resolve()
+
+  const config: PerpsBaseConfig = {
+    integrator: options.integrator,
+    apiKey: options.apiKey,
+    apiUrl,
+    disableVersionCheck: options.disableVersionCheck,
+    requestInterceptor: options.requestInterceptor,
+    readyPromise,
+  }
+
+  const agentManager = new AgentManager(options.storage)
+
+  return {
+    get config() {
+      return config
+    },
+    get agentManager() {
+      return agentManager
+    },
+    get ready() {
+      return readyPromise
+    },
+  }
+}
+
+/**
+ * Poll the API health endpoint until it returns a successful response.
+ *
+ * Derives the health URL from the apiUrl origin (e.g. https://li.quest/health/live).
+ * Retries up to {@link HEALTH_MAX_ATTEMPTS} times with {@link HEALTH_POLL_INTERVAL_MS} delays.
+ *
+ * @throws {PerpsError} If the health endpoint does not respond after all attempts
+ */
+async function pollHealth(apiUrl: string): Promise<void> {
+  const healthUrl = `${new URL(apiUrl).origin}/health/live`
+
+  for (let i = 0; i < HEALTH_MAX_ATTEMPTS; i++) {
+    try {
+      const response = await fetch(healthUrl)
+      if (response.ok) {
+        return
+      }
+    } catch {
+      // Server not reachable yet, retry
+    }
+    await sleep(HEALTH_POLL_INTERVAL_MS)
+  }
+
+  throw new PerpsError(
+    PerpsErrorCode.ServerError,
+    'API health check failed: server did not become ready'
+  )
+}

package/src/client/types.ts

@@ -0,0 +1,156 @@
+import type {
+  Address,
+  AuthorizationInput,
+  AuthorizationsResponse,
+  OrderSide,
+  OrderType,
+  SignedAuthorization,
+  TimeInForce,
+  TriggerOrderInput,
+} from '@lifi/perps-types'
+import type { StorageAdapter } from '../agent/types.js'
+
+// Re-export the SDK client types from createPerpsClient
+export type {
+  PerpsBaseConfig,
+  PerpsConfig,
+  PerpsSDKClient,
+  RequestInterceptor,
+  SDKRequestOptions,
+} from './createPerpsClient.js'
+
+/**
+ * Signing mode determines who signs trading actions.
+ *
+ * - `USER`: User wallet signs each action (requires wallet popup per action)
+ * - `USER_AGENT`: SDK-generated agent signs actions (no popups after initial setup)
+ */
+export type SigningMode = 'USER' | 'USER_AGENT'
+
+/**
+ * Options for PerpsClient constructor.
+ */
+export interface PerpsClientOptions {
+  /** Integrator identifier (required) */
+  integrator: string
+  /** Optional API key for authenticated requests */
+  apiKey?: string
+  /** Base API URL. Defaults to https://li.quest/v1/perps */
+  apiUrl?: string
+  /** Custom storage adapter for agent keys. Defaults to localStorage. */
+  storage?: StorageAdapter
+  /** Whether to perform a health check on startup before allowing requests. Default: true */
+  healthCheck?: boolean
+}
+
+/**
+ * Parameters for building authorization payloads.
+ */
+export interface BuildAuthorizationParams {
+  /** DEX to authorize */
+  dex: string
+  /** User wallet address */
+  address: Address
+  /** Address of the signer (auto-set in USER_AGENT mode) */
+  signerAddress?: Address
+  /** Authorizations to create */
+  authorizations: AuthorizationInput[]
+}
+
+/**
+ * Parameters for placing an order.
+ */
+export interface PlaceOrderParams {
+  /** DEX to place order on */
+  dex: string
+  /** User wallet address */
+  address: Address
+  /** Client-provided order ID */
+  clientOrderId?: string
+  /** Market symbol */
+  symbol: string
+  /** Order side */
+  side: OrderSide
+  /** Order type */
+  type: OrderType
+  /** Order size */
+  size: string
+  /** Order price */
+  price: string
+  /** Leverage */
+  leverage?: number
+  /** Reduce only flag */
+  reduceOnly?: boolean
+  /** Time in force */
+  timeInForce?: TimeInForce
+  /** Expiration time */
+  expiresAt?: string
+  /** Take profit trigger */
+  takeProfit?: TriggerOrderInput
+  /** Stop loss trigger */
+  stopLoss?: TriggerOrderInput
+}
+
+/**
+ * Parameters for canceling orders.
+ */
+export interface CancelOrdersParams {
+  /** DEX to cancel orders on */
+  dex: string
+  /** User wallet address */
+  address: Address
+  /** Order IDs to cancel */
+  ids: string[]
+}
+
+/**
+ * Parameters for getRequiredAuthorizations().
+ */
+export interface GetRequiredAuthorizationsParams {
+  /** DEX to check authorizations for */
+  dex: string
+  /** User wallet address */
+  address: Address
+  /** Whether to require abstraction (for HIP-3 assets). Default: false */
+  requireAbstraction?: boolean
+}
+
+/**
+ * Result from getRequiredAuthorizations().
+ */
+export interface RequiredAuthorizationsResult {
+  /** Authorizations requiring user wallet signature (0, 1, or 2 items) */
+  userAuthorizations: AuthorizationInput[]
+  /** Authorizations the SDK auto-signs with the agent after user auths are submitted */
+  agentAuthorizations: AuthorizationInput[]
+  /** Whether the local agent is registered and valid on the backend */
+  agentValid: boolean
+  /** The raw abstractionStatus from config (null=never set, 'disabled', 'unifiedAccount', 'portfolioMargin') */
+  abstractionStatus: string | null
+  /** Whether all authorizations are already satisfied (ready to trade) */
+  isReady: boolean
+}
+
+/**
+ * Parameters for executeAuthorizations().
+ */
+export interface ExecuteAuthorizationsParams {
+  /** DEX to authorize */
+  dex: string
+  /** User wallet address */
+  address: Address
+  /** The result from getRequiredAuthorizations() */
+  required: RequiredAuthorizationsResult
+  /** User-signed actions corresponding to required.userAuthorizations */
+  userSignedActions: SignedAuthorization[]
+}
+
+/**
+ * Result from executeAuthorizations().
+ */
+export interface ExecuteAuthorizationsResult {
+  /** Results from user-signed authorization submission */
+  userResults: AuthorizationsResponse
+  /** Results from agent-signed authorization submission (if any) */
+  agentResults?: AuthorizationsResponse
+}

package/src/errors/AgentError.ts

@@ -0,0 +1,43 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { version } from '../version.js'
+import { PerpsErrorName } from './constants.js'
+import { PerpsError } from './PerpsError.js'
+
+/**
+ * Error thrown when agent-related operations fail (agent not found, authorization issues, etc.)
+ */
+export class AgentError extends PerpsError {
+  override name = PerpsErrorName.AgentError
+
+  constructor(message: string, code = PerpsErrorCode.AgentUnauthorized) {
+    super(code, message)
+    this.name = PerpsErrorName.AgentError
+
+    // Override message format
+    this.message = `[${PerpsErrorName.AgentError}] ${message}\nLI.FI Perps SDK version: ${version}`
+  }
+
+  /**
+   * Create an AgentError for a missing agent.
+   *
+   * @param address - The user address
+   * @param dex - The DEX identifier
+   */
+  static notFound(address: string, dex: string): AgentError {
+    return new AgentError(
+      `Agent not found for ${address} on ${dex}. Call setSigningMode() first.`
+    )
+  }
+
+  /**
+   * Create an AgentError for an unauthorized agent.
+   *
+   * @param address - The agent address
+   * @param dex - The DEX identifier
+   */
+  static unauthorized(address: string, dex: string): AgentError {
+    return new AgentError(
+      `Agent ${address} is not authorized on ${dex}. Submit authorization first.`
+    )
+  }
+}

package/src/errors/HTTPError.ts

@@ -0,0 +1,72 @@
+import type { PerpsErrorBody } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsErrorName } from './constants.js'
+import { PerpsError } from './PerpsError.js'
+
+const statusCodeToErrorCode = new Map<number, PerpsErrorCode>([
+  [400, PerpsErrorCode.ValidationError],
+  [401, PerpsErrorCode.SignatureInvalid],
+  [403, PerpsErrorCode.AgentUnauthorized],
+  [404, PerpsErrorCode.MarketNotFound],
+  [422, PerpsErrorCode.ValidationError],
+  [424, PerpsErrorCode.ThirdPartyError],
+  [429, PerpsErrorCode.ServerError],
+  [500, PerpsErrorCode.ServerError],
+  [502, PerpsErrorCode.ServerError],
+  [503, PerpsErrorCode.ServerError],
+  [504, PerpsErrorCode.TimeoutError],
+])
+
+function getErrorCodeFromStatus(status: number): PerpsErrorCode {
+  return statusCodeToErrorCode.get(status) ?? PerpsErrorCode.ServerError
+}
+
+function createInitialMessage(response: Response): string {
+  const statusCode =
+    response.status || response.status === 0 ? response.status : ''
+  const title = response.statusText || ''
+  const status = `${statusCode} ${title}`.trim()
+  const reason = status ? `status code ${status}` : 'an unknown error'
+  return `Request failed with ${reason}`
+}
+
+export class HTTPError extends PerpsError {
+  response: Response
+  status: number
+  url: string
+  responseBody?: PerpsErrorBody
+
+  constructor(response: Response, url: string) {
+    const code = getErrorCodeFromStatus(response.status)
+    const message = createInitialMessage(response)
+
+    super(code, message)
+
+    this.name = PerpsErrorName.HTTPError
+    this.response = response
+    this.status = response.status
+    this.url = url
+  }
+
+  async buildAdditionalDetails(): Promise<this> {
+    try {
+      this.responseBody = (await this.response.json()) as PerpsErrorBody
+
+      if (this.responseBody) {
+        // Update code from response body if available
+        if (this.responseBody.code) {
+          this.code = this.responseBody.code
+        }
+
+        // Append server message
+        if (this.responseBody.message) {
+          this.message = `${this.message}. ${this.responseBody.message}`
+        }
+      }
+    } catch {
+      // Response body parsing failed - use defaults
+    }
+
+    return this
+  }
+}

package/src/errors/PerpsError.ts

@@ -0,0 +1,34 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { version } from '../version.js'
+import { PerpsErrorName } from './constants.js'
+
+export class PerpsError extends Error {
+  code: PerpsErrorCode
+  override name = PerpsErrorName.PerpsError
+
+  constructor(
+    code: PerpsErrorCode = PerpsErrorCode.DefaultError,
+    message = 'Unknown error occurred'
+  ) {
+    const errorMessage = `[${PerpsErrorName.PerpsError}] ${message}\nLI.FI Perps SDK version: ${version}`
+    super(errorMessage)
+    this.code = code
+    this.name = PerpsErrorName.PerpsError
+  }
+
+  static fromError(error: unknown, defaultCode?: PerpsErrorCode): PerpsError {
+    if (error instanceof PerpsError) {
+      return error
+    }
+    if (error instanceof Error) {
+      return new PerpsError(
+        defaultCode ?? PerpsErrorCode.DefaultError,
+        error.message
+      )
+    }
+    return new PerpsError(
+      defaultCode ?? PerpsErrorCode.DefaultError,
+      String(error)
+    )
+  }
+}

package/src/errors/PerpsSDKError.ts

@@ -0,0 +1,79 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { version } from '../version.js'
+import { PerpsError } from './PerpsError.js'
+
+const PERPS_SDK_ERROR_NAME = 'PerpsSDKError'
+
+/**
+ * Top-level SDK error that wraps all other error types.
+ * This is the public-facing error type for the SDK.
+ *
+ * PerpsSDKError always includes:
+ * - A consistent error message format with SDK version
+ * - Access to the root cause error via the `cause` property
+ * - Stack trace preservation
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await getDexes(client)
+ * } catch (error) {
+ *   if (error instanceof PerpsSDKError) {
+ *     console.log(error.message) // [PerpsSDKError] message\nSDK version: X
+ *     console.log(error.cause)   // Original error
+ *     console.log(error.code)    // Numeric error code
+ *   }
+ * }
+ * ```
+ */
+export class PerpsSDKError extends Error {
+  override name = PERPS_SDK_ERROR_NAME
+
+  /** Numeric error code from PerpsErrorCode enum */
+  code: PerpsErrorCode
+
+  /** Original cause of the error */
+  override cause?: Error
+
+  constructor(error: Error, message?: string) {
+    // Determine the code
+    const code =
+      error instanceof PerpsError ? error.code : PerpsErrorCode.DefaultError
+
+    // Build the message
+    const errorMessage = message ?? error.message
+    const formattedMessage = `[${PERPS_SDK_ERROR_NAME}] ${errorMessage}\nLI.FI Perps SDK version: ${version}`
+
+    super(formattedMessage)
+
+    this.name = PERPS_SDK_ERROR_NAME
+    this.code = code
+    this.cause = error
+
+    // Preserve the original stack trace if available
+    if (error.stack) {
+      this.stack = `${this.stack}\nCaused by: ${error.stack}`
+    }
+  }
+
+  /**
+   * Wrap any error in a PerpsSDKError.
+   *
+   * @param error - The error to wrap
+   * @param message - Optional custom message
+   * @returns PerpsSDKError instance
+   */
+  static wrap(error: unknown, message?: string): PerpsSDKError {
+    if (error instanceof PerpsSDKError) {
+      return error
+    }
+
+    if (error instanceof Error) {
+      return new PerpsSDKError(error, message)
+    }
+
+    // Convert non-Error to Error
+    const wrappedError = new Error(String(error))
+    return new PerpsSDKError(wrappedError, message)
+  }
+}

package/src/errors/ServerError.ts

@@ -0,0 +1,41 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { version } from '../version.js'
+import { PerpsErrorName } from './constants.js'
+import { PerpsError } from './PerpsError.js'
+
+/**
+ * Error thrown when server-side operations fail (network errors, timeouts, etc.)
+ */
+export class ServerError extends PerpsError {
+  override name = PerpsErrorName.ServerError
+
+  constructor(message: string, code = PerpsErrorCode.ServerError) {
+    super(code, message)
+    this.name = PerpsErrorName.ServerError
+
+    // Override message format
+    this.message = `[${PerpsErrorName.ServerError}] ${message}\nLI.FI Perps SDK version: ${version}`
+  }
+
+  /**
+   * Create a ServerError for a network failure.
+   *
+   * @param cause - The original error
+   */
+  static networkError(cause?: Error): ServerError {
+    const message = cause?.message ?? 'Network request failed'
+    return new ServerError(message)
+  }
+
+  /**
+   * Create a ServerError for a timeout.
+   *
+   * @param operation - The operation that timed out
+   */
+  static timeout(operation: string): ServerError {
+    return new ServerError(
+      `${operation} timed out`,
+      PerpsErrorCode.TimeoutError
+    )
+  }
+}

package/src/errors/ValidationError.ts

@@ -0,0 +1,38 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { version } from '../version.js'
+import { PerpsErrorName } from './constants.js'
+import { PerpsError } from './PerpsError.js'
+
+/**
+ * Error thrown when validation fails (invalid parameters, missing required fields, etc.)
+ */
+export class ValidationError extends PerpsError {
+  override name = PerpsErrorName.ValidationError
+
+  constructor(message: string) {
+    super(PerpsErrorCode.ValidationError, message)
+    this.name = PerpsErrorName.ValidationError
+
+    // Override message format
+    this.message = `[${PerpsErrorName.ValidationError}] ${message}\nLI.FI Perps SDK version: ${version}`
+  }
+
+  /**
+   * Create a ValidationError from a validation failure.
+   *
+   * @param field - The field that failed validation
+   * @param reason - The reason for validation failure
+   */
+  static field(field: string, reason: string): ValidationError {
+    return new ValidationError(`Invalid ${field}: ${reason}`)
+  }
+
+  /**
+   * Create a ValidationError for a missing required field.
+   *
+   * @param field - The name of the missing field
+   */
+  static required(field: string): ValidationError {
+    return new ValidationError(`${field} is required`)
+  }
+}

package/src/errors/constants.ts

@@ -0,0 +1,15 @@
+export enum PerpsErrorName {
+  PerpsError = 'PerpsError',
+  HTTPError = 'HTTPError',
+  ValidationError = 'ValidationError',
+  ServerError = 'ServerError',
+  ConfigError = 'ConfigError',
+  AgentError = 'AgentError',
+}
+
+export enum PerpsErrorMessage {
+  UnknownError = 'Unknown error occurred.',
+  ConfigNotInitialized = 'SDK not configured. Call createPerpsConfig() first.',
+  AgentNotFound = 'Agent not found. Call setSigningMode() first.',
+  InvalidSigningMode = 'Invalid signing mode for this operation.',
+}