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

package/src/client/bindProvider.ts

@@ -0,0 +1,24 @@
+import type {
+  PerpsProvider,
+  PerpsProviderPlugin,
+  PerpsSDKClient,
+} from '../types/provider.js'
+
+/**
+ * Inject `client` into a {@link PerpsProviderPlugin} once via its
+ * {@link PerpsProviderPlugin.bind} hook, returning the runtime
+ * {@link PerpsProvider} — the plugin with its one-shot `bind` member dropped so
+ * consumers cannot re-bind a live provider. The read methods are already
+ * clientless (`getX(params, options?)`); they resolve their runtime deps from
+ * the context the plugin captured during `bind`.
+ *
+ * @internal
+ */
+export function bindProvider(
+  plugin: PerpsProviderPlugin,
+  client: PerpsSDKClient
+): PerpsProvider {
+  plugin.bind(client)
+  const { bind: _bind, ...provider } = plugin
+  return provider
+}

package/src/client/createPerpsClient.ts

@@ -1,102 +1,49 @@
 import { PerpsErrorCode } from '@lifi/perps-types'
-import { AgentManager } from '../agent/AgentManager.js'
-import type { StorageAdapter } from '../agent/types.js'
-import { PerpsErrorName } from '../errors/constants.js'
 import { PerpsError } from '../errors/PerpsError.js'
-
-export const DEFAULT_API_URL = 'https://develop.li.quest/v1/perps'
-
-/**
- * Configuration options for creating a Perps SDK client.
- */
-export interface PerpsConfig {
-  /** Integrator identifier (required) */
-  integrator: string
-  /** Optional API key for authenticated requests */
-  apiKey?: string
-  /** Base API URL. Defaults to DEFAULT_API_URL */
-  apiUrl?: string
-  /** Disable version update check in development mode */
-  disableVersionCheck?: boolean
-  /** Custom storage adapter for agent keys. Defaults to localStorage. */
-  storage?: StorageAdapter
-  /** Optional request interceptor for custom handling */
-  requestInterceptor?: RequestInterceptor
-}
-
-/**
- * Resolved configuration with required fields.
- */
-export interface PerpsBaseConfig {
-  /** Integrator identifier (required) */
-  integrator: string
-  /** Optional API key for authenticated requests */
-  apiKey?: string
-  /** Resolved API URL (always set) */
-  apiUrl: string
-  /** Disable version update check in development mode */
-  disableVersionCheck?: boolean
-  /** Optional request interceptor for custom handling */
-  requestInterceptor?: RequestInterceptor
-}
-
-/**
- * Request interceptor function type.
- * Called before each request is made, allowing modification of fetch options.
- */
-export type RequestInterceptor = (
-  url: string,
-  options: RequestInit
-) => RequestInit | Promise<RequestInit>
-
-/**
- * Options passed to service functions for request control.
- */
-export interface SDKRequestOptions {
-  /** AbortSignal to cancel the request */
-  signal?: AbortSignal
-}
+import type { PerpsConfig } from '../types/api.js'
+import type { PerpsBaseConfig, ProviderConfigs } from '../types/config.js'
+import type {
+  PerpsProvider,
+  PerpsProviderPlugin,
+  PerpsSDKClient,
+} from '../types/provider.js'
+import { bindProvider } from './bindProvider.js'
 
 /**
- * The Perps SDK client instance.
- * Holds configuration and agent manager for making API requests.
+ * Default LI.FI perps API base URL used when `PerpsConfig.apiUrl` is omitted.
+ *
+ * @public
  */
-export interface PerpsSDKClient {
-  /** SDK configuration */
-  readonly config: PerpsBaseConfig
-  /** Agent manager for USER_AGENT signing mode */
-  readonly agentManager: AgentManager
-}
+export const DEFAULT_API_URL = 'https://develop.li.quest/v1/perps'
 
 /**
- * Create a new Perps SDK client.
- *
- * @param options - Configuration options
- * @returns A new SDK client instance
- * @throws {PerpsError} If integrator is not provided
+ * Construct the low-level {@link PerpsSDKClient} — config, the optional
+ * end-user wallet, and provider registry — shared by the service functions and
+ * the higher-level {@link PerpsClient}.
  *
+ * @throws {PerpsError} When `options.integrator` is missing.
  * @example
  * ```ts
  * const client = createPerpsClient({
  *   integrator: 'my-app',
- *   apiKey: 'optional-api-key',
+ *   apiKey: 'key',
+ *   providers: [hyperliquidProvider()],
  * })
- *
- * // Use with service functions
- * const { dexes } = await getDexes(client)
  * ```
+ * @public
  */
 export function createPerpsClient(options: PerpsConfig): PerpsSDKClient {
   if (!options.integrator) {
     const error = new PerpsError(
-      PerpsErrorCode.ValidationError,
+      PerpsErrorCode.SDKError,
       'Integrator is required. Please see documentation at https://docs.li.fi'
     )
-    error.name = PerpsErrorName.ValidationError
+    error.tool = '@lifi/perps-sdk'
     throw error
   }
 
   const apiUrl = options.apiUrl ?? DEFAULT_API_URL
+  const { providerPlugins, providerConfigs } = splitProviders(options.providers)
 
   const config: PerpsBaseConfig = {
     integrator: options.integrator,
@@ -104,16 +51,50 @@ export function createPerpsClient(options: PerpsConfig): PerpsSDKClient {
     apiUrl,
     disableVersionCheck: options.disableVersionCheck,
     requestInterceptor: options.requestInterceptor,
+    providers: providerConfigs,
+    retry: options.retry,
+    fetch: options.fetch,
   }
 
-  const agentManager = new AgentManager(options.storage)
-
-  return {
+  const client: PerpsSDKClient = {
     get config() {
       return config
     },
-    get agentManager() {
-      return agentManager
+    get userWallet() {
+      return options.userWallet
+    },
+    get providers() {
+      return boundProviders
+    },
+    getProvider(key: string): PerpsProvider | undefined {
+      return boundProviders.find((p) => p.type === key)
     },
   }
+
+  const boundProviders: PerpsProvider[] = providerPlugins.map((plugin) =>
+    bindProvider(plugin, client)
+  )
+
+  return client
+}
+
+/**
+ * Split the overloaded `providers` option into its two shapes — the
+ * plugin array used by {@link PerpsSDKClient.getProvider}, and the
+ * keyed `ProviderConfigs` consumed internally by `PerpsWsClient` for
+ * markets filtering.
+ */
+export function splitProviders(
+  input: PerpsProviderPlugin[] | ProviderConfigs | undefined
+): {
+  providerPlugins: PerpsProviderPlugin[]
+  providerConfigs?: ProviderConfigs
+} {
+  if (input === undefined) {
+    return { providerPlugins: [] }
+  }
+  if (Array.isArray(input)) {
+    return { providerPlugins: input }
+  }
+  return { providerPlugins: [], providerConfigs: input }
 }

package/src/client/requireProvider.ts

@@ -0,0 +1,29 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+import { PerpsError } from '../errors/PerpsError.js'
+import type { PerpsProvider, PerpsSDKClient } from '../types/provider.js'
+
+/**
+ * Resolve the registered bound {@link PerpsProvider} for `provider`, or throw.
+ * Account reads run direct-to-venue through the provider, so a missing one is a
+ * wiring error (the consumer must pass it to
+ * `createPerpsClient({ providers: [...] })`) rather than a runtime-recoverable
+ * state.
+ *
+ * @internal
+ */
+export function requireProvider(
+  client: PerpsSDKClient,
+  provider: string
+): PerpsProvider {
+  const plugin = client.getProvider(provider)
+  if (plugin === undefined) {
+    const error = new PerpsError(
+      PerpsErrorCode.SDKError,
+      `Provider plugin not registered: '${provider}'. Pass it to ` +
+        'createPerpsClient({ providers: [...] }).'
+    )
+    error.tool = '@lifi/perps-sdk'
+    throw error
+  }
+  return plugin
+}

package/src/errors/PerpsError.ts

@@ -1,34 +1,23 @@
 import { PerpsErrorCode } from '@lifi/perps-types'
-import { version } from '../version.js'
-import { PerpsErrorName } from './constants.js'
 
+/**
+ * Error thrown by every SDK code path — backend error responses, transport
+ * failures, and SDK-side validation alike. Carries a {@link PerpsErrorCode}
+ * for programmatic branching and an optional `tool` tag identifying the
+ * originating package.
+ *
+ * @public
+ */
 export class PerpsError extends Error {
   code: PerpsErrorCode
-  override name = PerpsErrorName.PerpsError
+  override name = 'PerpsError'
+  tool?: string
 
   constructor(
     code: PerpsErrorCode = PerpsErrorCode.DefaultError,
     message = 'Unknown error occurred'
   ) {
-    const errorMessage = `[${PerpsErrorName.PerpsError}] ${message}\nLI.FI Perps SDK version: ${version}`
-    super(errorMessage)
+    super(message)
     this.code = code
-    this.name = PerpsErrorName.PerpsError
-  }
-
-  static fromError(error: unknown, defaultCode?: PerpsErrorCode): PerpsError {
-    if (error instanceof PerpsError) {
-      return error
-    }
-    if (error instanceof Error) {
-      return new PerpsError(
-        defaultCode ?? PerpsErrorCode.DefaultError,
-        error.message
-      )
-    }
-    return new PerpsError(
-      defaultCode ?? PerpsErrorCode.DefaultError,
-      String(error)
-    )
   }
 }

package/src/errors/constants.ts

@@ -1,15 +1,10 @@
-export enum PerpsErrorName {
-  PerpsError = 'PerpsError',
-  HTTPError = 'HTTPError',
-  ValidationError = 'ValidationError',
-  ServerError = 'ServerError',
-  ConfigError = 'ConfigError',
-  AgentError = 'AgentError',
-}
-
+/**
+ * Canonical human-readable messages paired with SDK-originated
+ * {@link PerpsError}s.
+ *
+ * @public
+ */
 export enum PerpsErrorMessage {
-  UnknownError = 'Unknown error occurred.',
-  ConfigNotInitialized = 'SDK not configured. Call createPerpsConfig() first.',
-  AgentNotFound = 'Agent not found. Call setSigningMode() first.',
-  InvalidSigningMode = 'Invalid signing mode for this operation.',
+  AgentNotFound = 'Agent not found. Complete provider setup (APPROVE_AGENT) first.',
+  AgentStorageCorrupt = 'Stored agent keypair is malformed. Revoke and re-approve the agent (APPROVE_AGENT) to regenerate it.',
 }

package/src/index.ts

@@ -1,91 +1,215 @@
-// Client
+// biome-ignore-all lint/performance/noBarrelFile: package public entry point.
+// biome-ignore-all lint/performance/noReExportAll: package public entry point.
+
+/**
+ * `@lifi/perps-sdk` — the public entry point. Exports `createPerpsClient` and
+ * `PerpsClient` (the primary API), the realtime `PerpsWsClient`, the pure
+ * calculation/parsing/order helpers, and re-exports the shared `@lifi/perps-types`.
+ *
+ * @packageDocumentation
+ * @public
+ */
 
-// Types
 export * from '@lifi/perps-types'
-// Agent
-export { AgentManager } from './agent/AgentManager.js'
-export { createMemoryStorage, localStorageAdapter } from './agent/storage.js'
-export type { Agent, StorageAdapter } from './agent/types.js'
-export type {
-  PerpsBaseConfig,
-  PerpsConfig,
-  PerpsSDKClient,
-  RequestInterceptor,
-  SDKRequestOptions,
-} from './client/createPerpsClient.js'
 export {
   createPerpsClient,
   DEFAULT_API_URL,
 } from './client/createPerpsClient.js'
 export { PerpsClient } from './client/PerpsClient.js'
-export type {
-  BuildAuthorizationParams,
-  BuildWithdrawalParams,
-  CancelOrdersParams,
-  ExecuteAuthorizationsParams,
-  ExecuteAuthorizationsResult,
-  GetRequiredAuthorizationsParams,
-  PerpsClientOptions,
-  PlaceOrderParams,
-  RequiredAuthorizationsResult,
-  SigningMode,
-} from './client/types.js'
-// Dex
-export { getDexAuthProvider } from './dex/registry.js'
-export type { DexAuthInputs, DexAuthProvider } from './dex/types.js'
-export { AgentError } from './errors/AgentError.js'
-export { PerpsErrorMessage, PerpsErrorName } from './errors/constants.js'
-// Errors
-export { HTTPError } from './errors/HTTPError.js'
+export { PerpsErrorMessage } from './errors/constants.js'
 export { PerpsError } from './errors/PerpsError.js'
-export { PerpsSDKError } from './errors/PerpsSDKError.js'
-export { ServerError } from './errors/ServerError.js'
+// Registries
+export { AssetRegistry, getAssetRegistry } from './registry/assetRegistry.js'
 export {
-  findErrorType,
-  getErrorChain,
-  getRootCause,
-  getRootCauseMessage,
-  hasErrorType,
-} from './errors/utils/rootCause.js'
-export { ValidationError } from './errors/ValidationError.js'
-// Realtime
-export { PerpsWsClient } from './realtime/PerpsWsClient.js'
-export type { EventForSubscription } from './realtime/types.js'
-export type { CancelOrderParams } from './services/cancelOrder.js'
+  getMarketRegistry,
+  MarketRegistry,
+  toMarketDisplay,
+} from './registry/marketRegistry.js'
 // Services
-export { cancelOrder } from './services/cancelOrder.js'
-export type { CreateAuthorizationParams } from './services/createAuthorization.js'
-export { createAuthorization } from './services/createAuthorization.js'
-export type { CreateOrderParams } from './services/createOrder.js'
-export { createOrder } from './services/createOrder.js'
-export type { CreateWithdrawalParams } from './services/createWithdrawal.js'
-export { createWithdrawal } from './services/createWithdrawal.js'
+export type { CreateActionParams } from './services/createAction.js'
+export { createAction } from './services/createAction.js'
+export type { ExecuteActionParams } from './services/executeAction.js'
+export { executeAction } from './services/executeAction.js'
 export type { GetAccountParams } from './services/getAccount.js'
 export { getAccount } from './services/getAccount.js'
-export { getDexes } from './services/getDexes.js'
-export type { GetHistoryParams } from './services/getHistory.js'
-export { getHistory } from './services/getHistory.js'
+export type { GetActivityParams } from './services/getActivity.js'
+export { getActivity } from './services/getActivity.js'
+export type { GetAssetsParams } from './services/getAssets.js'
+export { getAssets } from './services/getAssets.js'
+export type { GetFillsParams } from './services/getFills.js'
+export { getFills } from './services/getFills.js'
 export type { GetMarketParams } from './services/getMarket.js'
 export { getMarket } from './services/getMarket.js'
 export type { GetMarketsParams } from './services/getMarkets.js'
 export { getMarkets } from './services/getMarkets.js'
+export { getMeta } from './services/getMeta.js'
 export type { GetOhlcvParams } from './services/getOhlcv.js'
 export { getOhlcv } from './services/getOhlcv.js'
 export type { GetOrderParams } from './services/getOrder.js'
 export { getOrder } from './services/getOrder.js'
 export type { GetOrderbookParams } from './services/getOrderbook.js'
 export { getOrderbook } from './services/getOrderbook.js'
+export type { GetOrdersParams } from './services/getOrders.js'
+export { getOrders } from './services/getOrders.js'
+export type { GetPositionsParams } from './services/getPositions.js'
+export { getPositions } from './services/getPositions.js'
 export type { GetPricesParams } from './services/getPrices.js'
 export { getPrices } from './services/getPrices.js'
-export type { SubmitAuthorizationParams } from './services/submitAuthorization.js'
-export { submitAuthorization } from './services/submitAuthorization.js'
-export type { SubmitOrderParams } from './services/submitOrder.js'
-export { submitOrder } from './services/submitOrder.js'
-export type { SubmitWithdrawalParams } from './services/submitWithdrawal.js'
-export { submitWithdrawal } from './services/submitWithdrawal.js'
-
-// Utils
-export { signTypedData } from './utils/signTypedData.js'
-
+export { getProviders } from './services/getProviders.js'
+export type { GetQuoteParams } from './services/getQuote.js'
+export { getQuote } from './services/getQuote.js'
+export { getTermsAcceptance } from './services/getTermsAcceptance.js'
+export { resolveQuote, resolveQuoteMarket } from './services/resolveQuote.js'
+export {
+  QUOTE_THROTTLE_MS,
+  resolveSubscribeQuote,
+} from './services/resolveSubscribeQuote.js'
+export {
+  parseStoredRecord,
+  readValidatedRecord,
+} from './storage/parseStoredRecord.js'
+export { createMemoryStorage, localStorageAdapter } from './storage/storage.js'
+export type { StorageAdapter } from './storage/types.js'
+export type { FetchWithRetryOptions } from './transport/fetchWithRetry.js'
+export { fetchWithRetry } from './transport/fetchWithRetry.js'
+export type {
+  ProviderRetryConfig,
+  ResolvedRetryPolicy,
+  RetryAttemptContext,
+  RetryClassification,
+  RetryClassifyContext,
+  RetryConfig,
+  RetryPolicy,
+} from './transport/retryPolicy.js'
+export {
+  DISABLED_RETRY,
+  LIFI_REQUEST_KEY,
+  LIFI_RETRY_DEFAULTS,
+  resolveRetryPolicy,
+} from './transport/retryPolicy.js'
+export type {
+  BuildProviderSetupParams,
+  CancelOrdersParams,
+  ExecuteProviderSetupParams,
+  ExecuteProviderSetupResult,
+  GetAccountResult,
+  GetSetupParams,
+  ModifyOrdersParams,
+  PerpsClientOptions,
+  PerpsConfig,
+  PlaceOrderParams as ClientPlaceOrderParams,
+  PlaceTriggerOrderParams as ClientPlaceTriggerOrderParams,
+  ProviderSetup,
+} from './types/api.js'
+export type {
+  HyperliquidConfig,
+  PerpsBaseConfig,
+  PerpsClientSigner,
+  ProviderConfig,
+  ProviderConfigs,
+  RequestInterceptor,
+  SDKRequestOptions,
+} from './types/config.js'
+export type {
+  ActionSignerContribution,
+  LiquidationEstimateParams,
+  PerpsProvider,
+  PerpsProviderPlugin,
+  PerpsSDKClient,
+  ProviderGetAccountParams,
+  ProviderGetActivityParams,
+  ProviderGetFillsParams,
+  ProviderGetOrderParams,
+  ProviderGetOrdersParams,
+  ProviderGetPositionsParams,
+  ProviderGetQuoteParams,
+  QuoteListener,
+  SignActionsContext,
+} from './types/provider.js'
+export { summarizeAccount } from './utils/accountSummary.js'
+export type { ExpectedPnl } from './utils/calculations.js'
+export {
+  applySlippage,
+  buildQuote,
+  calculateExpectedPnl,
+  calculateNotionalValue,
+  calculatePositionSize,
+  calculateRealizedPnlPercent,
+  calculateRequiredMargin,
+  calculateRoe,
+  calculateUnrealizedPnl,
+  effectiveLeverage,
+  estimateFees,
+  liquidationDistancePercent,
+  percentFromPrice,
+  priceFromPercent,
+  removableMargin,
+  walkOrderbook,
+} from './utils/calculations.js'
+export type { DepositProviderKey } from './utils/depositChain.js'
+export {
+  LIFI_DEPOSIT_CHAIN_BY_PROVIDER,
+  lifiDepositChainForProvider,
+} from './utils/depositChain.js'
+export { ExplorerChainId, explorerTxUrl } from './utils/explorer.js'
+export { classifyFillFromPosition } from './utils/fillClassification.js'
+export type { FormatOptions } from './utils/format.js'
+export {
+  formatCompactUsd,
+  formatPrice,
+  formatSignedPercent,
+  formatSignedUsd,
+  formatUsd,
+} from './utils/format.js'
+export {
+  ACTIVE_ORDER_STATUSES,
+  classifyFill,
+  FillClassification,
+  isActiveOrderStatus,
+  isStopLossOrder,
+  isTakeProfitOrder,
+  isTpSlOrder,
+} from './utils/orderClassification.js'
+export {
+  expectedRealizedPnlForOpenOrder,
+  expectedRealizedPnlForTriggerOrder,
+  findMatchingPosition,
+  resolveCloseSize,
+} from './utils/orderMath.js'
+export { stringToFloat } from './utils/parse.js'
+export {
+  directionSign,
+  estimateIsolatedLiquidationPrice,
+  predictAverageEntryPrice,
+  predictNewLeverage,
+  predictUnrealizedPnl,
+  realizedPnlOnClose,
+} from './utils/positionMath.js'
+export {
+  signTypedData,
+  signTypedDataWithSigner,
+} from './utils/signTypedData.js'
+export { fromBaseUnits, fromBaseUnitsNumber } from './utils/units.js'
+export { validateMargin } from './utils/validation.js'
 // Version
 export { name, version } from './version.js'
+export { cachePromise } from './websocket/cachePromise.js'
+export type {
+  PerpsWsClientOptions,
+  WsProviderFactory,
+} from './websocket/PerpsWsClient.js'
+export { PerpsWsClient } from './websocket/PerpsWsClient.js'
+export type { ReconnectingWebSocketOptions } from './websocket/ReconnectingWebSocket.js'
+export { ReconnectingWebSocket } from './websocket/ReconnectingWebSocket.js'
+export type {
+  EventForSubscription,
+  SubscriptionListener,
+  WsConnectionStatus,
+  WsProvider,
+  WsStatusListener,
+} from './websocket/types.js'
+export {
+  WS_CHANNEL_TEARDOWN_LINGER_MS,
+  WsProviderBase,
+} from './websocket/WsProviderBase.js'
+export { wsLog } from './websocket/wsLog.js'

package/src/registry/assetRegistry.ts

@@ -0,0 +1,62 @@
+import type { Asset, AssetsResponse } from '@lifi/perps-types'
+import { buildUrl, request } from '../transport/request.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+import { ReferenceDataRegistry } from './referenceDataRegistry.js'
+
+/**
+ * Per-provider index over the backend's `/assets` token registry, keyed by
+ * `Asset.id` — the provider-native asset id (Lighter: the stringified
+ * `asset_id`, Hyperliquid spot: the venue token index). Obtain via
+ * {@link getAssetRegistry}.
+ *
+ * @public
+ */
+export class AssetRegistry extends ReferenceDataRegistry<Asset> {
+  constructor(client: PerpsSDKClient, provider: string) {
+    super(client, provider, 'asset')
+  }
+
+  /** The most recently synced asset list. Empty before the first {@link sync}. */
+  get assets(): readonly Asset[] {
+    return this.items
+  }
+
+  protected fetchItems(bypassHttpCache: boolean): Promise<Asset[]> {
+    const url = buildUrl(`${this.client.config.apiUrl}/assets`, {
+      provider: this.provider,
+    })
+    return request<AssetsResponse>(
+      this.client.config,
+      url,
+      bypassHttpCache ? { cache: 'no-cache' } : {}
+    ).then((response) => response.assets)
+  }
+
+  protected keyOf(asset: Asset): string {
+    return asset.id
+  }
+}
+
+const registries = new WeakMap<PerpsSDKClient, Map<string, AssetRegistry>>()
+
+/**
+ * The stable {@link AssetRegistry} for `(client, provider)`.
+ *
+ * @public
+ */
+export function getAssetRegistry(
+  client: PerpsSDKClient,
+  provider: string
+): AssetRegistry {
+  let byProvider = registries.get(client)
+  if (byProvider === undefined) {
+    byProvider = new Map()
+    registries.set(client, byProvider)
+  }
+  let registry = byProvider.get(provider)
+  if (registry === undefined) {
+    registry = new AssetRegistry(client, provider)
+    byProvider.set(provider, registry)
+  }
+  return registry
+}