@lifi/perps-sdk-provider-ondo 0.0.0-preview-7ff840c

package/src/types/wire.ts

@@ -0,0 +1,228 @@
+/**
+ * Ondo REST wire types (`Ondo*`), mirroring the Ondo Perps OpenAPI schemas.
+ * All numeric quantities arrive as strings; timestamps are ISO 8601 strings
+ * unless a field says otherwise.
+ */
+
+/** Cursor pair Ondo returns as a sibling of `result` on paginated endpoints. */
+export interface OndoPageInfo {
+  prevCursor?: string
+  nextCursor?: string
+}
+
+/** @public */
+export type OndoPositionDirection = 'long' | 'short' | 'neutral'
+
+/** Mirrors Ondo's `ApiPosition`. @public */
+export interface OndoPosition {
+  market: string
+  direction: OndoPositionDirection
+  /** Position size in base currency (unsigned magnitude). */
+  netQuantity: string
+  averageEntryPrice: string
+  usedMargin: string
+  unrealizedPnl: string
+  markPrice: string
+  liquidationPrice: string
+  bankruptcyPrice: string
+  maintenanceMargin: string
+  notionalValue: string
+  leverage: string
+  netFundingSinceNeutral: string
+  returnOnEquity: string
+  stopLossTriggerPrice?: string
+  takeProfitTriggerPrice?: string
+}
+
+/** @public */
+export type OndoOrderSide = 'buy' | 'sell'
+
+/** @public */
+export type OndoOrderStatus =
+  | 'open'
+  | 'fullyfilled'
+  | 'canceled'
+  | 'pending'
+  | 'untriggered'
+
+/** @public */
+export type OndoOrderType =
+  | 'limit'
+  | 'market'
+  | 'stopMarket'
+  | 'takeProfitMarket'
+
+/** @public */
+export type OndoTimeInForce = 'GTC' | 'IOC'
+
+/** @public */
+export type OndoStopOrderType = 'stopLoss' | 'takeProfit'
+
+/** Mirrors Ondo's `ApiOrder`. @public */
+export interface OndoOrder {
+  orderId: string
+  side: OndoOrderSide
+  price: string
+  size: string
+  market: string
+  filledSize: string
+  lastFillSize: string
+  filledCost: string
+  fee: string
+  status: OndoOrderStatus
+  createdAt: string
+  type: OndoOrderType
+  clientOrderId?: string
+  parentOrderId?: string
+  realizedPnl?: string
+  feeRebate?: string
+  filledAt?: string
+  canceledAt?: string
+  cancelReason?: string
+  /** Not returned for market orders. */
+  timeInForce?: OndoTimeInForce
+  reduceOnly?: boolean
+  liquidationId?: string
+  /** Position-level TP/SL flag. */
+  closePosition?: boolean
+  stopOrderType?: OndoStopOrderType
+  triggerPrice?: string
+}
+
+/** @public */
+export type OndoFillDirection =
+  | 'openLong'
+  | 'openShort'
+  | 'closeLong'
+  | 'closeShort'
+  | 'flipLongToShort'
+  | 'flipShortToLong'
+
+/** Mirrors Ondo's `ApiFill`. @public */
+export interface OndoFill {
+  id: string
+  orderId: string
+  market: string
+  price: string
+  size: string
+  side: OndoOrderSide
+  filledCost: string
+  fee: string
+  time: string
+  isMaker: boolean
+  clientOrderId?: string
+  parentOrderID?: string
+  direction?: OndoFillDirection
+  feeRebate?: string
+  pnl?: string
+  isADL?: boolean
+}
+
+/**
+ * Mirrors Ondo's `MarginAccountBalanceSummary`. Invariants per the docs:
+ * `marginBalance = walletBalance + unrealizedPnl`,
+ * `availableMargin = marginBalance − usedMargin`.
+ * @public
+ */
+export interface OndoBalanceSummary {
+  walletBalance: string
+  realizedPnl: string
+  unrealizedPnl: string
+  marginBalance: string
+  usedMargin: string
+  availableMargin: string
+  withdrawableMargin: string
+  maintenanceMarginRequirement: string
+  totalMaintenanceMargin: string
+  marginRatio: string
+  leverage: string
+  underLiquidation: boolean
+  totalFundingPayments: string
+  totalTradingFees: string
+  totalPnL: string
+}
+
+/**
+ * `GET /v1/account/referral` result: the referral applied to the account.
+ * The endpoint is absent from Ondo's published OpenAPI spec; shape mirrors the
+ * venue web app. `result` is `null` when no referral is applied.
+ * @public
+ */
+export interface OndoAccountReferral {
+  /** The referrer's code applied to this account. */
+  code: string
+  /** Rebate share of trading fees returned to the referred account. */
+  rebate?: number
+}
+
+/** Mirrors Ondo's `Contract` (perps contract ticker row). @public */
+export interface OndoContract {
+  market: string
+  productType: string
+  contractType: string
+  baseCurrency: string
+  quoteCurrency: string
+  disabled: boolean
+  displayName?: string
+  lastPrice?: string
+  indexPrice?: string
+  fundingRate?: string
+  nextFundingRate?: string
+  nextFundingRateTimestamp?: string
+  makerFee?: string
+  takerFee?: string
+  openInterest?: string
+  openInterestUsd?: string
+  priceChangePercent?: string
+  isClosed?: boolean
+}
+
+/** Mirrors Ondo's `FundingFeeTransfer`. Carries no id — callers synthesize one. @public */
+export interface OndoFundingFeeTransfer {
+  market: string
+  time: string
+  markPrice: string
+  positionSize: string
+  positionDirection: OndoPositionDirection
+  rate: string
+  /** Which side paid this interval. */
+  payer: OndoPositionDirection
+  /** Signed: positive = earned, negative = paid. */
+  amount: string
+}
+
+/** @public */
+export type OndoLiquidationStatus = 'queued' | 'start' | 'retry' | 'stop'
+
+/** Mirrors Ondo's `LiquidationEvent`. @public */
+export interface OndoLiquidationEvent {
+  id: string
+  time: string
+  initiatedAt: string
+  accountId: string
+  status: OndoLiquidationStatus
+  insuranceFundUsed: string
+  adl: boolean
+  retryCount: number
+  triggeringPositions?: OndoPosition[]
+  filledQuoteSize?: string
+  filledQuantity?: string
+  reclaimOrderMargin?: boolean
+}
+
+/** @public */
+export type OndoAccountState = 'open' | 'disabled' | 'offboarding' | 'closed'
+
+/** Mirrors Ondo's `AccountInfo` (the `/v1/account` result). @public */
+export interface OndoAccountInfo {
+  accountID: string
+  identifier: string
+  authType: string
+  accountState: OndoAccountState
+  withdrawalFeeUSD: string
+  termsVersion: number
+  termsUnixSecs: number
+  privacyVersion: number
+  privacyUnixSecs: number
+  marketingConsent: string
+}

package/src/types/ws.ts

@@ -0,0 +1,79 @@
+/**
+ * Ondo WebSocket wire types. Client ops are `{op, ...args}` envelopes (only
+ * `login` nests its arguments); server data frames are
+ * `{type: 'update', channel, data}`.
+ */
+
+import type { OndoFill, OndoOrder, OndoPosition } from './wire.js'
+
+/** Level tuple as streamed: `[price, size]`, both decimal strings. @public */
+export type OndoBookLevel = [string, string]
+
+/** Streamed order-book snapshot (`depthBooksPerps`/`topOfBooksPerps`). @public */
+export interface OndoBookSnapshot {
+  market: string
+  time: string
+  asks: OndoBookLevel[]
+  bids: OndoBookLevel[]
+  depthLevels?: string
+}
+
+/** Streamed public trade (`tradesPerps`). @public */
+export interface OndoWsTrade {
+  market: string
+  price: string
+  size: string
+  cost: string
+  aggressor_side: 'buy' | 'sell'
+  time: string
+  id: string
+}
+
+/**
+ * Streamed candlestick (`kLinePerps`). Prices and volume arrive as numbers,
+ * unlike the string-typed REST shapes; `s`/`e`/`t` are Unix seconds.
+ * @public
+ */
+export interface OndoKline {
+  m: string
+  t: number
+  s: number
+  e: number
+  o: number
+  h: number
+  l: number
+  c: number
+  v: number
+  x: boolean
+}
+
+/** Streamed mark price (`markPricesPerps`). @public */
+export interface OndoMarkPrice {
+  market: string
+  markPrice: string
+}
+
+/** Streamed funding rate (`fundingRatesPerps`). @public */
+export interface OndoFundingRate {
+  market: string
+  rate: string
+  intervalEnds: string
+  premiums?: unknown[]
+}
+
+/** Server frame envelope. Non-`update` types are acks or errors. @public */
+export type OndoWsMessage =
+  | { type: 'update'; channel: 'depthBooksPerps'; data: OndoBookSnapshot[] }
+  | { type: 'update'; channel: 'tradesPerps'; data: OndoWsTrade[] }
+  | { type: 'update'; channel: 'kLinePerps'; data: OndoKline }
+  | { type: 'update'; channel: 'markPricesPerps'; data: OndoMarkPrice[] }
+  | { type: 'update'; channel: 'fundingRatesPerps'; data: OndoFundingRate[] }
+  | { type: 'update'; channel: 'ordersPerps'; data: OndoOrder[] }
+  | { type: 'update'; channel: 'fillsPerps'; data: OndoFill[] }
+  | { type: 'update'; channel: 'positionsPerps'; data: OndoPosition[] }
+  | { type: 'update'; channel: string; data: unknown }
+  | { type: 'pong' }
+  | { type: 'loggedIn'; msg?: string }
+  | { type: 'subscribed'; channel?: string }
+  | { type: 'unsubscribed'; channel?: string }
+  | { type: 'error'; msg?: string }

package/src/utils/activityCursor.ts

@@ -0,0 +1,140 @@
+import { PerpsError } from '@lifi/perps-sdk'
+import { type ActivityItem, PerpsErrorCode } from '@lifi/perps-types'
+
+/**
+ * Per-endpoint cursor envelope for Ondo activity pagination.
+ *
+ * Each key holds the `pageInfo.nextCursor` returned by that endpoint on the
+ * previous call. When a key is **present** with a non-empty string the
+ * corresponding endpoint will be re-fetched at that cursor on the next call;
+ * when a key is **absent** the endpoint is treated as exhausted (or never
+ * paged because the type filter excluded it) and skipped.
+ *
+ * The envelope is round-tripped through `cursor` as base64url JSON so callers
+ * don't need to know the per-endpoint shape.
+ * @public
+ */
+export interface OndoActivityCursor {
+  fundings?: string
+  liquidations?: string
+  /**
+   * Already-fetched, merged-and-sorted rows that did not fit under the page
+   * `limit`. The upstream cursors above have advanced past these rows, so they
+   * are replayed (prepended) on the next page before any fresh fetch — without
+   * them the tail would be lost forever.
+   */
+  overflow?: ActivityItem[]
+}
+
+const CURSOR_KEYS = ['fundings', 'liquidations'] as const
+
+const isNonEmpty = (v: string | undefined): v is string =>
+  typeof v === 'string' && v.length > 0
+
+/**
+ * Encode an `OndoActivityCursor` as the base64url-of-JSON cursor string
+ * persisted between activity pages. Returns `undefined` when every
+ * per-endpoint key is empty and no `overflow` rows remain — the caller
+ * should report `hasMore: false` and omit `cursor` from `Pagination` then.
+ *
+ * Browser-direct: `Buffer` is Node-only. We use `btoa` over a Latin-1
+ * encoding of the UTF-8 bytes and then rewrite `+/=` to base64url. This is
+ * the same byte sequence Node's `Buffer.from(json, 'utf8').toString('base64url')`
+ * produces, so cursors round-trip across environments.
+ * @public
+ */
+export const encodeActivityCursor = (
+  env: OndoActivityCursor
+): string | undefined => {
+  const compact: OndoActivityCursor = {}
+  for (const key of CURSOR_KEYS) {
+    if (isNonEmpty(env[key])) {
+      compact[key] = env[key]
+    }
+  }
+  if (env.overflow !== undefined && env.overflow.length > 0) {
+    compact.overflow = env.overflow
+  }
+  if (Object.keys(compact).length === 0) {
+    return undefined
+  }
+  return toBase64Url(JSON.stringify(compact))
+}
+
+/**
+ * Decode a previously-encoded activity cursor. Returns `undefined` for an
+ * absent cursor (first page) and throws {@link PerpsError} with
+ * `ValidationError` if the string is malformed — we'd rather fail loudly than
+ * silently re-page from page 1 and re-deliver already-paginated rows.
+ * @public
+ */
+export const decodeActivityCursor = (
+  cursor: string | undefined
+): OndoActivityCursor | undefined => {
+  if (cursor === undefined) {
+    return undefined
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(fromBase64Url(cursor))
+  } catch {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      'Invalid Ondo activity cursor: not base64url-encoded JSON'
+    )
+  }
+  if (parsed === null || typeof parsed !== 'object') {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      'Invalid Ondo activity cursor: expected JSON object'
+    )
+  }
+  const cursorRecord = parsed as Record<string, unknown>
+  const env: OndoActivityCursor = {}
+  for (const key of CURSOR_KEYS) {
+    const v = cursorRecord[key]
+    if (v === undefined) {
+      continue
+    }
+    if (typeof v !== 'string') {
+      throw new PerpsError(
+        PerpsErrorCode.ValidationError,
+        `Invalid Ondo activity cursor: ${key} must be a string`
+      )
+    }
+    env[key] = v
+  }
+  const overflow = cursorRecord.overflow
+  if (overflow !== undefined) {
+    if (!Array.isArray(overflow)) {
+      throw new PerpsError(
+        PerpsErrorCode.ValidationError,
+        'Invalid Ondo activity cursor: overflow must be an array'
+      )
+    }
+    env.overflow = overflow as ActivityItem[]
+  }
+  return env
+}
+
+const toBase64Url = (s: string): string => {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(s, 'utf8').toString('base64url')
+  }
+  const utf8 = unescape(encodeURIComponent(s))
+  return btoa(utf8).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+const fromBase64Url = (s: string): string => {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(s, 'base64url').toString('utf8')
+  }
+  const padded = s.replace(/-/g, '+').replace(/_/g, '/') + padFor(s)
+  const decoded = atob(padded)
+  return decodeURIComponent(escape(decoded))
+}
+
+const padFor = (s: string): string => {
+  const rem = s.length % 4
+  return rem === 0 ? '' : '='.repeat(4 - rem)
+}

package/src/utils/apiClient.ts

@@ -0,0 +1,257 @@
+import {
+  DISABLED_RETRY,
+  fetchWithRetry,
+  PerpsError,
+  type ResolvedRetryPolicy,
+} from '@lifi/perps-sdk'
+import { PerpsErrorCode } from '@lifi/perps-types'
+import type { OndoGenericResponse } from '../types/auth.js'
+import type { OndoPageInfo } from '../types/wire.js'
+
+/** @internal */
+export type ApiParams = Record<string, string | number | boolean>
+
+/** One page of a paginated Ondo response: `pageInfo` is a SIBLING of `result`. @public */
+export interface OndoPage<T> {
+  result: T[]
+  pageInfo: OndoPageInfo | undefined
+}
+
+/** @internal */
+export type OndoHttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE'
+
+/**
+ * Ondo request failure — a non-2xx HTTP status, a `success: false` envelope,
+ * or a body that is not a `GenericResponse` envelope at all. `errorCode`
+ * carries the wire `error_code` when the envelope advertised one.
+ *
+ * @public
+ */
+export class OndoApiError extends PerpsError {
+  readonly errorCode: string | undefined
+
+  constructor(message: string, errorCode?: string) {
+    super(PerpsErrorCode.ThirdPartyError, message)
+    this.errorCode = errorCode
+  }
+}
+
+/**
+ * The Ondo session JWT was rejected (HTTP 401). Distinct from
+ * {@link OndoApiError} so callers can evict the stored token and re-run the
+ * SIWE login instead of surfacing a generic venue failure.
+ *
+ * @public
+ */
+export class OndoSessionExpiredError extends PerpsError {
+  constructor(message: string) {
+    super(PerpsErrorCode.Unauthorized, message)
+  }
+}
+
+/** @internal */
+export const ONDO_RETRY_DEFAULTS: ResolvedRetryPolicy = {
+  enabled: true,
+  maxAttempts: 2,
+  baseDelayMs: 1_000,
+  maxDelayMs: 30_000,
+  respectRetryAfter: true,
+  classify: ({ response }) => {
+    if (response.status === 429) {
+      return 'retry-rate-limit'
+    }
+    if (
+      response.status === 502 ||
+      response.status === 503 ||
+      response.status === 504
+    ) {
+      return 'retry-server'
+    }
+    return 'fail'
+  },
+}
+
+/** @internal */
+export interface OndoApiClientOptions {
+  signal?: AbortSignal
+  policy?: ResolvedRetryPolicy
+  fetchImpl?: typeof fetch
+}
+
+/** @internal */
+export interface OndoRequestOptions {
+  params?: ApiParams
+  /** Ondo session JWT, sent as `Authorization: Bearer <token>`. */
+  authToken?: string
+}
+
+const isGenericResponse = (
+  data: unknown
+): data is OndoGenericResponse<unknown> =>
+  typeof data === 'object' &&
+  data !== null &&
+  typeof (data as { success?: unknown }).success === 'boolean'
+
+/**
+ * HTTP boundary against Ondo's REST API.
+ *
+ * Browser-direct by design: the session JWT lives client-side only, so
+ * credentialed calls (`authToken` option) go straight to Ondo — never through
+ * the LI.FI backend. Every response is an `OndoGenericResponse` envelope; the
+ * client unwraps `result` on success and throws {@link OndoApiError} (carrying
+ * the wire `error_code`) otherwise. An HTTP 401 throws
+ * {@link OndoSessionExpiredError} so callers can re-run the SIWE login.
+ * @public
+ */
+export class OndoApiClient {
+  private readonly baseUrl: string
+  private readonly signal: AbortSignal | undefined
+  private readonly policy: ResolvedRetryPolicy
+  private readonly fetchImpl: typeof fetch | undefined
+
+  constructor(baseUrl: string, options?: OndoApiClientOptions) {
+    this.baseUrl = baseUrl.replace(/\/$/, '')
+    this.signal = options?.signal
+    this.policy = options?.policy ?? ONDO_RETRY_DEFAULTS
+    this.fetchImpl = options?.fetchImpl
+  }
+
+  async get<T>(path: string, options?: OndoRequestOptions): Promise<T> {
+    const { status, data } = await this.perform(path, {
+      method: 'GET',
+      params: options?.params,
+      authToken: options?.authToken,
+      policy: this.policy,
+    })
+    return this.unwrap<T>(path, status, data)
+  }
+
+  /**
+   * GET a paginated endpoint, preserving the `pageInfo` sibling that
+   * {@link get}'s envelope unwrap would otherwise drop.
+   */
+  async getPage<T>(
+    path: string,
+    options?: OndoRequestOptions
+  ): Promise<OndoPage<T>> {
+    const { status, data } = await this.perform(path, {
+      method: 'GET',
+      params: options?.params,
+      authToken: options?.authToken,
+      policy: this.policy,
+    })
+    const result = this.unwrap<T[] | null>(path, status, data)
+    const pageInfo = (data as { pageInfo?: OndoPageInfo }).pageInfo
+    return { result: result ?? [], pageInfo }
+  }
+
+  /**
+   * Arbitrary-method request with caller-prebuilt headers — the execution
+   * surface for credential-bearing `RestCallSignedActionStep`s, whose
+   * `Authorization` header is attached by `signActions` from the token store.
+   * Only GET is ever retried; writes are not idempotent.
+   */
+  async send<T>(
+    method: OndoHttpMethod,
+    path: string,
+    options?: { body?: unknown; headers?: Record<string, string> }
+  ): Promise<T> {
+    const { status, data } = await this.perform(path, {
+      method,
+      body: options?.body,
+      headers: options?.headers,
+      policy: method === 'GET' ? this.policy : DISABLED_RETRY,
+    })
+    return this.unwrap<T>(path, status, data)
+  }
+
+  /**
+   * POSTs are never auto-retried regardless of policy: Ondo writes (order
+   * placement, login completion) are not idempotent, and a retried request
+   * whose first attempt landed would double-submit.
+   */
+  async post<T>(
+    path: string,
+    body?: unknown,
+    options?: Pick<OndoRequestOptions, 'authToken'>
+  ): Promise<T> {
+    const { status, data } = await this.perform(path, {
+      method: 'POST',
+      body,
+      authToken: options?.authToken,
+      policy: DISABLED_RETRY,
+    })
+    return this.unwrap<T>(path, status, data)
+  }
+
+  private buildUrl(path: string, params?: ApiParams): string {
+    const url = `${this.baseUrl}${path}`
+    if (!params || Object.keys(params).length === 0) {
+      return url
+    }
+    const qs = Object.entries(params)
+      .map(
+        ([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`
+      )
+      .join('&')
+    return `${url}?${qs}`
+  }
+
+  private async perform(
+    path: string,
+    options: {
+      method: OndoHttpMethod
+      params?: ApiParams
+      body?: unknown
+      authToken?: string
+      headers?: Record<string, string>
+      policy: ResolvedRetryPolicy
+    }
+  ): Promise<{ status: number; data: unknown }> {
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      ...options.headers,
+    }
+    if (options.authToken) {
+      headers.Authorization = `Bearer ${options.authToken}`
+    }
+    const init: RequestInit = { method: options.method, headers }
+    if (options.method !== 'GET' && options.method !== 'DELETE') {
+      headers['Content-Type'] = 'application/json'
+      init.body = JSON.stringify(options.body ?? {})
+    }
+    const response = await fetchWithRetry(
+      this.buildUrl(path, options.params),
+      init,
+      { policy: options.policy, fetchImpl: this.fetchImpl, signal: this.signal }
+    )
+    const data: unknown = await response.json().catch(() => undefined)
+    return { status: response.status, data }
+  }
+
+  private unwrap<T>(path: string, status: number, data: unknown): T {
+    if (status === 401) {
+      throw new OndoSessionExpiredError(
+        `Ondo rejected the session token for ${path}`
+      )
+    }
+    if (status < 200 || status >= 300) {
+      throw new OndoApiError(
+        `Ondo API request failed: ${status} — ${JSON.stringify(data).slice(0, 200)}`,
+        isGenericResponse(data) ? data.error_code : undefined
+      )
+    }
+    if (!isGenericResponse(data)) {
+      throw new OndoApiError(
+        `Ondo API returned an unexpected body for ${path}: ${JSON.stringify(data).slice(0, 200)}`
+      )
+    }
+    if (!data.success) {
+      throw new OndoApiError(
+        `Ondo API error for ${path}: ${data.error_code ?? 'unknown'} — ${data.error ?? 'no error message'}`,
+        data.error_code
+      )
+    }
+    return data.result as T
+  }
+}