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

package/src/agent/types.ts

@@ -1,24 +0,0 @@
-import type { Address, Hex } from '@lifi/perps-types'
-
-/**
- * Agent keypair for signing trading actions.
- */
-export interface Agent {
-  /** Agent wallet address */
-  address: Address
-  /** Agent private key */
-  privateKey: Hex
-}
-
-/**
- * Storage adapter interface for persisting agent keys.
- * Implement this interface to use custom storage (e.g., encrypted storage, database).
- */
-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/client/projectAccountConfigSettings.ts

@@ -1,39 +0,0 @@
-import type {
-  AccountConfig,
-  AccountConfigSetting,
-  ProviderOption,
-  ProviderSetup,
-} from '@lifi/perps-types'
-import { projectHyperliquidConfigSettings } from '../providers/hyperliquid/accountConfig.js'
-import { projectLighterConfigSettings } from '../providers/lighter/accountConfig.js'
-import { assertNever } from '../utils/assertNever.js'
-
-/**
- * Project a typed `AccountConfig` against the provider's `setup` + `options`
- * descriptors into `AccountConfigSetting[]`.
- *
- * Switches on `config.provider` to pick the per-provider mapper. The
- * `assertNever` exhaustiveness check in the `default` arm forces a compile
- * error whenever a new variant is added to `AccountConfig`.
- *
- * Produces exactly one `AccountConfigSetting` per descriptor in
- * `setup`-then-`options` order.
- *
- * @param config Typed account-state union (discriminated on `provider`).
- * @param setup  `Provider.setup` from the matching provider metadata.
- * @param options `Provider.options` from the matching provider metadata.
- */
-export function projectAccountConfigSettings(
-  config: AccountConfig,
-  setup: ProviderSetup[],
-  options: ProviderOption[]
-): AccountConfigSetting[] {
-  switch (config.provider) {
-    case 'hyperliquid':
-      return projectHyperliquidConfigSettings(config, setup, options)
-    case 'lighter':
-      return projectLighterConfigSettings(config, setup, options)
-    default:
-      return assertNever(config)
-  }
-}

package/src/client/types.ts

@@ -1,240 +0,0 @@
-import type {
-  AccountConfigSetting,
-  AccountResponse,
-  ActionStep,
-  Address,
-  AssetIdentity,
-  ExecuteActionResponse,
-  ModifyOrderInput,
-  OrderSide,
-  OrderType,
-  SignedActionStep,
-  TimeInForce,
-  TriggerOrderInput,
-  WithdrawalParams,
-} from '@lifi/perps-types'
-import type { StorageAdapter } from '../agent/types.js'
-import type {
-  LighterReadOnlyTokenManagerOptions,
-  LighterSignerConfig,
-} from '../signers/lighter/index.js'
-import type { ProviderConfigs } from './createPerpsClient.js'
-
-// Re-export the SDK client types from createPerpsClient
-export type {
-  HyperliquidConfig,
-  PerpsBaseConfig,
-  PerpsConfig,
-  PerpsSDKClient,
-  ProviderConfig,
-  ProviderConfigs,
-  RequestInterceptor,
-  SDKRequestOptions,
-} from './createPerpsClient.js'
-
-/**
- * Signing mode determines who signs trading actions.
- *
- * - `USER`: User wallet signs each action (requires wallet popup per action)
- * - `USER_AGENT`: SDK-generated agent signs actions (no popups after initial setup)
- */
-export enum SigningMode {
-  USER = 'USER',
-  USER_AGENT = 'USER_AGENT',
-}
-
-/**
- * Options for PerpsClient constructor.
- */
-export interface PerpsClientOptions {
-  /** Integrator identifier (required) */
-  integrator: string
-  /** API key for authenticated requests (get one at https://portal.li.fi/) */
-  apiKey: string
-  /** Base API URL. Defaults to DEFAULT_API_URL */
-  apiUrl?: string
-  /** Custom storage adapter for agent keys. Defaults to localStorage. */
-  storage?: StorageAdapter
-  /** Provider-specific configuration */
-  providers?: ProviderConfigs
-  /**
-   * Optional Lighter WASM signer configuration. Override the REST URL, chain
-   * ID, or WASM asset locations. Omit to accept defaults (mainnet, chain 304,
-   * WASM assets bundled with the package).
-   */
-  lighter?: LighterSignerConfig
-  /**
-   * Optional Lighter read-only token manager configuration. Override the
-   * Lighter REST URL, inject a custom HTTP fetcher, or pin a clock for
-   * tests. `storage` is shared with the rest of the client unless explicitly
-   * overridden here. Omit to accept the manager's defaults.
-   */
-  lighterReadOnlyToken?: LighterReadOnlyTokenManagerOptions
-}
-
-/**
- * Parameters for the internal `buildPrerequisites` helper that materialises
- * typed-data envelopes for the setup descriptors.
- */
-export interface CheckPrerequisitesParams {
-  /** Provider to build setup actions for */
-  provider: string
-  /** User wallet address */
-  address: Address
-  /** Address of the signer (auto-set in USER_AGENT mode) */
-  signerAddress?: Address
-}
-
-/**
- * Parameters for placing an order.
- */
-export interface PlaceOrderParams {
-  /** Provider to place order on */
-  provider: string
-  /** User wallet address */
-  address: Address
-  /** Asset identity */
-  asset: AssetIdentity
-  /** Order side */
-  side: OrderSide
-  /** Order type */
-  type: OrderType
-  /** Order size */
-  size: string
-  /** Order price */
-  price: string
-  /** Leverage */
-  leverage?: number
-  /** Reduce only flag */
-  reduceOnly?: boolean
-  /** Time in force */
-  timeInForce?: TimeInForce
-  /** Expiration time */
-  expiresAt?: string
-  /** Take profit trigger */
-  takeProfit?: TriggerOrderInput
-  /** Stop loss trigger */
-  stopLoss?: TriggerOrderInput
-}
-
-/**
- * Parameters for placing trigger-only orders (TP/SL on existing positions).
- * Sends a TRIGGER_ONLY order that skips the main order wire.
- */
-export interface PlaceTriggerOrderParams {
-  provider: string
-  address: Address
-  asset: AssetIdentity
-  side: OrderSide
-  takeProfit?: TriggerOrderInput
-  stopLoss?: TriggerOrderInput
-}
-
-/**
- * Parameters for withdrawing funds.
- */
-export interface WithdrawParams {
-  /** Provider to withdraw from */
-  provider: string
-  /** User wallet address (account owner) */
-  address: Address
-  /** Withdrawal details */
-  withdrawal: WithdrawalParams
-}
-
-/**
- * Parameters for canceling orders.
- */
-export interface CancelOrdersParams {
-  /** Provider to cancel orders on */
-  provider: string
-  /** User wallet address */
-  address: Address
-  /** Order IDs to cancel */
-  ids: string[]
-}
-
-/**
- * Parameters for modifying orders.
- */
-export interface ModifyOrdersParams {
-  /** Provider to modify orders on */
-  provider: string
-  /** User wallet address */
-  address: Address
-  /** Modifications to apply */
-  modifications: ModifyOrderInput[]
-}
-
-/**
- * Parameters for {@link PerpsClient.checkSetup}.
- */
-export interface GetSetupParams {
-  /** Provider to check setup for */
-  provider: string
-  /** User wallet address */
-  address: Address
-}
-
-/**
- * Result from {@link PerpsClient.checkSetup}.
- *
- * Reports the unsatisfied entries on `Provider.setup` for the queried
- * account, split by the signer role the descriptor declares.
- *
- * `Provider.options` items are NEVER included here — they don't gate trading
- * and are surfaced separately via `getAccount().settings`.
- */
-export interface SetupResult {
-  /** Setup steps requiring user wallet signature */
-  userPrerequisites: ActionStep[]
-  /** Setup steps the SDK auto-signs with the agent */
-  agentPrerequisites: ActionStep[]
-  /** Whether all setup items are already satisfied (ready to trade) */
-  isReady: boolean
-}
-
-/**
- * Parameters for {@link PerpsClient.satisfySetup}.
- */
-export interface SatisfySetupParams {
-  /** Provider to satisfy setup for */
-  provider: string
-  /** User wallet address */
-  address: Address
-  /** The result from checkSetup() */
-  required: SetupResult
-  /** User-signed actions corresponding to required.userPrerequisites */
-  userSignedActions: SignedActionStep[]
-}
-
-/**
- * Result from {@link PerpsClient.satisfySetup}.
- */
-export interface SatisfySetupResult {
-  /** Results from user-signed setup submission */
-  userResults: ExecuteActionResponse
-  /** Results from agent-signed setup submission (if any) */
-  agentResults?: ExecuteActionResponse
-  /**
-   * Fallback user-wallet setup steps surfaced when an agent-signed
-   * `ACCOUNT_MODE` dispatch is not authorised (e.g. Hyperliquid refuses to
-   * upgrade from a non-default abstraction variant without a user signature).
-   * Caller must re-sign these with the user's wallet.
-   */
-  fallbackUserPrerequisites?: ActionStep[]
-}
-
-/**
- * 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.
- */
-export interface GetAccountResult extends AccountResponse {
-  /** SDK-projected current state of every setup + options descriptor. */
-  settings: AccountConfigSetting[]
-}

package/src/providers/hyperliquid/accountConfig.ts

@@ -1,92 +0,0 @@
-import type {
-  AccountConfigSetting,
-  HyperliquidAccountConfig,
-  ProviderActionDescriptor,
-  ProviderOption,
-  ProviderSetup,
-} from '@lifi/perps-types'
-import { ActionType, PerpsErrorCode } from '@lifi/perps-types'
-import { PerpsError } from '../../errors/PerpsError.js'
-import { assertNever } from '../../utils/assertNever.js'
-
-/**
- * Project a single Hyperliquid descriptor against the typed
- * `HyperliquidAccountConfig` into an `AccountConfigSetting`.
- *
- * Mapping table:
- *
- * | descriptor.type          | projected values
- * |--------------------------|-----------------------------------------------
- * | APPROVE_AGENT            | []                  (no parameters)
- * | APPROVE_BUILDER_FEE      | []                  (no parameters)
- * | ACCOUNT_MODE             | [{ name: 'mode', value: config.abstractionMode }]
- *
- * The switch is exhaustive over `ActionType` so enum additions force a
- * compile error in the `default` arm. ActionTypes that are not valid on
- * `Provider.setup` / `Provider.options` throw at runtime.
- */
-function projectHyperliquidDescriptor(
-  descriptor: ProviderActionDescriptor,
-  config: HyperliquidAccountConfig
-): AccountConfigSetting {
-  switch (descriptor.type) {
-    // Zero-parameter user-approval descriptors. The "satisfied or not"
-    // state for these comes from `checkSetup`'s unsatisfied list, not from
-    // a projected value.
-    case ActionType.APPROVE_AGENT:
-    case ActionType.APPROVE_BUILDER_FEE:
-      return { type: descriptor.type, values: [] }
-
-    // `config.abstractionMode === null` means abstraction has never been set;
-    // callers fall back to the descriptor's `default` ParamOption.
-    case ActionType.ACCOUNT_MODE:
-      return {
-        type: descriptor.type,
-        values: [{ name: 'mode', value: config.abstractionMode }],
-      }
-
-    case ActionType.ACCOUNT_TYPE:
-    case ActionType.SEND_ASSET:
-    case ActionType.WITHDRAWAL:
-    case ActionType.TRANSFER:
-    case ActionType.PLACE_ORDER:
-    case ActionType.PLACE_TRIGGER_ORDER:
-    case ActionType.CANCEL_ORDER:
-    case ActionType.CANCEL_ALL_ORDERS:
-    case ActionType.MODIFY_ORDER:
-    case ActionType.UPDATE_LEVERAGE:
-    case ActionType.UPDATE_POSITION_MARGIN:
-    case ActionType.REGISTER_API_KEY:
-    case ActionType.APPROVE_READ_ONLY_TOKEN:
-    case ActionType.DEPOSIT:
-      throw new PerpsError(
-        PerpsErrorCode.SDKError,
-        `Hyperliquid account-config mapper has no projection for ` +
-          `descriptor type '${descriptor.type}' — this ActionType is not ` +
-          `valid on Provider.setup / Provider.options for Hyperliquid.`
-      )
-
-    default:
-      return assertNever(descriptor.type)
-  }
-}
-
-/**
- * Project the union of Hyperliquid setup + options descriptors against the
- * typed `HyperliquidAccountConfig`. Produces exactly one
- * `AccountConfigSetting` per descriptor, in `setup`-then-`options` order
- * (preserving the order in which the backend emits them).
- *
- * @param config Typed account state for the Hyperliquid account.
- * @param setup  `Provider.setup` array as emitted by `/providers`.
- * @param options `Provider.options` array as emitted by `/providers`.
- */
-export function projectHyperliquidConfigSettings(
-  config: HyperliquidAccountConfig,
-  setup: ProviderSetup[],
-  options: ProviderOption[]
-): AccountConfigSetting[] {
-  return [...setup, ...options].map((descriptor) =>
-    projectHyperliquidDescriptor(descriptor, config)
-  )
-}

package/src/providers/lighter/accountConfig.ts

@@ -1,103 +0,0 @@
-import type {
-  AccountConfigSetting,
-  LighterAccountConfig,
-  ProviderActionDescriptor,
-  ProviderOption,
-  ProviderSetup,
-} from '@lifi/perps-types'
-import { ActionType, PerpsErrorCode } from '@lifi/perps-types'
-import { PerpsError } from '../../errors/PerpsError.js'
-import { assertNever } from '../../utils/assertNever.js'
-
-/**
- * Project a single Lighter descriptor against the typed
- * `LighterAccountConfig` into an `AccountConfigSetting`.
- *
- * Mapping table:
- *
- * | descriptor.type           | projected values
- * |---------------------------|--------------------------------------------------
- * | REGISTER_API_KEY          | []                  (no parameters)
- * | APPROVE_READ_ONLY_TOKEN   | []                  (no parameters)
- * | ACCOUNT_MODE              | [{ name: 'mode', value: null }]  (Lighter has no
- * |                           |  abstraction-mode equivalent; read-only here)
- * | ACCOUNT_TYPE              | [{ name: 'tier', value: config.accountType }]
- *
- * The switch is exhaustive over `ActionType` so enum additions force a
- * compile error in the `default` arm. ActionTypes that are not valid on
- * `Provider.setup` / `Provider.options` throw at runtime.
- */
-function projectLighterDescriptor(
-  descriptor: ProviderActionDescriptor,
-  config: LighterAccountConfig
-): AccountConfigSetting {
-  switch (descriptor.type) {
-    // Zero-parameter user-approval descriptors. The "satisfied or not"
-    // state comes from `checkSetup`'s unsatisfied list and the
-    // `config.apiKeyRegistered` / `config.readOnlyTokenApproved` flags,
-    // not from a projected value.
-    case ActionType.REGISTER_API_KEY:
-    case ActionType.APPROVE_READ_ONLY_TOKEN:
-      return { type: descriptor.type, values: [] }
-
-    // Lighter exposes no abstraction-mode equivalent; if a backend descriptor
-    // surfaces ACCOUNT_MODE on Lighter it always projects `null` and callers
-    // fall back to the descriptor's `default` ParamOption.
-    case ActionType.ACCOUNT_MODE:
-      return {
-        type: descriptor.type,
-        values: [{ name: 'mode', value: null }],
-      }
-
-    // `tier` maps to the raw integer `config.accountType` Lighter publishes;
-    // decoding to a human label is the caller's responsibility.
-    case ActionType.ACCOUNT_TYPE:
-      return {
-        type: descriptor.type,
-        values: [{ name: 'tier', value: config.accountType }],
-      }
-
-    case ActionType.APPROVE_AGENT:
-    case ActionType.APPROVE_BUILDER_FEE:
-    case ActionType.SEND_ASSET:
-    case ActionType.WITHDRAWAL:
-    case ActionType.TRANSFER:
-    case ActionType.PLACE_ORDER:
-    case ActionType.PLACE_TRIGGER_ORDER:
-    case ActionType.CANCEL_ORDER:
-    case ActionType.CANCEL_ALL_ORDERS:
-    case ActionType.MODIFY_ORDER:
-    case ActionType.UPDATE_LEVERAGE:
-    case ActionType.UPDATE_POSITION_MARGIN:
-    case ActionType.DEPOSIT:
-      throw new PerpsError(
-        PerpsErrorCode.SDKError,
-        `Lighter account-config mapper has no projection for ` +
-          `descriptor type '${descriptor.type}' — this ActionType is not ` +
-          `valid on Provider.setup / Provider.options for Lighter.`
-      )
-
-    default:
-      return assertNever(descriptor.type)
-  }
-}
-
-/**
- * Project the union of Lighter setup + options descriptors against the typed
- * `LighterAccountConfig`. Produces exactly one `AccountConfigSetting` per
- * descriptor, in `setup`-then-`options` order (preserving the order in which
- * the backend emits them).
- *
- * @param config Typed account state for the Lighter account.
- * @param setup  `Provider.setup` array as emitted by `/providers`.
- * @param options `Provider.options` array as emitted by `/providers`.
- */
-export function projectLighterConfigSettings(
-  config: LighterAccountConfig,
-  setup: ProviderSetup[],
-  options: ProviderOption[]
-): AccountConfigSetting[] {
-  return [...setup, ...options].map((descriptor) =>
-    projectLighterDescriptor(descriptor, config)
-  )
-}

package/src/realtime/PerpsWsClient.ts

@@ -1,108 +0,0 @@
-import type { Subscription } from '@lifi/perps-types'
-import type { PerpsSDKClient } from '../client/createPerpsClient.js'
-import { getProviders } from '../services/getProviders.js'
-import { HyperliquidWsProvider } from './hyperliquid/HyperliquidWsProvider.js'
-import {
-  type LighterAuthProvider,
-  LighterWsProvider,
-} from './lighter/LighterWsProvider.js'
-import type {
-  EventForSubscription,
-  SubscriptionListener,
-  WsProvider,
-} from './types.js'
-
-export interface PerpsWsClientOptions {
-  /**
-   * Async function that mints a Lighter auth token for an L1 address. When
-   * provided, authenticated Lighter channels (orderUpdates, positions) will
-   * use the returned token. The provider is invoked on each subscribe send,
-   * including reconnects, so callers can transparently rotate tokens.
-   */
-  lighterAuthProvider?: LighterAuthProvider
-}
-
-export class PerpsWsClient {
-  private readonly client: PerpsSDKClient
-  private readonly options: PerpsWsClientOptions
-  private providers = new Map<string, WsProvider>()
-  private initPromises = new Map<string, Promise<WsProvider>>()
-
-  constructor(client: PerpsSDKClient, options: PerpsWsClientOptions = {}) {
-    this.client = client
-    this.options = options
-  }
-
-  async subscribe<S extends Subscription>(
-    sub: S,
-    listener: (event: EventForSubscription<S>) => void
-  ): Promise<() => void> {
-    const providerKey = sub.dex
-    const provider = await this.getOrCreateProvider(providerKey)
-    return provider.subscribe(sub, listener as SubscriptionListener)
-  }
-
-  close() {
-    for (const p of this.providers.values()) {
-      p.close()
-    }
-    this.providers.clear()
-    this.initPromises.clear()
-  }
-
-  private async getOrCreateProvider(provider: string): Promise<WsProvider> {
-    const existing = this.providers.get(provider)
-    if (existing) {
-      return existing
-    }
-
-    let initPromise = this.initPromises.get(provider)
-    if (!initPromise) {
-      initPromise = this.initProvider(provider)
-      this.initPromises.set(provider, initPromise)
-    }
-    return initPromise
-  }
-
-  private async initProvider(provider: string): Promise<WsProvider> {
-    const { providers } = await getProviders(this.client)
-
-    const providerInfo = providers.find((d) => d.key === provider)
-    if (!providerInfo?.wsUrl) {
-      throw new Error(`No WebSocket URL found for provider: ${provider}`)
-    }
-
-    const allMarkets = (providerInfo.markets ?? []) as Array<{
-      id: string
-    }>
-    const providerConfig = this.client.config.providers?.[provider]
-    const configuredMarkets = providerConfig?.markets
-    const filteredMarkets = configuredMarkets
-      ? allMarkets.filter((m) => configuredMarkets.includes(m.id))
-      : allMarkets
-    const subProviders = filteredMarkets
-      .map((m) => m.id)
-      .filter((id) => id !== provider && id !== 'spot')
-
-    const wsProvider = this.createWsProvider(
-      provider,
-      providerInfo.wsUrl,
-      subProviders
-    )
-    this.providers.set(provider, wsProvider)
-    return wsProvider
-  }
-
-  private createWsProvider(
-    provider: string,
-    wsUrl: string,
-    subProviders: string[]
-  ): WsProvider {
-    if (provider === 'lighter') {
-      return new LighterWsProvider(wsUrl, provider, {
-        authProvider: this.options.lighterAuthProvider,
-      })
-    }
-    return new HyperliquidWsProvider(wsUrl, provider, subProviders)
-  }
-}