@lifi/perps-sdk-provider-hyperliquid 6.0.0 → 6.0.2

package/src/utils/assetLogo.ts

@@ -47,7 +47,12 @@ const UNIT_UNDERLYING_SYMBOL: Readonly<Record<string, string>> = {
   UANSEM: 'ANSEM',
 }
 
-/** Token `name`s of the Unit-bridged HL spot assets. */
+/**
+ * Names of Unit-bridged Hyperliquid spot tokens recognized by the logo
+ * resolver. The set is read-only and is intended for callers that need to
+ * distinguish Unit balances before resolving their icons.
+ * @public
+ */
 export const UNIT_TOKEN_NAMES: ReadonlySet<string> = new Set(
   Object.keys(UNIT_UNDERLYING_SYMBOL)
 )
@@ -58,24 +63,21 @@ const unitSpotLogoURI = (name: string): string => {
   return underlying === undefined ? '' : `${HL_COIN_CDN}/${underlying}.svg`
 }
 
-/** Return `asset` with its `logoURI` replaced when a display-symbol override exists. */
+/**
+ * Apply the provider's known symbol-specific logo corrections to an asset.
+ * Returns the original object when no override exists.
+ * @public
+ */
 export const applyLogoOverride = (asset: Asset): Asset => {
   const override = BASE_ASSET_LOGO_OVERRIDES[asset.displaySymbol]
   return override === undefined ? asset : { ...asset, logoURI: override }
 }
 
 /**
- * Override-aware logo URI for a Hyperliquid spot token. Base rule is
- * `coins/${name}_spot.svg`; a Unit-bridged token (`fullName` starts with
- * "Unit") resolves to its underlying's icon instead; the override table wins
- * over both.
- *
- * When `fullName` is absent — spot *balances* (`HlSpotBalance`) carry no
- * `fullName` and this issue deliberately does not fetch `spotMeta` on the
- * account path — the derivation degrades to the symbol-keyed override + base
- * `_spot` rule, so a Unit-bridged balance uses the base rule rather than its
- * underlying's icon. The registry path (which has `fullName`) keeps full Unit
- * resolution.
+ * Resolve the logo URI for a Hyperliquid spot token. Unit-bridged tokens use
+ * the underlying symbol's icon when `fullName` starts with `'Unit'`; otherwise
+ * the base URI is `coins/${name}_spot.svg`. Known symbol overrides win.
+ * @public
  */
 export const spotLogoURI = (name: string, fullName?: string | null): string => {
   const base = fullName?.startsWith('Unit')

package/src/utils/decodeFastAssetCtxs.ts

@@ -1,6 +1,11 @@
 import type { HlWsFastAssetCtx } from '../types/index.js'
 
-/** Decode a base64 + raw-DEFLATE (RFC 1951) payload into parsed JSON. */
+/**
+ * Decode a base64-encoded raw-DEFLATE payload and parse its UTF-8 JSON body.
+ * @typeParam T - Expected shape of the decoded JSON value.
+ * @throws If decompression or JSON parsing fails.
+ * @public
+ */
 export async function decodeCompressedJson<T>(base64: string): Promise<T> {
   const binary = atob(base64)
   const bytes = new Uint8Array(binary.length)
@@ -24,6 +29,7 @@ export async function decodeCompressedJson<T>(base64: string): Promise<T> {
  * (Node 18+, modern browsers), so no dependency is needed.
  *
  * @throws If the input is not valid base64 / raw-DEFLATE / JSON.
+ * @public
  */
 export async function decodeFastAssetCtxs(
   base64: string

package/src/utils/infoClient.ts

@@ -50,7 +50,12 @@ export const HYPERLIQUID_RETRY_DEFAULTS: ResolvedRetryPolicy = {
   },
 }
 
-/** @public */
+/**
+ * Transport options for a direct Hyperliquid `/info` request. `policy`
+ * controls retries, `signal` cancels the request, and `fetchImpl` overrides
+ * the runtime's global `fetch` implementation.
+ * @public
+ */
 export interface InfoRequestOptions {
   signal?: AbortSignal
   policy?: ResolvedRetryPolicy

package/src/utils/mapActivity.ts

@@ -165,18 +165,30 @@ export const mapLedgerEntry = (
   }
 }
 
-/** @public */
+/**
+ * Map a Hyperliquid funding ledger update to a normalized funding activity.
+ * `amount`, `positionSize`, and `fundingRate` retain the upstream decimal
+ * strings; `resolveMarket` supplies the provider-agnostic market metadata.
+ *
+ * `userFunding` entries all carry the zero hash, so a deterministic
+ * `funding:<coin>:<ISO time>` id is synthesized — funding accrues at most
+ * once per coin per hourly settlement, so the pair is unique per account.
+ * @public
+ */
 export const mapFundingActivity = (
   entry: HlFundingUpdate,
   providerKey: string,
   resolveMarket: (coin: string) => MarketDisplay
-): FundingActivity => ({
-  id: entry.hash,
-  provider: providerKey,
-  timestamp: new Date(entry.time).toISOString(),
-  type: ActivityType.FUNDING,
-  market: resolveMarket(entry.delta.coin),
-  amount: entry.delta.usdc,
-  positionSize: entry.delta.szi,
-  fundingRate: entry.delta.fundingRate,
-})
+): FundingActivity => {
+  const timestamp = new Date(entry.time).toISOString()
+  return {
+    id: `funding:${entry.delta.coin}:${timestamp}`,
+    provider: providerKey,
+    timestamp,
+    type: ActivityType.FUNDING,
+    market: resolveMarket(entry.delta.coin),
+    amount: entry.delta.usdc,
+    positionSize: entry.delta.szi,
+    fundingRate: entry.delta.fundingRate,
+  }
+}

package/src/utils/mapFill.ts

@@ -14,6 +14,7 @@ import {
 import { SPOT_MARKET_ID } from '../constants.js'
 import type { HlUserFill } from '../types/index.js'
 
+/** Re-export the shared fill-position classifier used by Hyperliquid mappings. @public */
 export { classifyFillFromPosition }
 
 /**

package/src/utils/mapOrder.ts

@@ -34,7 +34,7 @@ export const mapOrderType = (orderType: string): OrderType => {
   }
 }
 
-/** @public */
+/** Return whether an SDK order type represents a take-profit or stop trigger. @public */
 export const isTriggerType = (type: OrderType): boolean =>
   type === OrderType.TAKE_PROFIT_MARKET ||
   type === OrderType.TAKE_PROFIT_LIMIT ||
@@ -83,7 +83,11 @@ export const isTriggerOrder = (
   return isTriggerType(mapOrderType(o.orderType))
 }
 
-/** @public */
+/**
+ * Map an open Hyperliquid order to the SDK's normalized open-order shape.
+ * Numeric IDs become strings and wire millisecond timestamps become ISO dates.
+ * @public
+ */
 export const mapOpenOrder = (
   o: HlFrontendOpenOrder,
   market: MarketDisplay
@@ -102,7 +106,10 @@ export const mapOpenOrder = (
   createdAt: new Date(o.timestamp).toISOString(),
 })
 
-/** @public */
+/**
+ * Map a Hyperliquid trigger/TP-SL order to the SDK's trigger-order shape.
+ * @public
+ */
 export const mapTriggerOrder = (
   o: HlFrontendOpenOrder,
   market: MarketDisplay
@@ -232,7 +239,11 @@ const mapTimeInForce = (tif: string | undefined): TimeInForce | undefined => {
   }
 }
 
-/** @public */
+/**
+ * Map an `orderStatus` detail to the SDK's normalized order shape, preserving
+ * decimal size/price strings and translating status, side, and time-in-force.
+ * @public
+ */
 export const mapOrder = (
   detail: HlOrderDetail,
   market: MarketDisplay

package/src/utils/mapPosition.ts

@@ -12,7 +12,12 @@ import type { HlAssetPosition } from '../types/index.js'
 export const isOpenAssetPosition = (ap: HlAssetPosition): boolean =>
   Number.parseFloat(ap.position.szi) !== 0
 
-/** @public */
+/**
+ * Map a non-zero Hyperliquid position payload to the SDK's normalized
+ * position. Signed wire size determines side; decimal strings remain strings
+ * in the normalized response.
+ * @public
+ */
 export const mapPosition = (
   ap: HlAssetPosition,
   market: PerpsMarketDisplay

package/src/utils/spotBalance.ts

@@ -6,10 +6,10 @@ import { spotLogoURI } from './assetLogo.js'
 import { coinAsset } from './marketDisplay.js'
 
 /**
- * USD price keyed by spot token index: each spot market's live USD price
- * (from `priceByMarketId`, keyed by `Market.id`) under its base-asset id, and
- * every market's quote-asset id at $1. A spot market absent from
- * `priceByMarketId` values its token at 0.
+ * Build USD prices keyed by spot token asset ID. Base tokens use the supplied
+ * market mark price; quote tokens default to exactly `$1`; missing base prices
+ * default to `0`.
+ * @public
  */
 export const spotPriceById = (
   markets: readonly Market[],
@@ -30,11 +30,10 @@ export const spotPriceById = (
 }
 
 /**
- * The held spot {@link Asset} for an HL balance: the venue token index
- * (`b.token`) as `Asset.id` — equal to that token's spot `Market.baseAsset.id`
- * — with display fields derived from the coin and the override-aware spot logo.
- * `HlSpotBalance` carries no `fullName`, so Unit-bridged balances take the base
- * `_spot` rule (see {@link spotLogoURI}).
+ * Convert a Hyperliquid spot balance's numeric token index into an SDK asset.
+ * The balance payload has no `fullName`, so logo resolution uses the base
+ * `_spot` URI rule rather than Unit-underlying lookup.
+ * @public
  */
 export const spotAssetFromToken = (b: HlSpotBalance): Asset => ({
   ...coinAsset(b.coin),
@@ -42,7 +41,7 @@ export const spotAssetFromToken = (b: HlSpotBalance): Asset => ({
   logoURI: spotLogoURI(b.coin),
 })
 
-/** Assemble a typed spot {@link Balance} from its resolved asset and raw size. */
+/** Assemble a typed spot {@link Balance}; `total` is native token units and its USD value uses `priceById`. @public */
 export const spotBalance = (
   asset: Asset,
   total: string,

package/src/utils/spotCollateral.ts

@@ -13,17 +13,21 @@ const PORTFOLIO_MARGIN_LTV: Readonly<Record<string, number>> = {
   UBTC: 0.5,
 }
 
-/** @internal */
+/**
+ * Result of {@link partitionSpotBalances}: balances that count toward
+ * collateral and balances treated as ordinary holdings.
+ * @public
+ */
 export interface SpotPartition {
   collateralBalances: Balance[]
   balances: Balance[]
 }
 
 /**
- * Split spot balances into margin collateral and flat holdings. A balance is
- * collateral when its token is a category quote asset (full value) or, under
- * portfolio margin, an LTV-weighted asset (HYPE/BTC); everything else is a
- * flat holding.
+ * Partition spot balances into collateral and ordinary holdings. Quote assets
+ * are full-value collateral; portfolio-margin-supported assets retain their
+ * LTV as `collateralWeight`.
+ * @public
  */
 export const partitionSpotBalances = (
   spotBalances: readonly Balance[],

package/src/utils/transferMargin.ts

@@ -1,10 +1,9 @@
 import { PerpsError } from '@lifi/perps-sdk'
 import {
-  MarginMode,
   PerpsErrorCode,
   type Position,
-  PositionMarginAdjustment,
   type PositionMarginConstraints,
+  positionSupportsMarginAdjustment,
 } from '@lifi/perps-types'
 import Big from 'big.js'
 
@@ -44,10 +43,7 @@ function positivePositionAmount(value: string, field: string): Big {
 export function positionMarginConstraints(
   position: Position
 ): PositionMarginConstraints | undefined {
-  if (
-    position.marginMode !== MarginMode.ISOLATED ||
-    position.market.positionMarginAdjustment === PositionMarginAdjustment.NONE
-  ) {
+  if (!positionSupportsMarginAdjustment(position)) {
     return undefined
   }
   const initialMargin = positivePositionAmount(