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

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)
+}

package/src/types/api.ts

@@ -0,0 +1,239 @@
+import type {
+  AccountConfigSetting,
+  AccountResponse,
+  ActionStep,
+  ExecuteActionResponse,
+  MarketRef,
+  ModifyOrderInput,
+  OrderSide,
+  OrderType,
+  SignedActionStep,
+  TimeInForce,
+  TriggerOrderInput,
+  WithdrawalParams,
+} from '@lifi/perps-types'
+import type { Account, Address, WalletClient } from 'viem'
+import type { RetryConfig } from '../transport/retryPolicy.js'
+import type { ProviderConfigs, RequestInterceptor } from './config.js'
+import type { PerpsProviderPlugin } from './provider.js'
+
+/**
+ * Configuration for {@link createPerpsClient}.
+ *
+ * @public
+ */
+export interface PerpsConfig {
+  integrator: string
+  apiKey: string
+  apiUrl?: string
+  disableVersionCheck?: boolean
+  requestInterceptor?: RequestInterceptor
+  /**
+   * Provider plugins or per-provider config. Two shapes are accepted:
+   *
+   * - `PerpsProviderPlugin[]` — plugin objects implementing the read surface
+   *   for one DEX each. Bound to the client at construction and looked up at
+   *   runtime as bound {@link PerpsProvider}s via `client.getProvider(key)`.
+   *   Modelled on `@lifi/sdk`'s `providers: SDKProvider[]`.
+   * - `ProviderConfigs` — keyed config object (e.g.
+   *   `{ hyperliquid: { markets: [...] } }`). Used internally by
+   *   `PerpsWsClient` to filter which markets are subscribed to.
+   *
+   * Both may be supplied during the migration to provider packages;
+   * the array form is preferred for new code.
+   */
+  providers?: PerpsProviderPlugin[] | ProviderConfigs
+  /**
+   * The end-user's wallet, used whenever an action's descriptor names the user
+   * wallet in its `signers` list. Accepts any viem-compatible WalletClient:
+   *   - Browser wallet: wagmi's useWalletClient() result
+   *   - Private key:    createWalletClient({ account: privateKeyToAccount('0x...'), transport: http() })
+   *   - Mnemonic:       createWalletClient({ account: mnemonicToAccount('word1 ...'), transport: http() })
+   */
+  userWallet?: WalletClient<any, any, Account>
+  /**
+   * Retry behaviour for HTTP requests. Pass `false` to disable retries
+   * everywhere (single-shot — useful when wrapping with TanStack Query or
+   * similar consumer-side retry). Pass a flat {@link RetryPolicy} to apply
+   * one policy across providers, or a per-provider object keyed by provider
+   * type (`'lifi'`, `'hyperliquid'`, `'lighter'`) with an optional `default`
+   * fallback. Per-provider built-in defaults apply when omitted.
+   */
+  retry?: RetryConfig
+  /**
+   * Replace the global `fetch` used by the SDK and provider HTTP clients —
+   * for instrumentation, custom proxying, or test injection. Does not affect
+   * retry policy.
+   */
+  fetch?: typeof fetch
+}
+
+/**
+ * Options for PerpsClient constructor.
+ *
+ * @public
+ */
+export interface PerpsClientOptions {
+  integrator: string
+  /** API key for authenticated requests (get one at https://portal.li.fi/) */
+  apiKey: string
+  /** Defaults to DEFAULT_API_URL */
+  apiUrl?: string
+  /**
+   * Provider plugins or per-provider config. Accepts the same two shapes as
+   * {@link PerpsConfig.providers}: an array of `PerpsProviderPlugin` plugins or
+   * a keyed `ProviderConfigs` map.
+   */
+  providers?: PerpsProviderPlugin[] | ProviderConfigs
+}
+
+/**
+ * Parameters for the internal `buildProviderSetup` helper that materialises
+ * typed-data envelopes for the setup descriptors.
+ *
+ * @public
+ */
+export interface BuildProviderSetupParams {
+  provider: string
+  address: Address
+}
+
+/**
+ * Parameters for placing an order.
+ *
+ * @public
+ */
+export interface PlaceOrderParams {
+  provider: string
+  address: Address
+  market: MarketRef
+  side: OrderSide
+  type: OrderType
+  size: string
+  price: string
+  leverage?: number
+  reduceOnly?: boolean
+  timeInForce?: TimeInForce
+  expiresAt?: string
+  takeProfit?: TriggerOrderInput
+  stopLoss?: TriggerOrderInput
+}
+
+/**
+ * Parameters for placing trigger-only orders (TP/SL on existing positions).
+ * Sends a TRIGGER_ONLY order that skips the main order wire.
+ *
+ * @public
+ */
+export interface PlaceTriggerOrderParams {
+  provider: string
+  address: Address
+  market: MarketRef
+  side: OrderSide
+  takeProfit?: TriggerOrderInput
+  stopLoss?: TriggerOrderInput
+}
+
+/**
+ * Parameters for withdrawing funds.
+ *
+ * @public
+ */
+export interface WithdrawParams {
+  provider: string
+  address: Address
+  withdrawal: WithdrawalParams
+}
+
+/**
+ * Parameters for canceling orders.
+ *
+ * @public
+ */
+export interface CancelOrdersParams {
+  provider: string
+  address: Address
+  ids: string[]
+}
+
+/**
+ * Parameters for modifying orders.
+ *
+ * @public
+ */
+export interface ModifyOrdersParams {
+  provider: string
+  address: Address
+  modifications: ModifyOrderInput[]
+}
+
+/**
+ * Parameters for {@link PerpsClient.checkSetup}.
+ *
+ * @public
+ */
+export interface GetSetupParams {
+  provider: string
+  address: Address
+}
+
+/**
+ * Result from {@link PerpsClient.checkSetup}.
+ *
+ * Reports the unsatisfied entries on `Provider.setup` for the queried account
+ * as a flat list — each `ActionStep` is self-describing (its action keys back
+ * to the provider's `setup` descriptor, which declares the step's signer and
+ * scheme), so no signer-role partition is exposed here.
+ *
+ * `Provider.options` items are NEVER included here — they don't gate trading
+ * and are surfaced separately via `getAccount().settings`.
+ *
+ * @public
+ */
+export interface ProviderSetup {
+  /** Unsatisfied setup steps, ordered by descriptor `sequence`. */
+  setup: ActionStep[]
+  /** Whether all setup items are already satisfied (ready to trade) */
+  isReady: boolean
+}
+
+/**
+ * Parameters for {@link PerpsClient.executeProviderSetup}.
+ *
+ * @public
+ */
+export interface ExecuteProviderSetupParams {
+  /** Provider to satisfy setup for */
+  provider: string
+  /** User wallet address */
+  address: Address
+  /** The unsatisfied setup steps from checkSetup() */
+  setup: ActionStep[]
+  /** Signed counterparts of `setup`, in the same order */
+  signedActions: SignedActionStep[]
+}
+
+/**
+ * Result from {@link PerpsClient.executeProviderSetup}.
+ *
+ * @public
+ */
+export interface ExecuteProviderSetupResult {
+  results: ExecuteActionResponse
+}
+
+/**
+ * Result envelope returned by {@link PerpsClient.getAccount} — wraps the
+ * backend's `AccountResponse` with a single SDK-projected `settings` array.
+ *
+ * `settings` contains exactly one `AccountConfigSetting` per descriptor on
+ * `Provider.setup` + `Provider.options` (in that order). Index the
+ * projection by `setting.type === descriptor.type` and read
+ * `setting.values[i].value` for each `Param` the descriptor declared.
+ *
+ * @public
+ */
+export interface GetAccountResult extends AccountResponse {
+  /** SDK-projected current state of every setup + options descriptor. */
+  settings: AccountConfigSetting[]
+}

package/src/types/config.ts

@@ -0,0 +1,79 @@
+import type { Account, WalletClient } from 'viem'
+import type { RetryConfig } from '../transport/retryPolicy.js'
+
+/**
+ * Viem `WalletClient` shape used by `PerpsSDKClient.userWallet`. Aliased here
+ * so provider plugins can name the type without re-deriving the viem generics.
+ *
+ * @public
+ */
+export type PerpsClientSigner = WalletClient<any, any, Account>
+
+/**
+ * Per-provider config — restricts which `markets` the WS client subscribes
+ * to. Indexed by provider key.
+ *
+ * @public
+ */
+export interface ProviderConfig {
+  markets?: string[]
+}
+
+/**
+ * @deprecated Use {@link ProviderConfig}.
+ * @public
+ */
+export type HyperliquidConfig = ProviderConfig
+
+/**
+ * Map of per-provider {@link ProviderConfig}, keyed by provider key.
+ *
+ * @public
+ */
+export interface ProviderConfigs {
+  [provider: string]: ProviderConfig | undefined
+}
+
+/**
+ * Hook to rewrite each outgoing request's URL/`RequestInit` before it is sent.
+ *
+ * @public
+ */
+export type RequestInterceptor = (
+  url: string,
+  options: RequestInit
+) => RequestInit | Promise<RequestInit>
+
+/**
+ * Per-call request options threaded through the service functions.
+ *
+ * @public
+ */
+export interface SDKRequestOptions {
+  signal?: AbortSignal
+  /**
+   * Lighter auth token consumed by provider-direct venue reads (getOrders,
+   * getOrder, getActivity, getAccount). Create via
+   * `lighterSigner.createAuthToken(deadline, context)`. Sent only to Lighter
+   * venue endpoints, never to the LI.FI backend — read-only by design
+   * (8h max TTL, cannot authorize writes).
+   */
+  lighterAuthToken?: string
+}
+
+/**
+ * Immutable snapshot of the resolved client configuration after defaults
+ * are applied. Exposed via {@link PerpsSDKClient.config}.
+ *
+ * @public
+ */
+export interface PerpsBaseConfig {
+  integrator: string
+  apiKey: string
+  apiUrl: string
+  disableVersionCheck?: boolean
+  requestInterceptor?: RequestInterceptor
+  providers?: ProviderConfigs
+  retry?: RetryConfig
+  fetch?: typeof fetch
+}