@lifi/perps-sdk 10.0.2 → 10.1.0

package/src/services/getReferralStatus.ts

@@ -0,0 +1,57 @@
+import type { ReferralStatus } from '@lifi/perps-types'
+import type { Address } from 'viem'
+import { buildUrl, request } from '../transport/request.js'
+import type { SDKRequestOptions } from '../types/config.js'
+import type { PerpsSDKClient } from '../types/provider.js'
+
+/**
+ * Parameters for {@link getReferralStatus}.
+ *
+ * @public
+ */
+export interface GetReferralStatusParams {
+  address: Address
+  /**
+   * Candidate internal referral code to validate in the same read. The
+   * response carries the backend's verdict on `candidate`, and reflects the
+   * candidate in `onboarding.referralCode` when it is attachable.
+   */
+  code?: string
+}
+
+/**
+ * Get an address's onboarding and internal-referral state: terms acceptance,
+ * the code attached to it, the code it owns, whether it may create one, the
+ * verdict on a candidate code, and the one onboarding step it must sign next.
+ * Provider-independent — reads from the platform `meta` surface, not a venue
+ * plugin.
+ *
+ * An address the backend holds no record for resolves to a well-formed
+ * payload with `termsAccepted: false` and the optional state fields absent.
+ *
+ * @throws {PerpsError} On backend error responses, network, or parsing errors.
+ *
+ * @example
+ * ```ts
+ * const client = createPerpsClient({ apiKey: 'your-api-key' })
+ * const status = await getReferralStatus(client, {
+ *   address: '0x1234...',
+ *   code: 'ABC123',
+ * })
+ * if (status.onboarding) {
+ *   // one signature is outstanding; submit it via PerpsClient.submitOnboarding
+ * }
+ * ```
+ * @public
+ */
+export async function getReferralStatus(
+  client: PerpsSDKClient,
+  params: GetReferralStatusParams,
+  options?: SDKRequestOptions
+): Promise<ReferralStatus> {
+  const url = buildUrl(`${client.config.apiUrl}/meta/referral`, {
+    address: params.address,
+    code: params.code,
+  })
+  return request<ReferralStatus>(client.config, url, {}, options)
+}

package/src/types/api.ts

@@ -2,12 +2,16 @@ import type {
   AccountConfigSetting,
   AccountResponse,
   CancelTwapOrderParams as ActionCancelTwapOrderParams,
+  CreateReferralCodeParams as ActionCreateReferralCodeParams,
+  ActionParamsMap,
   PlaceTwapOrderParams as ActionPlaceTwapOrderParams,
   ActionStep,
   ExecuteActionResponse,
   MarginMode,
   MarketRef,
+  MetaActionType,
   ModifyOrderInput,
+  OnboardParams,
   OrderSide,
   OrderType,
   SignedActionStep,
@@ -344,3 +348,33 @@ export interface GetAccountResult extends AccountResponse {
   /** SDK-projected current state of every setup + options descriptor. */
   settings: AccountConfigSetting[]
 }
+
+/**
+ * Parameters for {@link PerpsClient.submitOnboarding}.
+ *
+ * @public
+ */
+export interface SubmitOnboardingParams extends OnboardParams {
+  address: Address
+}
+
+/**
+ * Parameters for {@link PerpsClient.createReferralCode}.
+ *
+ * @public
+ */
+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/utils/switchChain.ts

@@ -8,12 +8,26 @@ import { getChainId } from 'viem/actions'
 import { PerpsError } from '../errors/PerpsError.js'
 import type { PerpsClientSigner, SwitchChainHook } from '../types/config.js'
 
+/**
+ * The chain `actions` are signed on: the first numeric
+ * `typedData.domain.chainId` across the batch, or `undefined` when no step
+ * carries one.
+ */
+export function eip712DomainChainId(actions: ActionStep[]): number | undefined {
+  for (const step of actions) {
+    const chainId = (step as Eip712ActionStep).typedData?.domain?.chainId
+    if (typeof chainId === 'number') {
+      return chainId
+    }
+  }
+  return undefined
+}
+
 /**
  * The chain a batch of `actions` must be signed on, or `undefined` when no
  * wallet chain switch applies. Only USER-signed EIP-712 batches carry a target
  * (agent-signed batches sign with a chain-bound keypair; other schemes are not
- * EIP-712). Reads the first numeric `typedData.domain.chainId`; a batch whose
- * steps omit `chainId` yields `undefined`.
+ * EIP-712).
  */
 export function userEip712TargetChainId(
   descriptor: ProviderAction,
@@ -25,13 +39,7 @@ export function userEip712TargetChainId(
   ) {
     return undefined
   }
-  for (const step of actions) {
-    const chainId = (step as Eip712ActionStep).typedData?.domain?.chainId
-    if (typeof chainId === 'number') {
-      return chainId
-    }
-  }
-  return undefined
+  return eip712DomainChainId(actions)
 }
 
 /**

package/src/version.ts

@@ -10,4 +10,4 @@ export const name = '@lifi/perps-sdk'
  *
  * @public
  */
-export const version = '10.0.2'
+export const version = '10.1.0'