@lifi/perps-sdk 0.2.0-alpha.0 → 1.0.0

package/src/utils/orderClassification.ts

@@ -7,7 +7,12 @@
  */
 
 import type { OpenOrder } from '@lifi/perps-types'
-import { FillClassification, OrderSide, OrderType } from '@lifi/perps-types'
+import {
+  FillClassification,
+  OrderSide,
+  OrderStatus,
+  OrderType,
+} from '@lifi/perps-types'
 import { stringToFloat } from './parse.js'
 
 export { FillClassification }
@@ -24,6 +29,7 @@ const SL_TYPES = new Set<OrderType>([
 
 /**
  * Check if an open order is a Take Profit trigger order.
+ * @public
  */
 export function isTakeProfitOrder(order: Pick<OpenOrder, 'type'>): boolean {
   return TP_TYPES.has(order.type)
@@ -31,6 +37,7 @@ export function isTakeProfitOrder(order: Pick<OpenOrder, 'type'>): boolean {
 
 /**
  * Check if an open order is a Stop Loss trigger order.
+ * @public
  */
 export function isStopLossOrder(order: Pick<OpenOrder, 'type'>): boolean {
   return SL_TYPES.has(order.type)
@@ -38,15 +45,40 @@ export function isStopLossOrder(order: Pick<OpenOrder, 'type'>): boolean {
 
 /**
  * Check if an open order is a TP or SL trigger order.
+ * @public
  */
 export function isTpSlOrder(order: Pick<OpenOrder, 'type'>): boolean {
   return TP_TYPES.has(order.type) || SL_TYPES.has(order.type)
 }
 
+/**
+ * Order statuses representing an order still resting on the book (visible
+ * in `openOrders` / `triggerOrders`). Anything not in this set is terminal —
+ * filled, cancelled, rejected, expired — and should be evicted from the
+ * cached orders list when seen in a WS update.
+ * @public
+ */
+export const ACTIVE_ORDER_STATUSES: ReadonlySet<OrderStatus> = new Set([
+  OrderStatus.OPEN,
+  OrderStatus.PENDING,
+  OrderStatus.PARTIALLY_FILLED,
+  OrderStatus.TRIGGERED,
+])
+
+/**
+ * Whether `status` is one of {@link ACTIVE_ORDER_STATUSES}.
+ *
+ * @public
+ */
+export function isActiveOrderStatus(status: OrderStatus): boolean {
+  return ACTIVE_ORDER_STATUSES.has(status)
+}
+
 /**
  * Classify a fill as open or close based on realizedPnl.
  * @deprecated Use `Fill.classification` instead — it uses startPosition
  * for accurate open/increase/reduce/close/reverse classification.
+ * @public
  */
 export function classifyFill(
   side: OrderSide,

package/src/utils/orderMath.ts

@@ -8,16 +8,17 @@ import {
 import { realizedPnlOnClose } from './positionMath.js'
 
 /**
- * Pick the matching open position for an order's asset, if any.
+ * Pick the matching open position for an order's market, if any.
  *
- * @param assetId - The order's `asset.assetId`.
- * @param positions - Open positions list (any symbol).
+ * @param marketId - The order's `market.id`.
+ * @param positions - Open positions list (any market).
+ * @public
  */
 export function findMatchingPosition(
-  assetId: string,
+  marketId: string,
   positions: readonly Position[]
 ): Position | undefined {
-  return positions.find((p) => p.asset.assetId === assetId)
+  return positions.find((p) => p.market.id === marketId)
 }
 
 /**
@@ -28,6 +29,7 @@ export function findMatchingPosition(
  *    position can only close what's open.
  *
  * Inputs are non-negative magnitudes.
+ * @public
  */
 export function resolveCloseSize(
   orderSize: number,
@@ -47,6 +49,7 @@ export function resolveCloseSize(
  *
  * @returns Realised PnL if the order would reduce the position, otherwise
  *   `null`.
+ * @public
  */
 export function expectedRealizedPnlForOpenOrder(
   order: OpenOrder,
@@ -96,6 +99,7 @@ export function expectedRealizedPnlForOpenOrder(
  * `TriggerOrder` shape) is used as the rPnL price; the optional `limitPrice`
  * for STOP_LIMIT / TAKE_PROFIT_LIMIT is the post-trigger limit, not the rPnL
  * price.
+ * @public
  */
 export function expectedRealizedPnlForTriggerOrder(
   order: TriggerOrder,

package/src/utils/parse.ts

@@ -1,7 +1,3 @@
-/**
- * Robust string-to-number parsing utilities.
- */
-
 /**
  * Parse a string to a float, stripping common formatting artefacts.
  *
@@ -12,14 +8,19 @@
  * - Percentage suffixes (%)
  * - Whitespace
  *
- * @param value - The string to parse
- * @returns Parsed number, or NaN if the string contains no valid number
+ * @returns Parsed number; `0` for empty/blank input, `NaN` when a non-empty
+ *   string contains no parseable number
+ * @example
+ * ```ts
+ * stringToFloat('$1,234.50') // 1234.5
+ * stringToFloat('') // 0
+ * ```
+ * @public
  */
 export function stringToFloat(value: string): number {
   if (!value) {
     return 0
   }
-  // Strip whitespace, currency symbols, thousands commas, and % suffix
   const cleaned = value.trim().replace(/[$%]/g, '').replace(/,/g, '').trim()
   if (!cleaned) {
     return 0

package/src/utils/positionMath.ts

@@ -11,11 +11,49 @@
  *
  * @param isLong - True for long positions, false for short.
  * @returns +1 for long, -1 for short.
+ * @public
  */
 export function directionSign(isLong: boolean): 1 | -1 {
   return isLong ? 1 : -1
 }
 
+/**
+ * Estimated liquidation price for an isolated-margin position, parameterised
+ * by the venue's maintenance margin rate.
+ *
+ * Standard isolated-margin model (new position, no existing exposure):
+ *   margin_per_unit      = entryPrice / leverage
+ *   maintenance_per_unit = entryPrice * mmr
+ *   margin_available     = margin_per_unit - maintenance_per_unit
+ *   liq_price            = entryPrice - side * margin_available / (1 - mmr * side)
+ *
+ * For existing positions, prefer `Position.liquidationPrice` from the venue.
+ *
+ * @param maintenanceMarginRate - Venue maintenance margin rate as a fraction
+ *   (e.g. 0.01 = 1%).
+ * @returns Estimated liquidation price, or undefined if the inputs cannot
+ *   produce one (zero leverage, degenerate denominator).
+ * @public
+ */
+export function estimateIsolatedLiquidationPrice(params: {
+  entryPrice: number
+  leverage: number
+  isLong: boolean
+  maintenanceMarginRate: number
+}): number | undefined {
+  const { entryPrice, leverage, isLong, maintenanceMarginRate } = params
+  if (leverage === 0) {
+    return undefined
+  }
+  const side = directionSign(isLong)
+  const denominator = 1 - maintenanceMarginRate * side
+  if (denominator === 0) {
+    return undefined
+  }
+  const marginAvailable = entryPrice * (1 / leverage - maintenanceMarginRate)
+  return entryPrice - (side * marginAvailable) / denominator
+}
+
 /**
  * Predicted average entry price after adding to an existing position.
  *
@@ -30,6 +68,7 @@ export function directionSign(isLong: boolean): 1 | -1 {
  *   market, limitPrice for limit orders).
  * @returns The new weighted-average entry price, or undefined if the inputs
  *   cannot produce a valid average (zero combined size, non-finite values).
+ * @public
  */
 export function predictAverageEntryPrice(params: {
   currentSize: number
@@ -57,6 +96,7 @@ export function predictAverageEntryPrice(params: {
  *
  * @returns The new effective leverage, or undefined if total margin is
  *   non-positive.
+ * @public
  */
 export function predictNewLeverage(params: {
   currentNotional: number
@@ -78,6 +118,7 @@ export function predictNewLeverage(params: {
  * `pnl = (markPrice - entryPrice) * size * directionSign(isLong)`
  *
  * @param size - Position size as a non-negative magnitude.
+ * @public
  */
 export function predictUnrealizedPnl(params: {
   entryPrice: number
@@ -95,6 +136,7 @@ export function predictUnrealizedPnl(params: {
  * `rPnl = (closePrice - entryPrice) * closeSize * directionSign(isLong)`
  *
  * @param closeSize - Size being closed as a non-negative magnitude.
+ * @public
  */
 export function realizedPnlOnClose(params: {
   entryPrice: number

package/src/utils/signTypedData.ts

@@ -1,9 +1,11 @@
-import type { Hex, PerpsTypedData } from '@lifi/perps-types'
-import type { Account, WalletClient } from 'viem'
+import type { PerpsTypedData } from '@lifi/perps-types'
+import type { Account, Hex, WalletClient } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
 
 /**
  * Sign EIP-712 typed data with a raw private key (agent keypair).
+ *
+ * @public
  */
 export async function signTypedData(
   privateKey: Hex,
@@ -20,13 +22,17 @@ export async function signTypedData(
 /**
  * Sign EIP-712 typed data with an externally-provided WalletClient. Works
  * with browser wallets (wagmi), private keys, mnemonics — any viem
- * WalletClient.
+ * WalletClient. Used by provider plugins to sign the EIP712 USER arm with the
+ * end-user's wallet.
+ *
+ * @public
  */
 export async function signTypedDataWithSigner(
-  signer: WalletClient<any, any, Account>,
+  userWallet: WalletClient<any, any, Account>,
   typedData: PerpsTypedData
 ): Promise<Hex> {
-  return signer.signTypedData({
+  return userWallet.signTypedData({
+    account: userWallet.account,
     domain: typedData.domain,
     types: typedData.types,
     primaryType: typedData.primaryType,

package/src/utils/sleep.ts

@@ -1,2 +1,7 @@
+/**
+ * Resolve after `ms` milliseconds.
+ *
+ * @internal
+ */
 export const sleep = (ms: number): Promise<void> =>
   new Promise((resolve) => setTimeout(resolve, ms))

package/src/utils/units.ts

@@ -9,7 +9,13 @@ import { formatUnits } from 'viem'
  *
  * @param amount - Amount in base units (e.g. "1000000" for 1 USDC)
  * @param decimals - Token decimals (e.g. 6 for USDC)
- * @returns Decimal string (e.g. "1.0")
+ * @returns Decimal string (e.g. "1.0"); `"0"` when `amount` is not a valid
+ *   bigint
+ * @example
+ * ```ts
+ * fromBaseUnits('1000000', 6) // '1'
+ * ```
+ * @public
  */
 export function fromBaseUnits(amount: string, decimals: number): string {
   try {
@@ -25,6 +31,7 @@ export function fromBaseUnits(amount: string, decimals: number): string {
  * @param amount - Amount in base units
  * @param decimals - Token decimals
  * @returns Numeric value, or 0 if parsing fails
+ * @public
  */
 export function fromBaseUnitsNumber(amount: string, decimals: number): number {
   const value = Number(fromBaseUnits(amount, decimals))

package/src/utils/validation.ts

@@ -9,8 +9,11 @@
  * @param _leverage - Position leverage (reserved for future use)
  * @param availableBalance - Available balance, or null if unknown
  * @param _feeRate - Fee rate as decimal, or null if unknown (reserved for future use)
- * @param minMarginUsd - Minimum margin requirement in USD (exchange-specific)
+ * @param minMarginUsd - Minimum margin requirement in USD (exchange-specific).
+ *   Source this from the selected provider's `minOrderValueUsd` metadata
+ *   (see `@lifi/perps-types` `Provider`) rather than a client-side constant.
  * @returns Error code: 'insufficient' | 'below-minimum' | '' (valid)
+ * @public
  */
 export function validateMargin(
   margin: number,

package/src/version.ts

@@ -1,2 +1,2 @@
 export const name = '@lifi/perps-sdk'
-export const version = '0.2.0-alpha.0'
+export const version = '1.0.0'

package/src/websocket/PerpsWsClient.ts

@@ -0,0 +1,204 @@
+import { PerpsErrorCode, type Subscription } from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
+import { getProviders } from '../services/getProviders.js'
+import type { GetQuoteParams } from '../services/getQuote.js'
+import type { PerpsSDKClient, QuoteListener } from '../types/provider.js'
+import { cachePromise } from './cachePromise.js'
+import type {
+  EventForSubscription,
+  SubscriptionListener,
+  WsProvider,
+  WsStatusListener,
+} from './types.js'
+
+/**
+ * Factory for a per-provider WS plugin. Invoked once per provider key the
+ * first time `subscribe(...)` is called against it.
+ *
+ * @public
+ */
+export type WsProviderFactory = (params: {
+  /** Provider key (e.g. `'lighter'`, `'hyperliquid'`). */
+  provider: string
+  /** WS URL discovered from `/providers`. */
+  wsUrl: string
+  /**
+   * Markets visible to this provider via `/providers`, optionally filtered
+   * by the consumer's `createPerpsClient({ providers: { [key]: { markets } } })`
+   * config. Each provider interprets these its own way — Hyperliquid uses
+   * them to decide which sub-DEXes to subscribe to; Lighter ignores them.
+   */
+  markets: string[]
+  /**
+   * The SDK client. WS providers use it to call core services (e.g.
+   * `getAssets` to source the wire-id ↔ display-symbol map) without
+   * duplicating backend orchestration in the WS layer.
+   */
+  client: PerpsSDKClient
+}) => WsProvider
+
+/**
+ * Options for {@link PerpsWsClient}.
+ *
+ * @public
+ */
+export interface PerpsWsClientOptions {
+  /**
+   * Per-provider WS factory map. Each key (e.g. `'hyperliquid'`,
+   * `'lighter'`) maps to a factory that returns a `WsProvider`. Concrete
+   * implementations ship with the provider packages — e.g.
+   * `@lifi/perps-sdk-provider-hyperliquid` exports `HyperliquidWsProvider`,
+   * `@lifi/perps-sdk-provider-lighter` exports `LighterWsProvider`.
+   * Subscribing to a provider key without a registered factory throws.
+   */
+  wsProviders?: Record<string, WsProviderFactory>
+}
+
+/**
+ * Realtime client: lazily instantiates a per-provider {@link WsProvider} on
+ * first subscription and fans subscriptions out to it.
+ *
+ * @public
+ */
+export class PerpsWsClient {
+  private readonly client: PerpsSDKClient
+  private readonly options: PerpsWsClientOptions
+  private providers = new Map<string, WsProvider>()
+  private initPromises = new Map<string, Promise<WsProvider>>()
+
+  constructor(client: PerpsSDKClient, options: PerpsWsClientOptions = {}) {
+    this.client = client
+    this.options = options
+  }
+
+  /**
+   * Subscribe to a realtime channel, lazily creating the provider's WS
+   * connection. Returns an unsubscribe function.
+   *
+   * @param onStatus - Optional listener for the underlying connection's
+   *   health. Fires `reconnecting` on a transient drop and the terminal
+   *   `disconnected` once auto-reconnect is abandoned, so consumers can
+   *   surface a reconnecting/disconnected state instead of silently showing
+   *   stale data.
+   * @throws {PerpsError} When no WS provider factory is registered for the
+   *   subscription's `dex`.
+   * @public
+   */
+  async subscribe<S extends Subscription>(
+    sub: S,
+    listener: (event: EventForSubscription<S>) => void,
+    onStatus?: WsStatusListener
+  ): Promise<() => void> {
+    const providerKey = sub.dex
+    const provider = await this.getOrCreateProvider(providerKey)
+    provider.reconnect()
+    return provider.subscribe(sub, listener as SubscriptionListener, onStatus)
+  }
+
+  /**
+   * Stream live fill quotes for `params.symbol` on `params.provider`, lazily
+   * creating the provider's WS connection. The provider's WS plugin layers the
+   * quote on its orderbook channel, so a concurrent orderbook subscription on
+   * the same market shares one wire subscription. Returns an unsubscribe
+   * function.
+   *
+   * @throws {PerpsError} When no WS provider factory is registered for
+   *   `params.provider`, or no market matches the symbol+type.
+   * @public
+   */
+  async subscribeQuote(
+    params: GetQuoteParams,
+    onQuote: QuoteListener
+  ): Promise<() => void> {
+    const provider = await this.getOrCreateProvider(params.provider)
+    return provider.subscribeQuote(
+      {
+        symbol: params.symbol,
+        side: params.side,
+        size: params.size,
+        type: params.type,
+      },
+      onQuote
+    )
+  }
+
+  /**
+   * Close every open provider WS connection and drop all cached providers.
+   *
+   * @public
+   */
+  close() {
+    for (const p of this.providers.values()) {
+      p.close()
+    }
+    this.providers.clear()
+    this.initPromises.clear()
+  }
+
+  /**
+   * Reconnect an already-created provider when its socket reached terminal
+   * `disconnected`. Safe no-op when the provider is unknown or not terminal.
+   *
+   * @public
+   */
+  reconnect(provider: string): void {
+    this.providers.get(provider)?.reconnect()
+  }
+
+  private async getOrCreateProvider(provider: string): Promise<WsProvider> {
+    const existing = this.providers.get(provider)
+    if (existing) {
+      return existing
+    }
+
+    return cachePromise(
+      () => this.initPromises.get(provider),
+      (p) => {
+        if (p) {
+          this.initPromises.set(provider, p)
+        } else {
+          this.initPromises.delete(provider)
+        }
+      },
+      () => this.initProvider(provider)
+    )
+  }
+
+  private async initProvider(provider: string): Promise<WsProvider> {
+    const factory = this.options.wsProviders?.[provider]
+    if (factory === undefined) {
+      throw new PerpsError(
+        PerpsErrorCode.SDKError,
+        `No WS provider factory registered for '${provider}'. Pass one via ` +
+          'new PerpsWsClient(client, { wsProviders: { [key]: factory } }).'
+      )
+    }
+
+    const { providers } = await getProviders(this.client)
+
+    const providerInfo = providers.find((d) => d.key === provider)
+    if (!providerInfo?.wsUrl) {
+      throw new Error(`No WebSocket URL found for provider: ${provider}`)
+    }
+
+    const allMarkets = (providerInfo.categories ?? []) as Array<{
+      id: string
+    }>
+    const providerConfig = this.client.config.providers?.[provider]
+    const configuredMarkets = providerConfig?.markets
+    const markets = (
+      configuredMarkets
+        ? allMarkets.filter((m) => configuredMarkets.includes(m.id))
+        : allMarkets
+    ).map((m) => m.id)
+
+    const wsProvider = factory({
+      provider,
+      wsUrl: providerInfo.wsUrl,
+      markets,
+      client: this.client,
+    })
+    this.providers.set(provider, wsProvider)
+    return wsProvider
+  }
+}