@lifi/perps-sdk 0.1.1-alpha.9 → 1.0.0

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}:{dex}`
+ * 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/transport/request.ts

@@ -0,0 +1,123 @@
+import type { PerpsErrorBody } from '@lifi/perps-types'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
+import type { PerpsBaseConfig, SDKRequestOptions } from '../types/config.js'
+import { version } from '../version.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 {
+  /** Per-call retry override. Falls back to the resolved client-level policy. */
+  retry?: RetryPolicy | false
+}
+
+/**
+ * Internal HTTP helper: applies SDK headers, retry policy, and the request
+ * interceptor, then normalizes failures into {@link PerpsError}.
+ *
+ * @internal
+ */
+export async function request<T>(
+  config: PerpsBaseConfig,
+  url: string,
+  options: RequestOptions = {},
+  sdkOptions?: SDKRequestOptions
+): Promise<T> {
+  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,
+    ...(fetchInit.headers as Record<string, string>),
+  }
+
+  if (config.apiKey) {
+    headers['x-lifi-api-key'] = config.apiKey
+  }
+
+  let finalOptions: RequestInit = {
+    ...fetchInit,
+    headers,
+    signal: sdkOptions?.signal ?? fetchInit.signal,
+  }
+
+  if (config.requestInterceptor) {
+    finalOptions = await config.requestInterceptor(url, finalOptions)
+  }
+
+  try {
+    const response = await fetchWithRetry(url, finalOptions, {
+      policy,
+      fetchImpl: config.fetch,
+      signal: sdkOptions?.signal ?? finalOptions.signal ?? undefined,
+    })
+
+    if (!response.ok) {
+      let body: PerpsErrorBody | undefined
+      try {
+        body = await response.json()
+      } catch {}
+
+      const fallbackMessage = `Request failed with status code ${response.status}`
+      if (
+        body &&
+        typeof body.code === 'number' &&
+        typeof body.message === 'string'
+      ) {
+        const error = new PerpsError(body.code, body.message)
+        error.tool = body.tool ?? 'unknown'
+        throw error
+      }
+      const error = new PerpsError(PerpsErrorCode.DefaultError, fallbackMessage)
+      error.tool = 'unknown'
+      throw error
+    }
+
+    return (await response.json()) as T
+  } catch (error) {
+    if (error instanceof PerpsError) {
+      throw error
+    }
+
+    throw new PerpsError(
+      PerpsErrorCode.ServerError,
+      error instanceof Error ? error.message : 'Request failed'
+    )
+  }
+}
+
+/**
+ * Build a URL with a query string from defined params (skips `undefined`).
+ *
+ * @internal
+ */
+export function buildUrl(
+  baseUrl: string,
+  params: Record<string, string | number | boolean | undefined>
+): string {
+  const searchParams = new URLSearchParams()
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined) {
+      searchParams.set(key, String(value))
+    }
+  }
+
+  const queryString = searchParams.toString()
+  return queryString ? `${baseUrl}?${queryString}` : baseUrl
+}

package/src/transport/retryPolicy.ts

@@ -0,0 +1,202 @@
+/**
+ * Provider key for LI.FI-backend-proxied requests in a
+ * {@link ProviderRetryConfig}.
+ *
+ * @public
+ */
+export const LIFI_REQUEST_KEY = 'lifi' as const
+
+/**
+ * Outcome of classifying a response/error for retry: the three `retry-*`
+ * variants are retriable; `'fail'` is terminal.
+ *
+ * @public
+ */
+export type RetryClassification =
+  | 'retry-rate-limit'
+  | 'retry-server'
+  | 'retry-network'
+  | 'fail'
+
+/**
+ * Context passed to a {@link RetryPolicy.classify} callback.
+ *
+ * @public
+ */
+export interface RetryClassifyContext {
+  response: Response
+}
+
+/**
+ * Context passed to a {@link RetryPolicy.shouldRetry} callback for each
+ * attempt.
+ *
+ * @public
+ */
+export interface RetryAttemptContext {
+  attempt: number
+  response?: Response
+  error?: unknown
+  classification: RetryClassification
+}
+
+/**
+ * User-supplied retry tuning. All fields optional — anything left unset
+ * inherits the built-in default for the target provider. `classify` returning
+ * `undefined` defers to the base classifier; returning `'fail'` short-circuits
+ * retry. `shouldRetry` runs after `classify` has already decided to retry and
+ * gives a final yes/no per attempt.
+ *
+ * @public
+ */
+export interface RetryPolicy {
+  maxAttempts?: number
+  baseDelayMs?: number
+  maxDelayMs?: number
+  respectRetryAfter?: boolean
+  classify?: (ctx: RetryClassifyContext) => RetryClassification | undefined
+  shouldRetry?: (ctx: RetryAttemptContext) => boolean | Promise<boolean>
+}
+
+/**
+ * A fully resolved retry policy with every field populated — the form
+ * {@link fetchWithRetry} consumes.
+ *
+ * @public
+ */
+export interface ResolvedRetryPolicy {
+  enabled: boolean
+  maxAttempts: number
+  baseDelayMs: number
+  maxDelayMs: number
+  respectRetryAfter: boolean
+  classify: (ctx: RetryClassifyContext) => RetryClassification
+  shouldRetry?: (ctx: RetryAttemptContext) => boolean | Promise<boolean>
+}
+
+/**
+ * Per-provider overrides keyed by the provider plugin's `type` (e.g. `'hyperliquid'`,
+ * `'lighter'`), plus `'lifi'` for backend-proxied requests. `default` is the
+ * fallback applied to any provider not explicitly listed.
+ *
+ * @public
+ */
+export interface ProviderRetryConfig {
+  default?: RetryPolicy | false
+  [providerKey: string]: RetryPolicy | false | undefined
+}
+
+/**
+ * Top-level `retry` option: a flat {@link RetryPolicy} for all providers,
+ * `false` to disable retries, or a per-provider {@link ProviderRetryConfig}.
+ *
+ * @public
+ */
+export type RetryConfig = RetryPolicy | false | ProviderRetryConfig
+
+/**
+ * Built-in default retry policy for LI.FI-backend requests.
+ *
+ * @public
+ */
+export const LIFI_RETRY_DEFAULTS: ResolvedRetryPolicy = {
+  enabled: true,
+  maxAttempts: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 5_000,
+  respectRetryAfter: true,
+  classify: ({ response }) => {
+    if (response.status === 429) {
+      return 'retry-rate-limit'
+    }
+    if (response.status >= 500 && response.status <= 599) {
+      return 'retry-server'
+    }
+    return 'fail'
+  },
+}
+
+/**
+ * A resolved policy that performs a single attempt with no retries.
+ *
+ * @public
+ */
+export const DISABLED_RETRY: ResolvedRetryPolicy = {
+  enabled: false,
+  maxAttempts: 1,
+  baseDelayMs: 0,
+  maxDelayMs: 0,
+  respectRetryAfter: false,
+  classify: () => 'fail',
+}
+
+function isProviderRetryConfig(
+  input: RetryPolicy | ProviderRetryConfig
+): input is ProviderRetryConfig {
+  if (
+    'maxAttempts' in input ||
+    'baseDelayMs' in input ||
+    'maxDelayMs' in input ||
+    'respectRetryAfter' in input ||
+    'classify' in input ||
+    'shouldRetry' in input
+  ) {
+    return false
+  }
+  return true
+}
+
+function mergePolicy(
+  base: ResolvedRetryPolicy,
+  override: RetryPolicy | false | undefined
+): ResolvedRetryPolicy {
+  if (override === false) {
+    return DISABLED_RETRY
+  }
+  if (!override) {
+    return base
+  }
+  return {
+    enabled: true,
+    maxAttempts: override.maxAttempts ?? base.maxAttempts,
+    baseDelayMs: override.baseDelayMs ?? base.baseDelayMs,
+    maxDelayMs: override.maxDelayMs ?? base.maxDelayMs,
+    respectRetryAfter: override.respectRetryAfter ?? base.respectRetryAfter,
+    classify: override.classify
+      ? (ctx) => override.classify?.(ctx) ?? base.classify(ctx)
+      : base.classify,
+    shouldRetry: override.shouldRetry ?? base.shouldRetry,
+  }
+}
+
+/**
+ * Merge a user-supplied {@link RetryConfig} onto a provider's built-in default.
+ * Resolution order when `config` is a {@link ProviderRetryConfig}:
+ * `config[providerKey]` → `config.default` → `base`. A flat {@link RetryPolicy}
+ * applies to every provider. `false` (at any level) disables retries entirely.
+ *
+ * @public
+ */
+export function resolveRetryPolicy(
+  base: ResolvedRetryPolicy,
+  config: RetryConfig | undefined,
+  providerKey: string
+): ResolvedRetryPolicy {
+  if (config === undefined) {
+    return base
+  }
+  if (config === false) {
+    return DISABLED_RETRY
+  }
+  if (isProviderRetryConfig(config)) {
+    const perProvider = config[providerKey]
+    if (perProvider !== undefined) {
+      return mergePolicy(base, perProvider)
+    }
+    if (config.default !== undefined) {
+      return mergePolicy(base, config.default)
+    }
+    return base
+  }
+  return mergePolicy(base, config)
+}