@lifi/perps-sdk 0.0.0-preview-e6f120b → 0.0.0-preview-d0c0a79

package/src/index.ts

@@ -104,6 +104,7 @@ export type {
   CancelOrdersParams,
   CancelTwapOrderParams as ClientCancelTwapOrderParams,
   CreateReferralCodeActionParams,
+  ExecuteMetaActionParams,
   GetAccountResult,
   GetDepositFlowParams,
   GetSetupParams,
@@ -116,6 +117,7 @@ export type {
   PlaceTwapOrderParams as ClientPlaceTwapOrderParams,
   ProviderSetup,
   SendAssetActionParams,
+  SetupChecklistItem,
   SubmitOnboardingParams,
   WithdrawParams,
 } from './types/api.js'

package/src/types/api.ts

@@ -3,15 +3,18 @@ import type {
   AccountResponse,
   CancelTwapOrderParams as ActionCancelTwapOrderParams,
   CreateReferralCodeParams as ActionCreateReferralCodeParams,
+  ActionParamsMap,
   PlaceTwapOrderParams as ActionPlaceTwapOrderParams,
   ActionStep,
   ExecuteActionResponse,
   MarginMode,
   MarketRef,
+  MetaActionType,
   ModifyOrderInput,
   OnboardParams,
   OrderSide,
   OrderType,
+  ProviderAction,
   SignedActionStep,
   TimeInForce,
   TriggerOrderInput,
@@ -34,12 +37,17 @@ import type { PerpsProviderPlugin } from './provider.js'
 export interface PerpsConfig {
   /**
    * Optional integrator assertion. Sent as `x-lifi-integrator` only when
-   * `apiKey` is also set. The backend resolves the fee identity from `apiKey`
-   * and rejects an integrator that disagrees with it.
+   * `apiKey` is also set. The backend rejects an integrator that disagrees
+   * with the key.
    */
   integrator?: string
-  /** LI.FI API key used for authenticated backend requests. */
-  apiKey: string
+  /**
+   * Optional LI.FI API key. The production host `https://li.quest/v1/perps`
+   * accepts anonymous requests, so a key is not required there. The
+   * `develop.li.quest` and `staging.li.quest` hosts require a key. Get one at
+   * https://portal.li.fi/.
+   */
+  apiKey?: string
   /** Perps API base URL; defaults to {@link DEFAULT_API_URL}. */
   apiUrl?: string
   /** Skip the SDK-version compatibility check when set. */
@@ -94,12 +102,17 @@ export interface PerpsConfig {
 export interface PerpsClientOptions {
   /**
    * Optional integrator assertion. Sent as `x-lifi-integrator` only when
-   * `apiKey` is also set. The backend resolves the fee identity from `apiKey`
-   * and rejects an integrator that disagrees with it.
+   * `apiKey` is also set. The backend rejects an integrator that disagrees
+   * with the key.
    */
   integrator?: string
-  /** API key for authenticated requests (get one at https://portal.li.fi/). */
-  apiKey: string
+  /**
+   * Optional LI.FI API key. The production host `https://li.quest/v1/perps`
+   * accepts anonymous requests, so a key is not required there. The
+   * `develop.li.quest` and `staging.li.quest` hosts require a key. Get one at
+   * https://portal.li.fi/.
+   */
+  apiKey?: string
   /** Perps API base URL; defaults to {@link DEFAULT_API_URL}. */
   apiUrl?: string
   /**
@@ -285,6 +298,19 @@ export interface GetWithdrawableBalancesParams {
   address: Address
 }
 
+/**
+ * One entry on {@link ProviderSetup.checklist}: a user-facing setup
+ * descriptor plus its satisfied state for the queried account.
+ *
+ * @public
+ */
+export interface SetupChecklistItem {
+  /** The `Provider.setup` descriptor for this step. */
+  descriptor: ProviderAction
+  /** Whether the step is already satisfied for this account. */
+  satisfied: boolean
+}
+
 /**
  * Result from {@link PerpsClient.checkSetup}.
  *
@@ -310,6 +336,15 @@ export interface ProviderSetup {
   setup: ActionStep[]
   /** Whether all setup items are already satisfied (ready to trade) */
   isReady: boolean
+  /**
+   * The renderable onboarding list: every USER-signed setup descriptor with
+   * its satisfied state, ordered by `sequence`. SDK-internal steps and
+   * conditional steps that staged no work for this account (see
+   * `PerpsProviderPlugin.conditionalSetupActions`) are omitted. Consumers
+   * render this list directly instead of joining `Provider.setup` metadata
+   * with the staged `setup` steps.
+   */
+  checklist: SetupChecklistItem[]
 }
 
 /**
@@ -365,3 +400,14 @@ export interface CreateReferralCodeActionParams
   extends ActionCreateReferralCodeParams {
   address: Address
 }
+
+/**
+ * Parameters for {@link PerpsClient.executeMetaAction}.
+ *
+ * @public
+ */
+export interface ExecuteMetaActionParams<T extends MetaActionType> {
+  address: Address
+  action: T
+  params: ActionParamsMap[T]
+}

package/src/types/config.ts

@@ -92,7 +92,12 @@ export interface PerpsBaseConfig {
    * transport sends it only when `apiKey` is also non-empty.
    */
   integrator?: string
-  /** API key applied to backend requests when non-empty. */
+  /**
+   * Resolved API key, or `''` when the client was built without one. The
+   * transport sends `x-lifi-api-key` only when it is non-empty. The production
+   * host `https://li.quest/v1/perps` accepts anonymous requests; the
+   * `develop.li.quest` and `staging.li.quest` hosts require a key.
+   */
   apiKey: string
   /** Resolved perps API base URL. */
   apiUrl: string

package/src/types/provider.ts

@@ -358,6 +358,16 @@ export interface PerpsProviderPlugin {
    */
   readonly internalSetupActions?: readonly ActionType[]
 
+  /**
+   * Setup actions that stage work only when the account needs remediation
+   * (e.g. Hyperliquid's REVOKE_AGENT frees an agent slot only when every
+   * named slot is taken). When such a step stages no actions,
+   * `PerpsClient.checkSetup` omits it from `ProviderSetup.checklist` instead
+   * of rendering it as satisfied. Omit when every setup step is
+   * unconditional.
+   */
+  readonly conditionalSetupActions?: readonly ActionType[]
+
   /**
    * Inject the runtime {@link PerpsSDKClient} into the plugin once, during
    * {@link createPerpsClient}. The plugin captures it (config, fetch, retry,

package/src/utils/setupActions.ts

@@ -8,9 +8,10 @@ import { PerpsSigner } from '@lifi/perps-types'
  * them inline, so surfacing them would render inert cards the user can't act on.
  *
  * Membership is a property of the descriptor's `signers` alone, independent of
- * any account: use this to build the onboarding list, then layer each entry's
- * satisfied/unsatisfied state on top from a live `checkSetup` so the tick never
- * goes stale.
+ * any account. When an account is available, prefer `ProviderSetup.checklist`
+ * from `checkSetup` for the onboarding list — it applies this filter, omits
+ * not-required conditional steps, and carries each entry's satisfied state.
+ * This function remains the static, account-free projection.
  *
  * @param setup The provider's `setup` descriptors, in their declared order.
  * @public

package/src/version.ts

@@ -10,4 +10,4 @@ export const name = '@lifi/perps-sdk'
  *
  * @public
  */
-export const version = '0.0.0-preview-e6f120b'
+export const version = '0.0.0-preview-d0c0a79'