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

package/src/services/resolveQuote.ts

@@ -0,0 +1,122 @@
+import {
+  type FeeTier,
+  type Market,
+  type MarketPrice,
+  PerpsErrorCode,
+  type Quote,
+} from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type {
+  PerpsSDKClient,
+  ProviderGetQuoteParams,
+} from '../types/provider.js'
+import { buildQuote } from '../utils/calculations.js'
+import { getMarkets } from './getMarkets.js'
+import { getOrderbook } from './getOrderbook.js'
+import { getPrices } from './getPrices.js'
+
+/**
+ * Shared provider-side `getQuote` implementation: resolve `params.symbol` to a
+ * market on `provider` (matching `baseAsset.displaySymbol`, scoped by
+ * `params.type`), fetch the orderbook snapshot, and build the {@link Quote}
+ * with the provider's public base `feeTier`. Both venue plugins delegate here
+ * so symbol resolution and the book walk live in one place; each plugin only
+ * supplies its own base tier.
+ *
+ * @throws {PerpsError} `MarketNotFound` when no market matches symbol+type.
+ * @internal
+ */
+export async function resolveQuote(
+  client: PerpsSDKClient,
+  provider: string,
+  params: ProviderGetQuoteParams,
+  feeTier: FeeTier,
+  options?: SDKRequestOptions
+): Promise<Quote> {
+  const market = await resolveQuoteMarket(client, provider, params, options)
+
+  const [{ bids, asks }, price] = await Promise.all([
+    getOrderbook(client, { provider, marketId: market.id }, options),
+    resolveQuotePrice(client, provider, market.id, options),
+  ])
+
+  return buildQuote({
+    provider,
+    symbol: params.symbol,
+    type: params.type,
+    side: params.side,
+    sizeUsd: params.size,
+    market,
+    price,
+    bids,
+    asks,
+    feeTier,
+    timestamp: Date.now(),
+  })
+}
+
+/**
+ * Resolve `params.symbol` to a market on `provider` (matching
+ * `baseAsset.displaySymbol`, scoped by `params.type`). Shared by the one-shot
+ * {@link resolveQuote} and the streaming quote subscription so both quote the
+ * same market for a given symbol+type.
+ *
+ * @throws {PerpsError} `MarketNotFound` when no market matches symbol+type.
+ * @internal
+ */
+export async function resolveQuoteMarket(
+  client: PerpsSDKClient,
+  provider: string,
+  params: Pick<ProviderGetQuoteParams, 'symbol' | 'type'>,
+  options?: SDKRequestOptions
+): Promise<Market> {
+  const { markets } = await getMarkets(client, { provider }, options)
+  const market = markets.find(
+    (m) =>
+      m.baseAsset.displaySymbol === params.symbol &&
+      isMarketOfType(m, params.type)
+  )
+  if (market === undefined) {
+    throw new PerpsError(
+      PerpsErrorCode.MarketNotFound,
+      `No ${params.type} market found on '${provider}' for symbol '${params.symbol}'.`
+    )
+  }
+  return market
+}
+
+const isMarketOfType = (
+  market: Market,
+  type: ProviderGetQuoteParams['type']
+): boolean => ('maxLeverage' in market ? type === 'perps' : type === 'spot')
+
+/**
+ * Fetch the live {@link MarketPrice} for `marketId` on `provider`, the source
+ * of the `markPrice` and `funding` a {@link Quote} carries. Shared by the
+ * one-shot {@link resolveQuote} and the streaming quote subscription.
+ *
+ * @throws {PerpsError} `ServerError` when the provider returns no price for the
+ * market.
+ * @internal
+ */
+export async function resolveQuotePrice(
+  client: PerpsSDKClient,
+  provider: string,
+  marketId: string,
+  options?: SDKRequestOptions
+): Promise<MarketPrice> {
+  const { prices } = await getPrices(
+    client,
+    { provider, marketIds: [marketId] },
+    options
+  )
+  const price = prices.find((p) => p.marketId === marketId)
+  if (price === undefined) {
+    throw new PerpsError(
+      PerpsErrorCode.ServerError,
+      `No price returned by '${provider}' for marketId '${marketId}'.`
+    )
+  }
+  return price
+}

package/src/services/resolveSubscribeQuote.ts

@@ -0,0 +1,109 @@
+import type { FeeTier, OrderbookResponse } from '@lifi/perps-types'
+import type {
+  PerpsSDKClient,
+  ProviderGetQuoteParams,
+  QuoteListener,
+} from '../types/provider.js'
+import { buildQuote } from '../utils/calculations.js'
+import type { WsProvider } from '../websocket/types.js'
+import { resolveQuoteMarket, resolveQuotePrice } from './resolveQuote.js'
+
+/**
+ * Minimum gap between successive streamed {@link Quote} emissions — the same
+ * 100 ms pacing applied to streamed orderbook rendering, so a quote ticks no
+ * faster than the book it derives from.
+ *
+ * @public
+ */
+export const QUOTE_THROTTLE_MS = 100
+
+/**
+ * Shared provider-side `subscribeQuote` implementation: resolve
+ * `params.symbol` to a market on `provider` (via {@link resolveQuoteMarket}),
+ * subscribe to that market's orderbook channel on `ws`, and on each book
+ * update rebuild the {@link Quote} with the provider's public base `feeTier` —
+ * the same transform the one-shot `resolveQuote` applies to a REST snapshot.
+ * Emissions are throttled to {@link QUOTE_THROTTLE_MS}: the first book update
+ * emits immediately, then at most one (trailing, latest-book) emission per
+ * interval. Both venue WS plugins delegate here; each only supplies its own
+ * base tier.
+ *
+ * The returned unsubscribe is idempotent — it releases the underlying
+ * orderbook listener once and cancels any pending trailing emission, so the
+ * wire subscription's ref count cannot be double-decremented.
+ *
+ * @throws {PerpsError} `MarketNotFound` when no market matches symbol+type.
+ * @internal
+ */
+export async function resolveSubscribeQuote(
+  client: PerpsSDKClient,
+  provider: string,
+  ws: Pick<WsProvider, 'subscribe'>,
+  params: ProviderGetQuoteParams,
+  feeTier: FeeTier,
+  onQuote: QuoteListener
+): Promise<() => void> {
+  const market = await resolveQuoteMarket(client, provider, params)
+  const price = await resolveQuotePrice(client, provider, market.id)
+
+  let latestBook: OrderbookResponse | undefined
+  let lastEmitAt = Number.NEGATIVE_INFINITY
+  let trailing: ReturnType<typeof setTimeout> | undefined
+
+  const emit = () => {
+    if (latestBook === undefined) {
+      return
+    }
+    lastEmitAt = Date.now()
+    onQuote(
+      buildQuote({
+        provider,
+        symbol: params.symbol,
+        type: params.type,
+        side: params.side,
+        sizeUsd: params.size,
+        market,
+        price,
+        bids: latestBook.bids,
+        asks: latestBook.asks,
+        feeTier,
+        timestamp: Date.now(),
+      })
+    )
+  }
+
+  const unsubscribe = await ws.subscribe(
+    { channel: 'orderbook', dex: provider, marketId: market.id },
+    (event) => {
+      if (event.channel !== 'orderbook') {
+        return
+      }
+      latestBook = event.data
+      if (trailing !== undefined) {
+        return
+      }
+      const wait = QUOTE_THROTTLE_MS - (Date.now() - lastEmitAt)
+      if (wait <= 0) {
+        emit()
+      } else {
+        trailing = setTimeout(() => {
+          trailing = undefined
+          emit()
+        }, wait)
+      }
+    }
+  )
+
+  let released = false
+  return () => {
+    if (released) {
+      return
+    }
+    released = true
+    if (trailing !== undefined) {
+      clearTimeout(trailing)
+      trailing = undefined
+    }
+    unsubscribe()
+  }
+}

package/src/storage/parseStoredRecord.ts

@@ -0,0 +1,55 @@
+import type { StorageAdapter } from './types.js'
+
+/**
+ * Parse a persisted (browser-writable) JSON record and validate it against a
+ * caller-supplied shape guard. localStorage is user-writable, so a stored value
+ * may be truncated, hand-edited, or written by an older schema; `JSON.parse(...)
+ * as T` would type-check such a record yet carry missing/invalid fields that
+ * fail far from here.
+ *
+ * Returns the parsed value when `isValid` accepts it; returns `null` when the
+ * record is absent, unparseable, or fails validation (i.e. poisoned). A `null`
+ * result is the "malformed-or-absent" signal — callers decide whether that
+ * means "regenerate deliberately" or "surface an error", but they never get a
+ * structurally-invalid `T`.
+ *
+ * @param raw Stored string, or `null` when the key is absent.
+ * @param isValid Shape guard run against the parsed value.
+ */
+export function parseStoredRecord<T>(
+  raw: string | null,
+  isValid: (value: unknown) => value is T
+): T | null {
+  if (raw === null) {
+    return null
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return null
+  }
+  return isValid(parsed) ? parsed : null
+}
+
+/**
+ * Read and validate a persisted record in one step, evicting the key when the
+ * stored value is present but poisoned (unparseable or failing `isValid`) so a
+ * later read does not keep tripping over the same corrupt entry.
+ *
+ * Returns `null` for both the genuine-absence and the evicted-poison cases;
+ * callers that must distinguish them should compare against the pre-read
+ * presence of the key themselves.
+ */
+export async function readValidatedRecord<T>(
+  storage: StorageAdapter,
+  key: string,
+  isValid: (value: unknown) => value is T
+): Promise<T | null> {
+  const raw = await storage.get(key)
+  const parsed = parseStoredRecord(raw, isValid)
+  if (parsed === null && raw !== null) {
+    await storage.remove(key)
+  }
+  return parsed
+}

package/src/{agent → storage}/storage.ts

@@ -1,16 +1,16 @@
 import type { StorageAdapter } from './types.js'
 
 /**
- * localStorage adapter for browser environments.
- * Agent keys are stored as JSON strings with the key pattern:
- * `lifi-perps-agent:{address}:{provider}`
+ * localStorage adapter for browser environments. Falls back to a no-op when
+ * `localStorage` is unavailable (e.g. SSR).
+ *
+ * @public
  */
 export const localStorageAdapter: StorageAdapter = {
   get: (key: string): Promise<string | null> => {
     try {
       return Promise.resolve(localStorage.getItem(key))
     } catch {
-      // localStorage not available (e.g., SSR)
       return Promise.resolve(null)
     }
   },
@@ -36,6 +36,8 @@ export const localStorageAdapter: StorageAdapter = {
 
 /**
  * In-memory storage adapter for testing or server-side use.
+ *
+ * @public
  */
 export function createMemoryStorage(): StorageAdapter {
   const store = new Map<string, string>()

package/src/storage/types.ts

@@ -0,0 +1,13 @@
+/**
+ * Storage adapter interface for persisting SDK session credentials (provider
+ * agent keypairs, API keys, read-only tokens). Implement this to use custom
+ * storage (e.g. encrypted storage, a database, async key-value stores).
+ */
+export interface StorageAdapter {
+  /** Get a value by key. */
+  get(key: string): Promise<string | null>
+  /** Set a value by key. */
+  set(key: string, value: string): Promise<void>
+  /** Remove a value by key. */
+  remove(key: string): Promise<void>
+}

package/src/transport/fetchWithRetry.ts

@@ -0,0 +1,116 @@
+import { sleep } from '../utils/sleep.js'
+import type { ResolvedRetryPolicy, RetryClassification } from './retryPolicy.js'
+
+/**
+ * Options for {@link fetchWithRetry}.
+ *
+ * @public
+ */
+export interface FetchWithRetryOptions {
+  policy: ResolvedRetryPolicy
+  fetchImpl?: typeof fetch
+  signal?: AbortSignal
+}
+
+/**
+ * Wrap `fetch` with policy-driven retry. Honors `Retry-After` (when present
+ * and `respectRetryAfter` is true), otherwise falls back to exponential
+ * backoff with full jitter, capped by `maxDelayMs`. Network errors (thrown
+ * `fetch` rejections) are treated as `retry-network` — same retry budget as
+ * 5xx. An aborted signal short-circuits without further attempts.
+ *
+ * @public
+ */
+export async function fetchWithRetry(
+  input: RequestInfo | URL,
+  init: RequestInit | undefined,
+  options: FetchWithRetryOptions
+): Promise<Response> {
+  const { policy, fetchImpl = fetch, signal } = options
+  const mergedInit: RequestInit = signal ? { ...init, signal } : (init ?? {})
+
+  let attempt = 0
+  while (true) {
+    if (signal?.aborted) {
+      throw signal.reason ?? new DOMException('Aborted', 'AbortError')
+    }
+
+    let response: Response | undefined
+    let networkError: unknown
+    try {
+      response = await fetchImpl(input, mergedInit)
+    } catch (error) {
+      networkError = error
+    }
+
+    if (response?.ok) {
+      return response
+    }
+
+    const classification: RetryClassification = response
+      ? policy.classify({ response })
+      : 'retry-network'
+
+    const attemptsRemaining = policy.maxAttempts - attempt - 1
+    const isRetriable = classification !== 'fail' && attemptsRemaining > 0
+
+    if (!isRetriable) {
+      if (response) {
+        return response
+      }
+      throw networkError
+    }
+
+    if (policy.shouldRetry) {
+      const ok = await policy.shouldRetry({
+        attempt,
+        response,
+        error: networkError,
+        classification,
+      })
+      if (!ok) {
+        if (response) {
+          return response
+        }
+        throw networkError
+      }
+    }
+
+    const delayMs = computeDelay(policy, attempt, response)
+    if (delayMs > 0) {
+      await sleep(delayMs)
+    }
+    attempt++
+  }
+}
+
+function computeDelay(
+  policy: ResolvedRetryPolicy,
+  attempt: number,
+  response: Response | undefined
+): number {
+  if (policy.respectRetryAfter && response) {
+    const header = response.headers.get('Retry-After')
+    if (header) {
+      const parsed = parseRetryAfter(header)
+      if (parsed !== undefined) {
+        return Math.min(parsed, policy.maxDelayMs)
+      }
+    }
+  }
+  const exp = policy.baseDelayMs * 2 ** attempt
+  const capped = Math.min(exp, policy.maxDelayMs)
+  return Math.floor(Math.random() * capped)
+}
+
+function parseRetryAfter(header: string): number | undefined {
+  const seconds = Number(header)
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return seconds * 1000
+  }
+  const dateMs = Date.parse(header)
+  if (!Number.isNaN(dateMs)) {
+    return Math.max(0, dateMs - Date.now())
+  }
+  return undefined
+}

package/src/{utils → transport}/request.ts

@@ -1,29 +1,31 @@
 import type { PerpsErrorBody } from '@lifi/perps-types'
 import { PerpsErrorCode } from '@lifi/perps-types'
-import type {
-  PerpsBaseConfig,
-  SDKRequestOptions,
-} from '../client/createPerpsClient.js'
 import { PerpsError } from '../errors/PerpsError.js'
+import type { PerpsBaseConfig, SDKRequestOptions } from '../types/config.js'
 import { version } from '../version.js'
-import { sleep } from './sleep.js'
+import { fetchWithRetry } from './fetchWithRetry.js'
+import {
+  LIFI_REQUEST_KEY,
+  LIFI_RETRY_DEFAULTS,
+  type RetryPolicy,
+  resolveRetryPolicy,
+} from './retryPolicy.js'
 
+/**
+ * `RequestInit` plus a per-call retry override.
+ *
+ * @internal
+ */
 export interface RequestOptions extends RequestInit {
-  /** Number of retries on 5xx errors. Default: 1 */
-  retries?: number
+  /** Per-call retry override. Falls back to the resolved client-level policy. */
+  retry?: RetryPolicy | false
 }
 
-const DEFAULT_RETRIES = 1
-
 /**
- * Make an HTTP request to the Perps API.
+ * Internal HTTP helper: applies SDK headers, retry policy, and the request
+ * interceptor, then normalizes failures into {@link PerpsError}.
  *
- * @param config - SDK configuration
- * @param url - The full URL to request
- * @param options - Fetch options plus retries
- * @param sdkOptions - SDK-specific options (signal, etc.)
- * @returns Parsed JSON response
- * @throws {PerpsError} On non-2xx responses or network errors
+ * @internal
  */
 export async function request<T>(
   config: PerpsBaseConfig,
@@ -31,57 +33,46 @@ export async function request<T>(
   options: RequestOptions = {},
   sdkOptions?: SDKRequestOptions
 ): Promise<T> {
-  const retries = options.retries ?? DEFAULT_RETRIES
+  const { retry, ...fetchInit } = options
+  const policy =
+    retry !== undefined
+      ? resolveRetryPolicy(LIFI_RETRY_DEFAULTS, retry, LIFI_REQUEST_KEY)
+      : resolveRetryPolicy(LIFI_RETRY_DEFAULTS, config.retry, LIFI_REQUEST_KEY)
 
   const headers: Record<string, string> = {
     'Content-Type': 'application/json',
     'x-lifi-integrator': config.integrator,
     'x-lifi-perps-sdk': version,
-    ...(options.headers as Record<string, string>),
+    ...(fetchInit.headers as Record<string, string>),
   }
 
   if (config.apiKey) {
     headers['x-lifi-api-key'] = config.apiKey
   }
 
-  if (sdkOptions?.lighterAuthToken) {
-    headers.Authorization = `Bearer ${sdkOptions.lighterAuthToken}`
-  }
-
-  // Merge signal from sdkOptions into options
   let finalOptions: RequestInit = {
-    ...options,
+    ...fetchInit,
     headers,
-    signal: sdkOptions?.signal ?? options.signal,
+    signal: sdkOptions?.signal ?? fetchInit.signal,
   }
 
-  // Apply request interceptor if configured
   if (config.requestInterceptor) {
     finalOptions = await config.requestInterceptor(url, finalOptions)
   }
 
   try {
-    const response = await fetch(url, finalOptions)
+    const response = await fetchWithRetry(url, finalOptions, {
+      policy,
+      fetchImpl: config.fetch,
+      signal: sdkOptions?.signal ?? finalOptions.signal ?? undefined,
+    })
 
     if (!response.ok) {
-      // Parse the backend's error body
       let body: PerpsErrorBody | undefined
       try {
         body = await response.json()
       } catch {}
 
-      // Retry on 5xx before throwing
-      if (retries > 0 && response.status >= 500) {
-        await sleep(500)
-        return request<T>(
-          config,
-          url,
-          { ...options, retries: retries - 1 },
-          sdkOptions
-        )
-      }
-
-      // Rehydrate backend error — code/message/tool come straight from the response
       const fallbackMessage = `Request failed with status code ${response.status}`
       if (
         body &&
@@ -103,7 +94,6 @@ export async function request<T>(
       throw error
     }
 
-    // Network error or other fetch failure
     throw new PerpsError(
       PerpsErrorCode.ServerError,
       error instanceof Error ? error.message : 'Request failed'
@@ -112,11 +102,9 @@ export async function request<T>(
 }
 
 /**
- * Build a URL with query parameters.
+ * Build a URL with a query string from defined params (skips `undefined`).
  *
- * @param baseUrl - The base URL
- * @param params - Query parameters (undefined values are filtered out)
- * @returns Full URL with query string
+ * @internal
  */
 export function buildUrl(
   baseUrl: string,