@lifi/perps-sdk 6.0.0 → 6.1.0

package/src/types/deposit.ts

@@ -9,9 +9,11 @@ import type { Address } from 'viem'
  * @public
  */
 export interface DeclaredDepositAsset {
+  /** EVM chain id on which the asset is held or broadcast. */
   chainId: number
-  /** EIP-55 checksummed address; the zero address denotes the chain's native gas token. */
+  /** EIP-55 checksummed address; the zero address denotes native gas. */
   address: Address
+  /** Decimal places used by the token; native gas assets use 18. */
   decimals: number
 }
 
@@ -25,6 +27,7 @@ export interface DeclaredDepositAsset {
  */
 export interface DepositFlowLifiSwap {
   kind: 'lifiSwap'
+  /** Destination collateral token and its full chain identity. */
   destination: DeclaredDepositAsset
   /**
    * Credited address when it is not the user's own — a venue-provisioned
@@ -43,10 +46,13 @@ export interface DepositFlowLifiSwap {
  */
 export interface DepositFlowFirstDepositPipeline {
   kind: 'firstDepositPipeline'
-  /** Chain the deposit legs broadcast on; the user's wallet must be switched to it. */
+  /** Chain on which the deposit legs broadcast; the wallet must be switched here. */
   chainId: number
+  /** Native gas asset needed to broadcast the deposit legs. */
   gasAsset: DeclaredDepositAsset
+  /** Collateral asset credited by the first deposit. */
   collateral: DeclaredDepositAsset
+  /** Action type used to stage the deposit pipeline. */
   bridgeAction: ActionType.DEPOSIT
 }
 
@@ -59,7 +65,7 @@ export interface DepositFlowFirstDepositPipeline {
  */
 export interface DepositFlowSetupRequired {
   kind: 'setupRequired'
-  /** Outstanding `Provider.setup` action types, in the order they must be run. */
+  /** Setup action types that must be completed, in execution order. */
   setup: ActionType[]
 }
 

package/src/types/provider.ts

@@ -43,22 +43,14 @@ import type { DepositFlow } from './deposit.js'
  */
 export interface PerpsSDKClient {
   readonly config: PerpsBaseConfig
-  /** The end-user's wallet — accepts any viem WalletClient (browser, private key, mnemonic). */
+  /** End-user wallet for USER-signed or on-chain EVM legs, when configured. */
   readonly userWallet?: PerpsClientSigner
-  /** Registered providers, bound to this client, in construction order. */
+  /** Providers bound to this client, in registration order. */
   readonly providers: PerpsProvider[]
-  /** Look up a registered bound {@link PerpsProvider} by its `type` key. */
+  /** Look up a bound provider by its wire `type` key. */
   getProvider(key: string): PerpsProvider | undefined
 }
 
-/**
- * Per-call context passed by `PerpsClient` to a provider's {@link
- * PerpsProvider.signActions} method. Carries the end-user's wallet (when
- * configured); providers that own a session credential (e.g. the Hyperliquid
- * agent keypair, Lighter's API key) resolve it internally.
- *
- * @public
- */
 /**
  * Progress for one on-chain leg of an `EVM_TX` batch (e.g. a native deposit's
  * `approve` then `deposit`). Emitted twice per leg: `submitted` once the wallet
@@ -68,19 +60,26 @@ export interface PerpsSDKClient {
  * @public
  */
 export interface SignActionProgress {
-  /** 0-based index of this leg within the batch. */
   index: number
-  /** Total legs in the batch. */
   total: number
   action: ActionType
-  /** Contract function the leg invokes, e.g. `"approve"` or the deposit method. */
   functionName: string
   chainId: number
+  /** Whether the transaction was broadcast or its receipt confirmed. */
   status: 'submitted' | 'confirmed'
   txHash: string
 }
 
+/**
+ * Per-call context passed by `PerpsClient` to a provider's
+ * {@link PerpsProviderPlugin.signActions} implementation. Carries the
+ * configured end-user wallet, descriptor-declared signer roles, an optional
+ * chain-switch helper, and an optional progress callback.
+ *
+ * @public
+ */
 export interface SignActionsContext {
+  /** End-user wallet used for USER-signed or EVM transaction legs. */
   userWallet?: PerpsClientSigner
   /**
    * The signing batch's declared signers, from the action's `ProviderAction`
@@ -142,8 +141,10 @@ export interface ActionSignerContribution {
  * @public
  */
 export interface LiquidationEstimateParams {
+  /** Entry price in quote currency per base unit. */
   entryPrice: number
   leverage: number
+  /** `true` for long, `false` for short. */
   isLong: boolean
 }
 
@@ -182,9 +183,11 @@ export interface ProviderGetDepositFlowParams {
  */
 export interface ProviderGetPositionsParams {
   address: Address
-  /** Optional filter — opaque `Market.id` (not `displaySymbol`). */
+  /** Optional opaque `Market.id` filter (not a display symbol). */
   marketId?: string
+  /** Maximum items returned; provider defaults and caps apply. */
   limit?: number
+  /** Opaque pagination cursor from the previous response. */
   cursor?: string
 }
 
@@ -207,9 +210,11 @@ export interface ProviderGetMarketSettingsParams {
  */
 export interface ProviderGetOrdersParams {
   address: Address
-  /** Optional filter — opaque `Market.id` (not `displaySymbol`). */
+  /** Optional opaque `Market.id` filter (not a display symbol). */
   marketId?: string
+  /** Maximum items returned; provider defaults and caps apply. */
   limit?: number
+  /** Opaque pagination cursor from the previous response. */
   cursor?: string
 }
 
@@ -220,6 +225,7 @@ export interface ProviderGetOrdersParams {
  */
 export interface ProviderGetOrderParams {
   address: Address
+  /** Venue order id, opaque to the SDK. */
   id: string
 }
 
@@ -230,9 +236,13 @@ export interface ProviderGetOrderParams {
  */
 export interface ProviderGetFillsParams {
   address: Address
+  /** Maximum items returned; provider defaults and caps apply. */
   limit?: number
+  /** Opaque pagination cursor from the previous response. */
   cursor?: string
+  /** Include fills at or after this Unix timestamp in milliseconds. */
   startTime?: number
+  /** Include fills at or before this Unix timestamp in milliseconds. */
   endTime?: number
 }
 
@@ -243,10 +253,15 @@ export interface ProviderGetFillsParams {
  */
 export interface ProviderGetActivityParams {
   address: Address
+  /** Maximum items returned; provider defaults and caps apply. */
   limit?: number
+  /** Opaque pagination cursor from the previous response. */
   cursor?: string
+  /** Include activity at or after this Unix timestamp in milliseconds. */
   startTime?: number
+  /** Include activity at or before this Unix timestamp in milliseconds. */
   endTime?: number
+  /** Optional filter for activity types. */
   type?: ActivityType[]
 }
 
@@ -257,11 +272,13 @@ export interface ProviderGetActivityParams {
  * @public
  */
 export interface ProviderGetQuoteParams {
-  /** Human `displaySymbol`, e.g. `"BTC"`. Resolved against the provider's own markets, scoped by `type`. */
+  /** Human `displaySymbol`, resolved against this provider and `type`. */
   symbol: string
+  /** Trade direction used to choose asks for buys or bids for sells. */
   side: QuoteSide
   /** USD notional to fill. */
   size: number
+  /** Product family used to disambiguate spot and perpetual markets. */
   type: TradeType
 }
 

package/src/utils/calculations.ts

@@ -175,7 +175,9 @@ export function effectiveLeverage(params: {
  * @public
  */
 export interface ExpectedPnl {
+  /** Signed expected profit/loss in USD. */
   amount: number
+  /** Signed expected return as a percentage (10 means 10%). */
   percent: number
 }
 

package/src/utils/format.ts

@@ -19,7 +19,11 @@ export interface FormatOptions {
   rounding?: RoundingMode
 }
 
-/** Rounding mode for {@link FormatOptions.rounding}. */
+/**
+ * Rounding mode for {@link FormatOptions.rounding}.
+ *
+ * @public
+ */
 export type RoundingMode = 'halfUp' | 'floor'
 
 const DEFAULT_PLACEHOLDER = '—'

package/src/utils/orderClassification.ts

@@ -15,6 +15,11 @@ import {
 } from '@lifi/perps-types'
 import { stringToFloat } from './parse.js'
 
+/**
+ * Re-exported fill taxonomy used by {@link classifyFillFromPosition}.
+ *
+ * @public
+ */
 export { FillClassification }
 
 const TP_TYPES = new Set<OrderType>([

package/src/utils/transferMargin.ts

@@ -1,9 +1,8 @@
 import {
-  MarginMode,
   PerpsErrorCode,
   type Position,
-  PositionMarginAdjustment,
   type PositionMarginConstraints,
+  positionSupportsMarginRemoval,
 } from '@lifi/perps-types'
 import Big from 'big.js'
 import { PerpsError } from '../errors/PerpsError.js'
@@ -66,11 +65,7 @@ export function removableIsolatedMargin({
   position,
   constraints,
 }: RemovableIsolatedMarginParams): string {
-  if (
-    position.marginMode !== MarginMode.ISOLATED ||
-    position.market.positionMarginAdjustment !==
-      PositionMarginAdjustment.ADD_AND_REMOVE
-  ) {
+  if (!positionSupportsMarginRemoval(position)) {
     return '0'
   }
 

package/src/version.ts

@@ -1,2 +1,2 @@
 export const name = '@lifi/perps-sdk'
-export const version = '6.0.0'
+export const version = '6.1.0'

package/src/websocket/PerpsWsClient.ts

@@ -18,7 +18,6 @@ import type {
  * @public
  */
 export type WsProviderFactory = (params: {
-  /** Provider key (e.g. `'lighter'`, `'hyperliquid'`). */
   provider: string
   /** WS URL discovered from `/providers`. */
   wsUrl: string

package/src/websocket/ReconnectingWebSocket.ts

@@ -44,7 +44,9 @@ const WS_PROVIDER_KEY = 'reconnecting-websocket'
  * @public
  */
 export interface ReconnectingWebSocketOptions {
+  /** Maximum reconnect attempts before status becomes `disconnected`; defaults to 10. */
   maxRetries?: number
+  /** Keepalive interval in milliseconds; defaults to 30,000. */
   pingIntervalMs?: number
   /**
    * Keepalive frame sent every `pingIntervalMs` while the socket is open.
@@ -52,9 +54,9 @@ export interface ReconnectingWebSocketOptions {
    */
   pingPayload?: string
   /**
-   * Stale-stream watchdog window. With `pingPayload` configured, the socket is
-   * force-reconnected when no inbound frame arrives within this window.
-   * Defaults to 3× `pingIntervalMs`.
+   * Stale-stream watchdog window in milliseconds. With `pingPayload` configured,
+   * the socket is force-reconnected when no inbound frame arrives within this
+   * window. Defaults to 3× `pingIntervalMs`.
    */
   staleWindowMs?: number
 }

package/src/websocket/WsProviderBase.ts

@@ -76,6 +76,13 @@ export abstract class WsProviderBase<TSub = unknown> implements WsProvider {
     })
   }
 
+  /**
+   * Acquire a ref-counted subscription to a provider channel and return an
+   * idempotent release function. Optional status listeners are reference-counted
+   * alongside the channel listener.
+   *
+   * @public
+   */
   async subscribe(
     sub: Subscription,
     listener: SubscriptionListener,
@@ -112,6 +119,11 @@ export abstract class WsProviderBase<TSub = unknown> implements WsProvider {
     }
   }
 
+  /**
+   * Reconnect the underlying socket only when it is terminally disconnected.
+   *
+   * @public
+   */
   reconnect(): void {
     if (this.rws.getStatus() !== 'disconnected') {
       return
@@ -119,6 +131,11 @@ export abstract class WsProviderBase<TSub = unknown> implements WsProvider {
     this.rws.reconnect()
   }
 
+  /**
+   * Release all channel and status listeners and close the underlying socket.
+   *
+   * @public
+   */
   close(): void {
     for (const entry of this.channels.values()) {
       if (entry.pendingTeardown !== undefined) {

package/src/websocket/cachePromise.ts

@@ -9,6 +9,8 @@
  * @param read - Returns the currently cached promise, or `undefined` if none.
  * @param write - Stores (or with `undefined`, clears) the cached promise.
  * @param factory - Creates the promise when the slot is empty.
+ *
+ * @public
  */
 export function cachePromise<T>(
   read: () => Promise<T> | undefined,

package/src/websocket/types.ts

@@ -50,6 +50,10 @@ export type WsStatusListener = (status: WsConnectionStatus) => void
  * @public
  */
 export interface WsProvider {
+  /**
+   * Subscribe to one venue channel and return an idempotent unsubscribe.
+   * `onStatus` receives the provider socket's health transitions.
+   */
   subscribe(
     sub: Subscription,
     listener: SubscriptionListener,
@@ -71,5 +75,6 @@ export interface WsProvider {
     params: ProviderGetQuoteParams,
     onQuote: QuoteListener
   ): Promise<() => void>
+  /** Permanently close the provider's realtime connection. */
   close(): void
 }