@lifi/perps-sdk 1.5.5 → 1.6.0

package/src/registry/referenceDataRegistry.ts

@@ -1,17 +1,13 @@
 import type { PerpsSDKClient } from '../types/provider.js'
 
-/** Minimum gap between unknown-id-triggered, HTTP-cache-bypassing refetches. */
-const REFRESH_COOLDOWN_MS = 60_000
-
 /**
  * Per-provider hash index over one of the provider's reference-data lists
  * (`/markets`, `/assets`), keyed by the list's own primary key.
  *
  * NOT a cache: it holds no freshness policy of its own. Every {@link sync}
  * refetches through the HTTP layer, whose `cache-control` headers decide
- * whether the response comes from disk or the network. A lookup miss
- * schedules a cooldown-gated background refetch that bypasses the HTTP
- * cache — the id may have listed after the cached snapshot.
+ * whether the response comes from disk or the network. A lookup miss warns
+ * once and returns `undefined`; the next {@link sync} reconciles the index.
  *
  * @internal
  */
@@ -20,7 +16,6 @@ export abstract class ReferenceDataRegistry<T> {
   private current: readonly T[] = []
   private inflight: Promise<readonly T[]> | undefined
   private warnedIds = new Set<string>()
-  private refreshAfter = 0
 
   protected constructor(
     protected readonly client: PerpsSDKClient,
@@ -28,8 +23,8 @@ export abstract class ReferenceDataRegistry<T> {
     private readonly kind: string
   ) {}
 
-  /** Fetch the provider's full list, bypassing the HTTP cache when asked. */
-  protected abstract fetchItems(bypassHttpCache: boolean): Promise<T[]>
+  /** Fetch the provider's full list through the HTTP layer. */
+  protected abstract fetchItems(): Promise<T[]>
 
   /** The item's primary key — what {@link get} is keyed by. */
   protected abstract keyOf(item: T): string
@@ -41,7 +36,7 @@ export abstract class ReferenceDataRegistry<T> {
    */
   sync(): Promise<readonly T[]> {
     if (!this.inflight) {
-      this.inflight = this.load(false).finally(() => {
+      this.inflight = this.load().finally(() => {
         this.inflight = undefined
       })
     }
@@ -53,10 +48,7 @@ export abstract class ReferenceDataRegistry<T> {
     return this.current
   }
 
-  /**
-   * O(1) lookup by primary key. A miss warns once per id and schedules the
-   * cooldown-gated, cache-bypassing background refetch.
-   */
+  /** O(1) lookup by primary key. A miss warns once per id. */
   get(id: string): T | undefined {
     const item = this.index.get(id)
     if (item !== undefined) {
@@ -66,30 +58,14 @@ export abstract class ReferenceDataRegistry<T> {
       this.warnedIds.add(id)
       console.warn(`[${this.provider}] unknown ${this.kind} id '${id}'`)
     }
-    this.scheduleRefresh()
     return undefined
   }
 
-  private async load(bypassHttpCache: boolean): Promise<readonly T[]> {
-    const items = await this.fetchItems(bypassHttpCache)
+  private async load(): Promise<readonly T[]> {
+    const items = await this.fetchItems()
     this.index = new Map(items.map((item) => [this.keyOf(item), item]))
     this.current = items
     this.warnedIds.clear()
     return items
   }
-
-  private scheduleRefresh(): void {
-    const now = Date.now()
-    if (now < this.refreshAfter) {
-      return
-    }
-    // Set before any await so concurrent misses cannot trigger a refetch storm.
-    this.refreshAfter = now + REFRESH_COOLDOWN_MS
-    this.load(true).catch((error) =>
-      console.error(
-        `[${this.provider}] ${this.kind} registry refresh failed`,
-        error
-      )
-    )
-  }
 }

package/src/services/getMarket.ts

@@ -1,4 +1,6 @@
 import type { Market, MarketsResponse } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
 import { buildUrl, request } from '../transport/request.js'
 import type { SDKRequestOptions } from '../types/config.js'
 import type { PerpsSDKClient } from '../types/provider.js'
@@ -21,10 +23,11 @@ export interface GetMarketParams {
 /**
  * Get a specific market by its opaque marketId. Requests the single market
  * from the backend `/markets` route (filtered by `marketIds`) and returns the
- * first match; the backend responds 404 (thrown as a {@link PerpsError}) when
- * nothing matches.
+ * first match; throws a `MarketNotFound` {@link PerpsError} both when the
+ * backend responds 404 and when it responds 200 with an empty list, matching
+ * `MarketRegistry.require`'s miss behaviour.
  *
- * @throws {PerpsError} On backend (e.g. 404), network, or parsing errors.
+ * @throws {PerpsError} On backend (e.g. 404 or empty match), network, or parsing errors.
  * @example
  * ```ts
  * const client = createPerpsClient({ integrator: 'my-app' })
@@ -48,5 +51,14 @@ export async function getMarket(
     {},
     options
   )
-  return markets[0]
+  const market = markets[0]
+  if (market === undefined) {
+    const error = new PerpsError(
+      PerpsErrorCode.MarketNotFound,
+      `No ${params.provider} market found for marketId '${params.marketId}'`
+    )
+    error.tool = params.provider
+    throw error
+  }
+  return market
 }

package/src/utils/accountSummary.ts

@@ -13,11 +13,15 @@ const sumValueUsd = (balances: AccountResponse['balances']): number =>
  * positions' locked margin and unrealized PnL:
  *
  * - `'free'` — free collateral only; locked margin and unrealized PnL are
- *   both carried by the positions.
+ *   both carried by the positions. Available margin is the free collateral
+ *   as-is; unrealized PnL is not counted toward it.
  * - `'gross'` — locked margin included, unrealized PnL carried by the
- *   positions (e.g. spot holdings backing a unified account).
+ *   positions (e.g. spot holdings backing a unified account). The venue
+ *   counts unrealized PnL toward buying power, so it is added to available
+ *   margin on top of the gross collateral.
  * - `'equity'` — total equity: locked margin AND unrealized PnL included
- *   (e.g. a venue-reported account value).
+ *   (e.g. a venue-reported account value). Unrealized PnL is thus already
+ *   counted toward available margin.
  *
  * @public
  */
@@ -51,9 +55,15 @@ export function summarizeAccount(
   const equity =
     semantics === 'equity' ? grossCollateral : grossCollateral + unrealizedPnl
 
+  // Buying power is equity net of locked margin, so unrealized PnL counts
+  // toward it. The `'free'` rows exclude uPnL from available margin, holding
+  // it purely as free collateral.
+  const availableMargin =
+    semantics === 'free' ? grossCollateral - marginUsed : equity - marginUsed
+
   return {
     portfolioValue: (balances + equity).toString(),
-    availableMargin: (grossCollateral - marginUsed).toString(),
+    availableMargin: availableMargin.toString(),
     marginUsed: marginUsed.toString(),
     unrealizedPnl: unrealizedPnl.toString(),
   }

package/src/utils/calculations.ts

@@ -6,15 +6,17 @@
  * values for critical financial parameters.
  */
 
-import type {
-  FeeTier,
-  Market,
-  MarketContext,
-  OrderbookLevel,
-  Quote,
-  QuoteSide,
-  TradeType,
+import {
+  type FeeTier,
+  type Market,
+  type MarketContext,
+  type OrderbookLevel,
+  PerpsErrorCode,
+  type Quote,
+  type QuoteSide,
+  type TradeType,
 } from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
 
 /**
  * Calculate position size in asset units from margin.
@@ -319,6 +321,8 @@ interface BookWalk {
  * notional, the walk stops at the last level and flags `insufficientLiquidity`,
  * returning the best obtainable fill.
  *
+ * @throws {PerpsError} `ValidationError` when a level's `price` or `size`
+ *   does not parse to a finite number.
  * @public
  */
 export function walkOrderbook(
@@ -333,7 +337,14 @@ export function walkOrderbook(
       break
     }
     const price = Number.parseFloat(level.price)
-    const levelNotional = Number.parseFloat(level.size) * price
+    const size = Number.parseFloat(level.size)
+    if (!Number.isFinite(price) || !Number.isFinite(size)) {
+      throw new PerpsError(
+        PerpsErrorCode.ValidationError,
+        `Malformed orderbook level: price='${level.price}', size='${level.size}'`
+      )
+    }
+    const levelNotional = size * price
     const take = Math.min(remaining, levelNotional)
     filledNotional += take
     baseSize += take / price
@@ -370,6 +381,8 @@ interface BuildQuoteInput {
  * versus mark, applies the base taker fee on the filled notional, and carries
  * the market's `funding` (`null` for spot, which has none).
  *
+ * @throws {PerpsError} `ValidationError` when a book level does not parse to
+ *   a finite number — see {@link walkOrderbook}.
  * @public
  */
 export function buildQuote(input: BuildQuoteInput): Quote {

package/src/version.ts

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

package/src/websocket/ReconnectingWebSocket.ts

@@ -238,16 +238,21 @@ export class ReconnectingWebSocket {
 
   /**
    * Send `data`, buffering it (bounded) for replay when the socket is not yet
-   * open.
+   * open. Throws once {@link ReconnectingWebSocket.close} has been called —
+   * there is no socket left to buffer against.
    *
    * @public
    */
   send(data: string) {
+    if (this.closed) {
+      throw new Error(CLOSED_ERROR)
+    }
     this.socket.send(data)
   }
 
   /**
-   * Permanently close the socket and suppress further reconnection.
+   * Permanently close the socket, suppress further reconnection, and set
+   * status to terminal `disconnected`.
    *
    * @public
    */
@@ -256,6 +261,7 @@ export class ReconnectingWebSocket {
     this.stopPing()
     this.clearWatchdog()
     this.socket.close()
+    this.setStatus('disconnected')
     for (const { reject } of this.readyResolvers) {
       reject(new Error(CLOSED_ERROR))
     }
@@ -300,8 +306,9 @@ export class ReconnectingWebSocket {
 
   /**
    * Current connection health. `reconnecting` until the first open;
-   * `disconnected` once auto-reconnect is abandoned (terminal until
-   * {@link ReconnectingWebSocket.reconnect} is called).
+   * `disconnected` once auto-reconnect is abandoned or {@link
+   * ReconnectingWebSocket.close} is called (terminal until {@link
+   * ReconnectingWebSocket.reconnect} is called).
    *
    * @public
    */

package/src/websocket/WsProviderBase.ts

@@ -94,7 +94,12 @@ export abstract class WsProviderBase<TSub = unknown> implements WsProvider {
       onStatus(this.rws.getStatus())
     }
 
+    let released = false
     return () => {
+      if (released) {
+        return
+      }
+      released = true
       if (onStatus) {
         const remaining = (this.statusListeners.get(onStatus) ?? 0) - 1
         if (remaining > 0) {
@@ -188,7 +193,15 @@ export abstract class WsProviderBase<TSub = unknown> implements WsProvider {
   }
 
   private async replaySubs(): Promise<void> {
-    for (const [key, state] of this.wireSubs) {
+    // Snapshot at replay start, and re-check the live registry before each
+    // send. An async sendSubscribe (e.g. Lighter's auth-token fetch) suspends
+    // the loop; status is already 'connected' while open listeners run, so a
+    // subscribe landing mid-replay is sent inline by registerSub — it must not
+    // be revisited here, and an entry unregistered mid-replay must be skipped.
+    for (const [key, state] of [...this.wireSubs]) {
+      if (this.wireSubs.get(key) !== state) {
+        continue
+      }
       // Isolate each resubscribe: a send can reject (e.g. an auth-token fetch
       // after reconnect), and one sub's failure must not abort the rest of
       // the loop or escape as an unhandled rejection.

package/src/websocket/types.ts

@@ -28,9 +28,9 @@ export type SubscriptionListener = (event: SubscriptionEvent) => void
  * - `connected` — socket open, live data flowing.
  * - `reconnecting` — socket dropped; auto-reconnect with backoff in progress.
  *   Data may be stale until it returns to `connected`.
- * - `disconnected` — reconnection abandoned after the retry cap. The
- *   connection is permanently dead and will not recover on its own; the
- *   subscription's data is stale. Terminal.
+ * - `disconnected` — reconnection abandoned after the retry cap, or the
+ *   connection was explicitly closed. The connection is permanently dead and
+ *   will not recover on its own; the subscription's data is stale. Terminal.
  *
  * @public
  */