@lifi/perps-sdk-provider-lighter 21.0.0 → 22.1.0

package/src/utils/apiClient.ts

@@ -6,9 +6,11 @@ import {
 import { PerpsErrorCode } from '@lifi/perps-types'
 import {
   LIGHTER_INVALID_AUTH_CODE,
+  LIGHTER_INVALID_SIGNATURE_CODE,
   LIGHTER_SUCCESS_CODES,
   LIGHTER_TOKEN_REVOKED_CODE,
 } from '../constants.js'
+import { lighterErrorCodeFromBody } from './lighterErrorCode.js'
 
 /** @internal */
 export type ApiParams = Record<string, string | number | boolean>
@@ -40,19 +42,33 @@ export class LighterAuthRejectedError extends PerpsError {}
  */
 export class LighterTokenRevokedError extends PerpsError {}
 
-const isLighterAuthRejection = (status: number, data: unknown): boolean =>
-  status === 401 ||
-  status === 403 ||
-  lighterBodyErrorCode(data) === LIGHTER_INVALID_AUTH_CODE
+const isLighterAuthRejection = (status: number, data: unknown): boolean => {
+  if (status === 401 || status === 403) {
+    return true
+  }
+  const code = lighterBodyErrorCode(data)
+  return (
+    code === LIGHTER_INVALID_AUTH_CODE ||
+    code === LIGHTER_INVALID_SIGNATURE_CODE
+  )
+}
 
 const isLighterTokenRevoked = (data: unknown): boolean =>
   lighterBodyErrorCode(data) === LIGHTER_TOKEN_REVOKED_CODE
 
 /**
  * A CR or LF in a token would split the request when it reaches a
- * `fetchImpl` that does not validate header values itself.
+ * `fetchImpl` that does not validate header values itself. A blank token
+ * would dispatch an `Authorization` header that carries no credential at
+ * all, which Lighter answers as a generic rejection.
  */
 const assertHeaderSafe = (authToken: string): string => {
+  if (authToken.trim().length === 0) {
+    throw new PerpsError(
+      PerpsErrorCode.ValidationError,
+      'Lighter auth token is blank and cannot go in a header'
+    )
+  }
   if (/[\r\n]/.test(authToken)) {
     throw new PerpsError(
       PerpsErrorCode.ValidationError,
@@ -136,6 +152,11 @@ export interface LighterApiClientOptions {
  * `Access-Control-Max-Age: 86400`, so a browser sends one preflight per day
  * per origin.
  *
+ * The `/api/v1/changeAccountTier` and `/api/v1/referral/use` mutations send
+ * the same header with a fresh per-call token. Their `OPTIONS` response is
+ * not yet probed against a live host, so a browser may reject the preflight
+ * even though the GET paths pass.
+ *
  * Lighter signals rate limits through HTTP 429 or HTTP 405. This client never
  * retries such a response. It throws `RateLimitExceeded` and holds all network
  * dispatch until `Retry-After` expires (capped at five minutes), or for 60
@@ -226,13 +247,13 @@ export class LighterApiClient {
     })
     if (isLighterTokenRevoked(data)) {
       throw new LighterTokenRevokedError(
-        PerpsErrorCode.ThirdPartyError,
+        PerpsErrorCode.Unauthorized,
         `Lighter reports a revoked auth token for ${path}`
       )
     }
     if (isLighterAuthRejection(status, data)) {
       throw new LighterAuthRejectedError(
-        PerpsErrorCode.ThirdPartyError,
+        PerpsErrorCode.Unauthorized,
         `Lighter rejected the auth token for ${path}`
       )
     }
@@ -274,13 +295,15 @@ export class LighterApiClient {
   }
 
   /**
-   * Form-encoded POST to a Lighter mutation endpoint. Single-shot — never
-   * retried, since these are money/state writes whose outcome is unknown on a
-   * transport failure. Surfaces the raw `{status, body}` pair so the caller can
-   * map Lighter's per-endpoint business-rule `code` to a domain error verbatim.
+   * Form-encoded POST to a Lighter mutation endpoint, carrying the Lighter
+   * token in the `Authorization` header. Single-shot — never retried, since
+   * these are money/state writes whose outcome is unknown on a transport
+   * failure. Surfaces the raw `{status, body}` pair so the caller can map
+   * Lighter's per-endpoint business-rule `code` to a domain error verbatim.
    */
   async postForm<T>(
     path: string,
+    authToken: string,
     params: ApiParams
   ): Promise<{ status: number; data: T }> {
     const body = new URLSearchParams()
@@ -289,7 +312,10 @@ export class LighterApiClient {
     }
     const response = await this.fetchWithHold(`${this.baseUrl}${path}`, {
       method: 'POST',
-      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      headers: {
+        'content-type': 'application/x-www-form-urlencoded',
+        Authorization: assertHeaderSafe(authToken),
+      },
       body: body.toString(),
       signal: this.signal,
     })
@@ -306,20 +332,24 @@ export class LighterApiClient {
 
   /**
    * Post-parse validation shared by every checked read: rejects a non-2xx HTTP
-   * status and a 200 body carrying a non-success `code`. Callers that surface a
-   * distinct auth-rejection error must run that check before this one.
+   * status and a 200 body carrying a non-success `code`. A body `code` that
+   * names a nonce, margin, or balance rejection sets the matching
+   * `PerpsErrorCode`; every other rejection is `ThirdPartyError`. Callers that
+   * surface a distinct auth-rejection error must run that check before this one.
    */
   private assertOk(path: string, status: number, data: unknown): void {
+    const errorCode = lighterBodyErrorCode(data)
+    const code =
+      lighterErrorCodeFromBody(errorCode) ?? PerpsErrorCode.ThirdPartyError
     if (status < 200 || status >= 300) {
       throw new PerpsError(
-        PerpsErrorCode.ThirdPartyError,
+        code,
         `Lighter API request failed: ${status} — ${JSON.stringify(data).slice(0, 200)}`
       )
     }
-    const errorCode = lighterBodyErrorCode(data)
     if (errorCode !== undefined) {
       throw new PerpsError(
-        PerpsErrorCode.ThirdPartyError,
+        code,
         `Lighter API error for ${path}: code ${errorCode} — ${JSON.stringify(data).slice(0, 200)}`
       )
     }

package/src/utils/lighterErrorCode.ts

@@ -0,0 +1,30 @@
+import { PerpsErrorCode } from '@lifi/perps-types'
+
+/** Lighter body `code` values that name a rejection a `PerpsErrorCode` describes. */
+const LIGHTER_BODY_ERROR_CODES: ReadonlyMap<number, PerpsErrorCode> = new Map([
+  // invalid nonce
+  [21104, PerpsErrorCode.InvalidNonce],
+  // batch transaction nonce is not increasing
+  [21105, PerpsErrorCode.InvalidNonce],
+  // not enough collateral
+  [21301, PerpsErrorCode.InsufficientBalance],
+  // not enough asset balance
+  [21304, PerpsErrorCode.InsufficientBalance],
+  // not enough asset balance for fee
+  [21305, PerpsErrorCode.InsufficientBalance],
+  // account is below maintenance margin
+  [21507, PerpsErrorCode.InsufficientMargin],
+  // account is below initial margin
+  [21508, PerpsErrorCode.InsufficientMargin],
+  // not enough margin to create the order
+  [21739, PerpsErrorCode.InsufficientMargin],
+])
+
+/**
+ * Maps a Lighter body error `code` to the `PerpsErrorCode` it names. Returns
+ * `undefined` for every other code so the status-driven layer decides.
+ */
+export const lighterErrorCodeFromBody = (
+  code: number | undefined
+): PerpsErrorCode | undefined =>
+  code === undefined ? undefined : LIGHTER_BODY_ERROR_CODES.get(code)

package/src/utils/mapFill.ts

@@ -107,9 +107,11 @@ export const mapFill = (
 
   // Lighter publishes both counterparties' position-before snapshots on every
   // trade row; reading the wrong one mis-classifies when they differ.
-  const startPosition = isMaker
-    ? trade.maker_position_size_before
-    : trade.taker_position_size_before
+  // Both keys are `omitempty`: an absent snapshot means flat.
+  const startPosition =
+    (isMaker
+      ? trade.maker_position_size_before
+      : trade.taker_position_size_before) ?? '0'
   const entryQuoteBefore = isMaker
     ? trade.maker_entry_quote_before
     : trade.taker_entry_quote_before

package/src/utils/mapPosition.ts

@@ -60,7 +60,7 @@ export const mapPosition = (
         : positionValue.div(size.abs()).toFixed(),
     liquidationPrice: pos.liquidation_price,
     unrealizedPnl: pos.unrealized_pnl,
-    accruedFunding: pos.total_funding_paid_out,
+    accruedFunding: pos.total_funding_paid_out ?? '0',
     leverage: leverageFromImf(pos.initial_margin_fraction) ?? 1,
     marginUsed,
     initialMarginRequirement: initialMarginRequirement.toFixed(),