@lifi/perps-sdk 0.1.1-alpha.4 → 0.1.1-alpha.40

package/src/errors/HTTPError.ts

@@ -1,72 +0,0 @@
-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/PerpsSDKError.ts

@@ -1,79 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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

@@ -1,38 +0,0 @@
-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/utils/rootCause.ts

@@ -1,112 +0,0 @@
-/**
- * Get the root cause of an error by following the cause chain.
- *
- * @param error - The error to get the root cause of
- * @returns The root cause error, or the original error if no cause chain
- *
- * @example
- * ```ts
- * const wrapper = new PerpsSDKError(new HTTPError(response, url))
- * const root = getRootCause(wrapper) // Returns the HTTPError
- * ```
- */
-export function getRootCause(error: Error): Error {
-  let current: Error = error
-  let iterations = 0
-  const maxIterations = 100 // Prevent infinite loops
-
-  while (current.cause instanceof Error && iterations < maxIterations) {
-    current = current.cause
-    iterations++
-  }
-
-  return current
-}
-
-/**
- * Get the message from the root cause of an error.
- *
- * @param error - The error to get the root cause message from
- * @returns The root cause message
- *
- * @example
- * ```ts
- * const wrapper = new PerpsSDKError(new HTTPError(response, url))
- * const message = getRootCauseMessage(wrapper) // Returns the HTTPError's message
- * ```
- */
-export function getRootCauseMessage(error: Error): string {
-  return getRootCause(error).message
-}
-
-/**
- * Get the full error chain as an array.
- *
- * @param error - The error to get the chain from
- * @returns Array of errors from outermost to root cause
- *
- * @example
- * ```ts
- * const chain = getErrorChain(sdkError)
- * // [PerpsSDKError, HTTPError, ...]
- * ```
- */
-export function getErrorChain(error: Error): Error[] {
-  const chain: Error[] = [error]
-  let current = error
-  let iterations = 0
-  const maxIterations = 100
-
-  while (current.cause instanceof Error && iterations < maxIterations) {
-    chain.push(current.cause)
-    current = current.cause
-    iterations++
-  }
-
-  return chain
-}
-
-/**
- * Check if an error chain contains an error of a specific type.
- *
- * @param error - The error to check
- * @param ErrorClass - The error class to look for
- * @returns True if the chain contains an error of the specified type
- *
- * @example
- * ```ts
- * if (hasErrorType(error, HTTPError)) {
- *   // Handle HTTP error specifically
- * }
- * ```
- */
-export function hasErrorType<T extends Error>(
-  error: Error,
-  ErrorClass: new (...args: any[]) => T
-): boolean {
-  const chain = getErrorChain(error)
-  return chain.some((e) => e instanceof ErrorClass)
-}
-
-/**
- * Find the first error of a specific type in the error chain.
- *
- * @param error - The error to search
- * @param ErrorClass - The error class to find
- * @returns The first matching error, or undefined if not found
- *
- * @example
- * ```ts
- * const httpError = findErrorType(error, HTTPError)
- * if (httpError) {
- *   console.log(httpError.status)
- * }
- * ```
- */
-export function findErrorType<T extends Error>(
-  error: Error,
-  ErrorClass: new (...args: any[]) => T
-): T | undefined {
-  const chain = getErrorChain(error)
-  return chain.find((e): e is T => e instanceof ErrorClass)
-}

package/src/services/cancelOrder.ts

@@ -1,75 +0,0 @@
-import type { Address, CancelOrderPayloadResponse } from '@lifi/perps-types'
-import type {
-  PerpsSDKClient,
-  SDKRequestOptions,
-} from '../client/createPerpsClient.js'
-import { request } from '../utils/request.js'
-
-export interface CancelOrderParams {
-  /** DEX to cancel orders on (e.g., 'hyperliquid') */
-  dex: string
-  /** Wallet address */
-  address: Address
-  /** Address of the signer (for agent mode, this is the agent address) */
-  signerAddress?: Address
-  /** Order IDs to cancel */
-  ids: string[]
-}
-
-/**
- * Create cancel order payloads for signing.
- * Returns typed data that must be signed by the user or agent.
- *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns Cancel actions with typed data for signing
- * @throws {HTTPError} On API error responses
- * @throws {PerpsError} On network or parsing errors
- *
- * @example
- * ```ts
- * const client = createPerpsClient({ integrator: 'my-app' })
- * const { actions } = await cancelOrder(client, {
- *   dex: 'hyperliquid',
- *   address: '0x1234...',
- *   ids: ['order1', 'order2']
- * })
- *
- * // Sign with agent key or user wallet
- * const signedActions = await Promise.all(
- *   actions.map(async (a) => ({
- *     action: a.action,
- *     typedData: a.typedData,
- *     signature: await signTypedData(agentPrivateKey, a.typedData)
- *   }))
- * )
- *
- * // Submit the signed cancellation
- * await submitOrder(client, {
- *   dex: 'hyperliquid',
- *   address: '0x1234...',
- *   actions: signedActions
- * })
- * ```
- */
-export async function cancelOrder(
-  client: PerpsSDKClient,
-  params: CancelOrderParams,
-  options?: SDKRequestOptions
-): Promise<CancelOrderPayloadResponse> {
-  return request<CancelOrderPayloadResponse>(
-    client.config,
-    `${client.config.apiUrl}/cancelOrder`,
-    {
-      method: 'POST',
-      body: JSON.stringify({
-        dex: params.dex,
-        address: params.address,
-        signerAddress: params.signerAddress,
-        ids: params.ids,
-      }),
-    },
-    options
-  )
-}

package/src/services/createAuthorization.ts

@@ -1,79 +0,0 @@
-import type {
-  Address,
-  AuthorizationInput,
-  CreateAuthorizationResponse,
-} from '@lifi/perps-types'
-import type {
-  PerpsSDKClient,
-  SDKRequestOptions,
-} from '../client/createPerpsClient.js'
-import { request } from '../utils/request.js'
-
-export interface CreateAuthorizationParams {
-  /** DEX to authorize (e.g., 'hyperliquid') */
-  dex: string
-  /** Wallet address */
-  address: Address
-  /** Address of the signer (for agent mode, this is the agent address) */
-  signerAddress?: Address
-  /** List of authorizations to create */
-  authorizations: AuthorizationInput[]
-}
-
-/**
- * Create authorization payloads for signing.
- * Returns typed data that must be signed by the user or agent.
- *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns Authorization actions with typed data for signing
- * @throws {HTTPError} On API error responses
- * @throws {PerpsError} On network or parsing errors
- *
- * @remarks
- * The example below uses Hyperliquid authorization keys. Use `getDexes()` to discover
- * available authorizations for each DEX.
- *
- * @example
- * ```ts
- * const client = createPerpsClient({ integrator: 'my-app' })
- * const { actions } = await createAuthorization(client, {
- *   dex: 'hyperliquid',
- *   address: '0x1234...',
- *   authorizations: [
- *     { key: 'ApproveAgent', params: { agentAddress: '0xabcd...' } },
- *     { key: 'ApproveBuilderFee' }
- *   ]
- * })
- *
- * // Sign each action's typedData with the user's wallet
- * const signedActions = await Promise.all(
- *   actions.map(async (a) => ({
- *     action: a.action,
- *     typedData: a.typedData,
- *     signature: await walletClient.signTypedData(a.typedData)
- *   }))
- * )
- * ```
- */
-export async function createAuthorization(
-  client: PerpsSDKClient,
-  params: CreateAuthorizationParams,
-  options?: SDKRequestOptions
-): Promise<CreateAuthorizationResponse> {
-  return request<CreateAuthorizationResponse>(
-    client.config,
-    `${client.config.apiUrl}/createAuthorization`,
-    {
-      method: 'POST',
-      body: JSON.stringify({
-        dex: params.dex,
-        address: params.address,
-        signerAddress: params.signerAddress,
-        authorizations: params.authorizations,
-      }),
-    },
-    options
-  )
-}

package/src/services/createOrder.ts

@@ -1,116 +0,0 @@
-import type {
-  Address,
-  CreateOrderResponse,
-  OrderSide,
-  OrderType,
-  TimeInForce,
-  TriggerOrderInput,
-} from '@lifi/perps-types'
-import type {
-  PerpsSDKClient,
-  SDKRequestOptions,
-} from '../client/createPerpsClient.js'
-import { request } from '../utils/request.js'
-
-export interface CreateOrderParams {
-  /** DEX to place order on (e.g., 'hyperliquid') */
-  dex: string
-  /** Wallet address */
-  address: Address
-  /** Address of the signer (for agent mode, this is the agent address) */
-  signerAddress?: Address
-  /** Client-provided order ID for tracking */
-  clientOrderId?: string
-  /** Market symbol (e.g., 'BTC') */
-  symbol: string
-  /** Order side */
-  side: OrderSide
-  /** Order type */
-  type: OrderType
-  /** Order size (in base asset) */
-  size: string
-  /** Order price (required for limit orders) */
-  price: string
-  /** Leverage for the position */
-  leverage?: number
-  /** Whether this order only reduces position */
-  reduceOnly?: boolean
-  /** Time in force */
-  timeInForce?: TimeInForce
-  /** Expiration time (ISO 8601) */
-  expiresAt?: string
-  /** Take profit trigger order */
-  takeProfit?: TriggerOrderInput
-  /** Stop loss trigger order */
-  stopLoss?: TriggerOrderInput
-}
-
-/**
- * Create order payloads for signing.
- * Returns typed data that must be signed by the user or agent.
- *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns Order actions with typed data for signing
- * @throws {HTTPError} On API error responses
- * @throws {PerpsError} On network or parsing errors
- *
- * @remarks
- * The example below uses Hyperliquid. Replace the `dex` value for other DEXes.
- *
- * @example
- * ```ts
- * const client = createPerpsClient({ integrator: 'my-app' })
- * const { actions } = await createOrder(client, {
- *   dex: 'hyperliquid',
- *   address: '0x1234...',
- *   symbol: 'BTC',
- *   side: OrderSide.BUY,
- *   type: OrderType.LIMIT,
- *   size: '0.1',
- *   price: '94000.00',
- *   leverage: 10
- * })
- *
- * // Sign each action with the user's wallet or agent key
- * const signedActions = await Promise.all(
- *   actions.map(async (a) => ({
- *     action: a.action,
- *     typedData: a.typedData,
- *     signature: await walletClient.signTypedData(a.typedData)
- *   }))
- * )
- * ```
- */
-export async function createOrder(
-  client: PerpsSDKClient,
-  params: CreateOrderParams,
-  options?: SDKRequestOptions
-): Promise<CreateOrderResponse> {
-  return request<CreateOrderResponse>(
-    client.config,
-    `${client.config.apiUrl}/createOrder`,
-    {
-      method: 'POST',
-      body: JSON.stringify({
-        dex: params.dex,
-        address: params.address,
-        signerAddress: params.signerAddress,
-        clientOrderId: params.clientOrderId,
-        symbol: params.symbol,
-        side: params.side,
-        type: params.type,
-        size: params.size,
-        price: params.price,
-        leverage: params.leverage,
-        reduceOnly: params.reduceOnly,
-        timeInForce: params.timeInForce,
-        expiresAt: params.expiresAt,
-        takeProfit: params.takeProfit,
-        stopLoss: params.stopLoss,
-      }),
-    },
-    options
-  )
-}

package/src/services/createWithdrawal.ts

@@ -1,76 +0,0 @@
-import type {
-  Address,
-  CreateWithdrawalResponse,
-  WithdrawalInput,
-} from '@lifi/perps-types'
-import type {
-  PerpsSDKClient,
-  SDKRequestOptions,
-} from '../client/createPerpsClient.js'
-import { request } from '../utils/request.js'
-
-export interface CreateWithdrawalParams {
-  /** DEX to withdraw from (e.g., 'hyperliquid') */
-  dex: string
-  /** Wallet address (account owner) */
-  address: Address
-  /** Withdrawal details (destination address and amount) */
-  withdrawal: WithdrawalInput
-}
-
-/**
- * Create a withdrawal payload for signing.
- * Returns typed data that must be signed by the user's wallet.
- *
- * Withdrawals are user-signed only — agents cannot initiate withdrawals.
- * This is a protocol-level security feature.
- *
- * @param client - The SDK client instance
- * @param params - Request parameters
- * @param options - Request options (e.g., AbortSignal)
- * @returns Withdrawal action with typed data for signing
- * @throws {HTTPError} On API error responses
- * @throws {PerpsError} On network or parsing errors
- *
- * @remarks
- * The example below uses Hyperliquid. Withdrawal mechanics vary by DEX.
- *
- * @example
- * ```ts
- * const client = createPerpsClient({ integrator: 'my-app' })
- * const { action } = await createWithdrawal(client, {
- *   dex: 'hyperliquid',
- *   address: '0x1234...',
- *   withdrawal: {
- *     destination: '0x1234...',
- *     amount: '100.0',
- *   },
- * })
- *
- * // Sign the action's typedData with the user's wallet
- * const signedAction = {
- *   action: action.action,
- *   typedData: action.typedData,
- *   signature: await walletClient.signTypedData(action.typedData),
- * }
- * ```
- */
-export async function createWithdrawal(
-  client: PerpsSDKClient,
-  params: CreateWithdrawalParams,
-  options?: SDKRequestOptions
-): Promise<CreateWithdrawalResponse> {
-  return request<CreateWithdrawalResponse>(
-    client.config,
-    `${client.config.apiUrl}/createWithdrawal`,
-    {
-      method: 'POST',
-      body: JSON.stringify({
-        dex: params.dex,
-        address: params.address,
-        withdrawal: params.withdrawal,
-      }),
-    },
-    options
-  )
-}