@lifi/perps-sdk 20.0.0 → 20.1.1

package/src/registry/referenceDataRegistry.ts

@@ -1,14 +1,64 @@
 import { PerpsErrorCode } from '@lifi/perps-types'
 import { PerpsError } from '../errors/PerpsError.js'
+import type { RequestOptions } from '../transport/request.js'
 import type { PerpsSDKClient } from '../types/provider.js'
 import { createWarnOnce } from '../utils/warnOnce.js'
 
+function freshUntil(
+  headers: Headers,
+  requestStartedAt: number,
+  responseReceivedAt: number
+): number {
+  const directives = (headers.get('cache-control') ?? '')
+    .toLowerCase()
+    .split(',')
+    .map((directive) => directive.trim())
+  if (
+    directives.some((directive) =>
+      /^(no-store|no-cache)(?:\s*=|$)/.test(directive)
+    ) ||
+    headers
+      .get('vary')
+      ?.split(',')
+      .some((name) => name.trim() === '*')
+  ) {
+    return 0
+  }
+  const maxAges = directives.filter((directive) =>
+    /^max-age(?:\s*=|$)/.test(directive)
+  )
+  const maxAge =
+    maxAges.length === 1
+      ? /^max-age\s*=\s*(?:"(\d+)"|(\d+))$/.exec(maxAges[0])
+      : null
+  if (!maxAge) {
+    return 0
+  }
+  const age = headers.get('age') ?? '0'
+  const date = headers.get('date')
+  const dateTime = date === null ? responseReceivedAt : Date.parse(date)
+  if (!/^\d+$/.test(age) || !Number.isFinite(dateTime)) {
+    return 0
+  }
+  const lifetime = Number(maxAge[1] ?? maxAge[2]) * 1000
+  const currentAge = Math.max(
+    responseReceivedAt - dateTime,
+    Number(age) * 1000 + Math.max(0, responseReceivedAt - requestStartedAt)
+  )
+  return Number.isFinite(lifetime)
+    ? responseReceivedAt + lifetime - currentAge
+    : 0
+}
+
 /** Atomic provider reference indexes; HTTP cache headers govern freshness. @internal */
 export abstract class ReferenceDataRegistry<T> {
   private index = new Map<string, T>()
   private secondaryIndexes = new Map<string, Map<string, T>>()
   private current: readonly T[] = []
   private inflight: Promise<readonly T[]> | undefined
+  private inflightIdentity: string | undefined
+  private cacheIdentity: string | undefined
+  private freshUntil = 0
   private readonly warnOnce = createWarnOnce()
 
   protected constructor(
@@ -21,21 +71,37 @@ export abstract class ReferenceDataRegistry<T> {
   ) {}
 
   /** Fetch the provider's full list through the HTTP layer. */
-  protected abstract fetchItems(): Promise<T[]>
+  protected abstract fetchItems(
+    onResponse: RequestOptions['onResponse']
+  ): Promise<T[]>
 
   /** The item's primary key — what {@link get} is keyed by. */
   protected abstract keyOf(item: T): string
 
-  /**
-   * Fetch the list through the HTTP cache and rebuild the index. Concurrent
-   * callers share one in-flight fetch; a settled fetch is never reused, so
-   * HTTP `cache-control` alone governs freshness.
-   */
+  /** Sync reference indexes, reusing only explicitly fresh Node responses. */
   sync(): Promise<readonly T[]> {
-    if (!this.inflight) {
-      this.inflight = this.load().finally(() => {
-        this.inflight = undefined
+    const { config } = this.client
+    // Hooks can change credentials or cache policy on every call.
+    if (config.requestInterceptor || config.fetch) {
+      return this.load()
+    }
+    const identity = JSON.stringify([
+      config.apiUrl,
+      config.apiKey,
+      config.integrator,
+    ])
+    if (identity === this.cacheIdentity && Date.now() < this.freshUntil) {
+      return Promise.resolve(this.current)
+    }
+    if (!this.inflight || this.inflightIdentity !== identity) {
+      const inflight = this.load(identity).finally(() => {
+        if (this.inflight === inflight) {
+          this.inflight = undefined
+          this.inflightIdentity = undefined
+        }
       })
+      this.inflight = inflight
+      this.inflightIdentity = identity
     }
     return this.inflight
   }
@@ -59,8 +125,18 @@ export abstract class ReferenceDataRegistry<T> {
     return this.secondaryIndexes.get(key)?.get(id)
   }
 
-  private async load(): Promise<readonly T[]> {
-    const items = await this.fetchItems()
+  private async load(identity?: string): Promise<readonly T[]> {
+    let expiresAt = 0
+    const items = await this.fetchItems((headers, startedAt, receivedAt) => {
+      // Browsers retain their native HTTP cache and its resident response age.
+      if (
+        identity !== undefined &&
+        typeof process !== 'undefined' &&
+        process.versions?.node
+      ) {
+        expiresAt = freshUntil(headers, startedAt, receivedAt)
+      }
+    })
     const index = new Map<string, T>()
     for (const item of items) {
       const key = this.keyOf(item)
@@ -93,6 +169,8 @@ export abstract class ReferenceDataRegistry<T> {
     this.index = index
     this.secondaryIndexes = secondaryIndexes
     this.current = items
+    this.cacheIdentity = identity
+    this.freshUntil = expiresAt
     return items
   }
 }

package/src/transport/request.ts

@@ -20,6 +20,12 @@ import {
 export interface RequestOptions extends RequestInit {
   /** Per-call retry override. Falls back to the resolved client-level policy. */
   retry?: RetryPolicy | false
+  /** Successful response metadata, delivered only after JSON decoding. */
+  onResponse?: (
+    headers: Headers,
+    requestStartedAt: number,
+    responseReceivedAt: number
+  ) => void
 }
 
 /**
@@ -34,7 +40,7 @@ export async function request<T>(
   options: RequestOptions = {},
   sdkOptions?: SDKRequestOptions
 ): Promise<T> {
-  const { retry, ...fetchInit } = options
+  const { retry, onResponse, ...fetchInit } = options
   const policy =
     retry !== undefined
       ? resolveRetryPolicy(LIFI_RETRY_DEFAULTS, retry, LIFI_REQUEST_KEY)
@@ -64,11 +70,13 @@ export async function request<T>(
   }
 
   try {
+    const requestStartedAt = onResponse ? Date.now() : 0
     const response = await fetchWithRetry(url, finalOptions, {
       policy,
       fetchImpl: config.fetch,
       signal: sdkOptions?.signal ?? finalOptions.signal ?? undefined,
     })
+    const responseReceivedAt = onResponse ? Date.now() : 0
 
     if (!response.ok) {
       let body: PerpsErrorBody | undefined
@@ -94,7 +102,9 @@ export async function request<T>(
       throw error
     }
 
-    return (await response.json()) as T
+    const data = (await response.json()) as T
+    onResponse?.(response.headers, requestStartedAt, responseReceivedAt)
+    return data
   } catch (error) {
     if (error instanceof PerpsError) {
       throw error

package/src/types/withdrawal.ts

@@ -1,4 +1,9 @@
-import type { ActionType, Asset, WithdrawalRoute } from '@lifi/perps-types'
+import type {
+  ActionType,
+  Asset,
+  DecimalString,
+  WithdrawalRoute,
+} from '@lifi/perps-types'
 import type { Address } from 'viem'
 
 export type { WithdrawalRoute }
@@ -14,13 +19,13 @@ export interface ProviderWithdrawableBalance {
   assetId: string
   route: WithdrawalRoute
   /** Withdrawable amount in the asset's own units. Always greater than zero. */
-  available: string
+  available: DecimalString
   /**
    * Flat venue fee on a withdrawal from this row, in the asset's own units.
    * Absent when the venue publishes no fee for the asset. The client rejects
    * a value that is not a non-negative decimal.
    */
-  withdrawalFee?: string
+  withdrawalFee?: DecimalString
   /**
    * `true` when the venue takes `withdrawalFee` out of the requested amount,
    * `false` when it charges the fee in addition. Set together with
@@ -40,7 +45,7 @@ export interface WithdrawableBalance {
   asset: Asset
   route: WithdrawalRoute
   /** Withdrawable amount in the asset's own units. */
-  available: string
+  available: DecimalString
   /**
    * Flat venue fee on a withdrawal from this row, in the asset's own units.
    * Absent when the venue publishes no fee for the asset. With
@@ -51,7 +56,7 @@ export interface WithdrawableBalance {
    * is zero or negative when the fee is at or above `available`, and the row
    * then funds no withdrawal.
    */
-  withdrawalFee?: string
+  withdrawalFee?: DecimalString
   /**
    * Present only together with `withdrawalFee`. Absent on a row from a
    * provider plugin that does not report it; absence means unknown, not

package/src/utils/decimal.ts

@@ -7,6 +7,14 @@ import Big from 'big.js'
 export const DivBig = Big()
 DivBig.DP = 40
 
+/**
+ * As `DivBig`, but truncating, so a derived amount never rounds up past the
+ * exact quotient.
+ */
+export const TruncBig = Big()
+TruncBig.DP = 40
+TruncBig.RM = Big.roundDown
+
 /** True when every value is a finite number, so `new DivBig(value)` cannot throw. */
 export function areFinite(...values: number[]): boolean {
   return values.every(Number.isFinite)

package/src/utils/orderEntry.ts

@@ -0,0 +1,38 @@
+import type Big from 'big.js'
+import { TruncBig } from './decimal.js'
+
+/**
+ * Base size the given margin buys at `leverage`: size = margin × leverage ÷ price.
+ * Truncates, so `size × price` never exceeds `margin × leverage`.
+ * @public
+ */
+export function sizeFromMargin(margin: Big, leverage: number, price: Big): Big {
+  return new TruncBig(margin).times(leverage).div(price)
+}
+
+/**
+ * Margin that holds the given base size at `leverage`: margin = size × price ÷ leverage.
+ * Truncates, so `margin × leverage` never exceeds `size × price`.
+ * @public
+ */
+export function marginFromSize(size: Big, leverage: number, price: Big): Big {
+  return new TruncBig(size).times(price).div(leverage)
+}
+
+/**
+ * Base size for a notional: size = notional ÷ price.
+ * Truncates, so `size × price` never exceeds the notional.
+ * @public
+ */
+export function sizeFromNotional(notionalUsd: Big, price: Big): Big {
+  return new TruncBig(notionalUsd).div(price)
+}
+
+/**
+ * Margin for a notional at `leverage`: margin = notional ÷ leverage.
+ * Truncates, so `margin × leverage` never exceeds the notional.
+ * @public
+ */
+export function marginFromNotional(notionalUsd: Big, leverage: number): Big {
+  return new TruncBig(notionalUsd).div(leverage)
+}

package/src/version.ts

@@ -10,4 +10,4 @@ export const name = '@lifi/perps-sdk'
  *
  * @public
  */
-export const version = '20.0.0'
+export const version = '20.1.1'

package/src/websocket/WsProviderBase.ts

@@ -199,7 +199,9 @@ export abstract class WsProviderBase<TSub = unknown> implements WsProvider {
     try {
       await this.sendSubscribe(state)
     } catch (err) {
-      this.wireSubs.delete(key)
+      if (this.wireSubs.get(key) === state) {
+        this.wireSubs.delete(key)
+      }
       throw err
     }
   }
@@ -304,7 +306,11 @@ export abstract class WsProviderBase<TSub = unknown> implements WsProvider {
     try {
       const teardown = await opening
       const current = this.channels.get(key)
-      if (current === undefined || current.listeners.size === 0) {
+      if (current !== entry) {
+        teardown()
+        return
+      }
+      if (current.listeners.size === 0) {
         // Every listener released while opening — unwind immediately.
         teardown()
         this.channels.delete(key)
@@ -315,7 +321,9 @@ export abstract class WsProviderBase<TSub = unknown> implements WsProvider {
     } catch (err) {
       // Open failed: drop the channel so all (concurrent) subscribers reject
       // cleanly and a later subscribe re-opens.
-      this.channels.delete(key)
+      if (this.channels.get(key) === entry) {
+        this.channels.delete(key)
+      }
       throw err
     }
   }