@lifi/perps-sdk 0.1.1-alpha.9 → 1.0.0

package/dist/esm/utils/positionMath.js

@@ -0,0 +1,119 @@
+/**
+ * Pure-function helpers for predicting how a perp position changes after a
+ * fill.
+ *
+ * Sign convention: long = +1, short = -1. Sizes passed to these helpers are
+ * always non-negative magnitudes; direction is carried by `isLong`.
+ */
+/**
+ * Direction sign for a position.
+ *
+ * @param isLong - True for long positions, false for short.
+ * @returns +1 for long, -1 for short.
+ * @public
+ */
+export function directionSign(isLong) {
+    return isLong ? 1 : -1;
+}
+/**
+ * Estimated liquidation price for an isolated-margin position, parameterised
+ * by the venue's maintenance margin rate.
+ *
+ * Standard isolated-margin model (new position, no existing exposure):
+ *   margin_per_unit      = entryPrice / leverage
+ *   maintenance_per_unit = entryPrice * mmr
+ *   margin_available     = margin_per_unit - maintenance_per_unit
+ *   liq_price            = entryPrice - side * margin_available / (1 - mmr * side)
+ *
+ * For existing positions, prefer `Position.liquidationPrice` from the venue.
+ *
+ * @param maintenanceMarginRate - Venue maintenance margin rate as a fraction
+ *   (e.g. 0.01 = 1%).
+ * @returns Estimated liquidation price, or undefined if the inputs cannot
+ *   produce one (zero leverage, degenerate denominator).
+ * @public
+ */
+export function estimateIsolatedLiquidationPrice(params) {
+    const { entryPrice, leverage, isLong, maintenanceMarginRate } = params;
+    if (leverage === 0) {
+        return undefined;
+    }
+    const side = directionSign(isLong);
+    const denominator = 1 - maintenanceMarginRate * side;
+    if (denominator === 0) {
+        return undefined;
+    }
+    const marginAvailable = entryPrice * (1 / leverage - maintenanceMarginRate);
+    return entryPrice - (side * marginAvailable) / denominator;
+}
+/**
+ * Predicted average entry price after adding to an existing position.
+ *
+ * Weighted average of the current entry and the new fill price, weighted by
+ * the size of each leg in coin units. Both legs assumed in the same direction
+ * (this helper is for adding to, not flipping, a position).
+ *
+ * @param currentSize - Existing position size in coin units (>= 0).
+ * @param currentEntry - Existing position's average entry price.
+ * @param addSize - Size being added in coin units (>= 0).
+ * @param fillPrice - Price the new size is expected to fill at (mid for
+ *   market, limitPrice for limit orders).
+ * @returns The new weighted-average entry price, or undefined if the inputs
+ *   cannot produce a valid average (zero combined size, non-finite values).
+ * @public
+ */
+export function predictAverageEntryPrice(params) {
+    const { currentSize, currentEntry, addSize, fillPrice } = params;
+    const totalSize = currentSize + addSize;
+    if (totalSize <= 0) {
+        return undefined;
+    }
+    if (!Number.isFinite(currentEntry) || !Number.isFinite(fillPrice)) {
+        return undefined;
+    }
+    return (currentSize * currentEntry + addSize * fillPrice) / totalSize;
+}
+/**
+ * Predicted effective leverage after adding margin and notional.
+ *
+ * leverage = totalNotional / totalMargin. The caller computes notional from
+ * size and price (`calculateNotionalValue`) and supplies the additional
+ * margin the user is about to put up.
+ *
+ * @returns The new effective leverage, or undefined if total margin is
+ *   non-positive.
+ * @public
+ */
+export function predictNewLeverage(params) {
+    const { currentNotional, currentMargin, addNotional, addMargin } = params;
+    const totalMargin = currentMargin + addMargin;
+    if (totalMargin <= 0) {
+        return undefined;
+    }
+    return (currentNotional + addNotional) / totalMargin;
+}
+/**
+ * Predicted unrealised PnL at the current mark price.
+ *
+ * `pnl = (markPrice - entryPrice) * size * directionSign(isLong)`
+ *
+ * @param size - Position size as a non-negative magnitude.
+ * @public
+ */
+export function predictUnrealizedPnl(params) {
+    const { entryPrice, markPrice, size, isLong } = params;
+    return (markPrice - entryPrice) * size * directionSign(isLong);
+}
+/**
+ * Realised PnL on the portion of a position being closed.
+ *
+ * `rPnl = (closePrice - entryPrice) * closeSize * directionSign(isLong)`
+ *
+ * @param closeSize - Size being closed as a non-negative magnitude.
+ * @public
+ */
+export function realizedPnlOnClose(params) {
+    const { entryPrice, closePrice, closeSize, isLong } = params;
+    return (closePrice - entryPrice) * closeSize * directionSign(isLong);
+}
+//# sourceMappingURL=positionMath.js.map

package/dist/esm/utils/positionMath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"positionMath.js","sourceRoot":"","sources":["../../../src/utils/positionMath.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,MAAe;IAC3C,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AACxB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gCAAgC,CAAC,MAKhD;IACC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,qBAAqB,EAAE,GAAG,MAAM,CAAA;IACtE,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAA;IAClC,MAAM,WAAW,GAAG,CAAC,GAAG,qBAAqB,GAAG,IAAI,CAAA;IACpD,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,eAAe,GAAG,UAAU,GAAG,CAAC,CAAC,GAAG,QAAQ,GAAG,qBAAqB,CAAC,CAAA;IAC3E,OAAO,UAAU,GAAG,CAAC,IAAI,GAAG,eAAe,CAAC,GAAG,WAAW,CAAA;AAC5D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAKxC;IACC,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,CAAA;IAChE,MAAM,SAAS,GAAG,WAAW,GAAG,OAAO,CAAA;IACvC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QACnB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAClE,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,CAAC,WAAW,GAAG,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC,GAAG,SAAS,CAAA;AACvE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAKlC;IACC,MAAM,EAAE,eAAe,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,MAAM,CAAA;IACzE,MAAM,WAAW,GAAG,aAAa,GAAG,SAAS,CAAA;IAC7C,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACrB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,OAAO,CAAC,eAAe,GAAG,WAAW,CAAC,GAAG,WAAW,CAAA;AACtD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAKpC;IACC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;IACtD,OAAO,CAAC,SAAS,GAAG,UAAU,CAAC,GAAG,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAA;AAChE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAKlC;IACC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;IAC5D,OAAO,CAAC,UAAU,GAAG,UAAU,CAAC,GAAG,SAAS,GAAG,aAAa,CAAC,MAAM,CAAC,CAAA;AACtE,CAAC"}

package/dist/esm/utils/signTypedData.d.ts

@@ -1,15 +1,18 @@
-import type { Hex, PerpsTypedData } from '@lifi/perps-types';
+import type { PerpsTypedData } from '@lifi/perps-types';
+import type { Account, Hex, WalletClient } from 'viem';
 /**
- * Sign EIP-712 typed data with a private key.
+ * Sign EIP-712 typed data with a raw private key (agent keypair).
  *
- * @param privateKey - The private key to sign with
- * @param typedData - The typed data to sign
- * @returns The signature as a hex string
- *
- * @example
- * ```ts
- * const signature = await signTypedData(agentPrivateKey, typedData)
- * ```
+ * @public
  */
 export declare function signTypedData(privateKey: Hex, typedData: PerpsTypedData): Promise<Hex>;
+/**
+ * Sign EIP-712 typed data with an externally-provided WalletClient. Works
+ * with browser wallets (wagmi), private keys, mnemonics — any viem
+ * WalletClient. Used by provider plugins to sign the EIP712 USER arm with the
+ * end-user's wallet.
+ *
+ * @public
+ */
+export declare function signTypedDataWithSigner(userWallet: WalletClient<any, any, Account>, typedData: PerpsTypedData): Promise<Hex>;
 //# sourceMappingURL=signTypedData.d.ts.map

package/dist/esm/utils/signTypedData.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signTypedData.d.ts","sourceRoot":"","sources":["../../../src/utils/signTypedData.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAG5D;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,GAAG,EACf,SAAS,EAAE,cAAc,GACxB,OAAO,CAAC,GAAG,CAAC,CAYd"}
+{"version":3,"file":"signTypedData.d.ts","sourceRoot":"","sources":["../../../src/utils/signTypedData.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AAGtD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,GAAG,EACf,SAAS,EAAE,cAAc,GACxB,OAAO,CAAC,GAAG,CAAC,CAOd;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,EAC3C,SAAS,EAAE,cAAc,GACxB,OAAO,CAAC,GAAG,CAAC,CAQd"}

package/dist/esm/utils/signTypedData.js

@@ -1,25 +1,32 @@
 import { privateKeyToAccount } from 'viem/accounts';
 /**
- * Sign EIP-712 typed data with a private key.
+ * Sign EIP-712 typed data with a raw private key (agent keypair).
  *
- * @param privateKey - The private key to sign with
- * @param typedData - The typed data to sign
- * @returns The signature as a hex string
- *
- * @example
- * ```ts
- * const signature = await signTypedData(agentPrivateKey, typedData)
- * ```
+ * @public
  */
 export async function signTypedData(privateKey, typedData) {
-    const account = privateKeyToAccount(privateKey);
-    // viem's signTypedData expects the typed data in a specific format
-    const signature = await account.signTypedData({
+    return privateKeyToAccount(privateKey).signTypedData({
+        domain: typedData.domain,
+        types: typedData.types,
+        primaryType: typedData.primaryType,
+        message: typedData.message,
+    });
+}
+/**
+ * Sign EIP-712 typed data with an externally-provided WalletClient. Works
+ * with browser wallets (wagmi), private keys, mnemonics — any viem
+ * WalletClient. Used by provider plugins to sign the EIP712 USER arm with the
+ * end-user's wallet.
+ *
+ * @public
+ */
+export async function signTypedDataWithSigner(userWallet, typedData) {
+    return userWallet.signTypedData({
+        account: userWallet.account,
         domain: typedData.domain,
         types: typedData.types,
         primaryType: typedData.primaryType,
         message: typedData.message,
     });
-    return signature;
 }
 //# sourceMappingURL=signTypedData.js.map

package/dist/esm/utils/signTypedData.js.map

@@ -1 +1 @@
-{"version":3,"file":"signTypedData.js","sourceRoot":"","sources":["../../../src/utils/signTypedData.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAEnD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAAe,EACf,SAAyB;IAEzB,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAA;IAE/C,mEAAmE;IACnE,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC;QAC5C,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,OAAO,EAAE,SAAS,CAAC,OAAO;KAC3B,CAAC,CAAA;IAEF,OAAO,SAAS,CAAA;AAClB,CAAC"}
+{"version":3,"file":"signTypedData.js","sourceRoot":"","sources":["../../../src/utils/signTypedData.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAEnD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,UAAe,EACf,SAAyB;IAEzB,OAAO,mBAAmB,CAAC,UAAU,CAAC,CAAC,aAAa,CAAC;QACnD,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,OAAO,EAAE,SAAS,CAAC,OAAO;KAC3B,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,UAA2C,EAC3C,SAAyB;IAEzB,OAAO,UAAU,CAAC,aAAa,CAAC;QAC9B,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,OAAO,EAAE,SAAS,CAAC,OAAO;KAC3B,CAAC,CAAA;AACJ,CAAC"}

package/dist/esm/utils/sleep.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Resolve after `ms` milliseconds.
+ *
+ * @internal
+ */
 export declare const sleep: (ms: number) => Promise<void>;
 //# sourceMappingURL=sleep.d.ts.map

package/dist/esm/utils/sleep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../../src/utils/sleep.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK,GAAI,IAAI,MAAM,KAAG,OAAO,CAAC,IAAI,CACI,CAAA"}
+{"version":3,"file":"sleep.d.ts","sourceRoot":"","sources":["../../../src/utils/sleep.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,IAAI,MAAM,KAAG,OAAO,CAAC,IAAI,CACI,CAAA"}

package/dist/esm/utils/sleep.js

@@ -1,2 +1,7 @@
+/**
+ * Resolve after `ms` milliseconds.
+ *
+ * @internal
+ */
 export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 //# sourceMappingURL=sleep.js.map

package/dist/esm/utils/sleep.js.map

@@ -1 +1 @@
-{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../../../src/utils/sleep.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CACjD,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAA"}
+{"version":3,"file":"sleep.js","sourceRoot":"","sources":["../../../src/utils/sleep.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,EAAU,EAAiB,EAAE,CACjD,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAA"}

package/dist/esm/utils/units.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Token unit conversion utilities.
+ */
+/**
+ * Convert a base-unit amount (bigint string) to a human-readable decimal string.
+ *
+ * @param amount - Amount in base units (e.g. "1000000" for 1 USDC)
+ * @param decimals - Token decimals (e.g. 6 for USDC)
+ * @returns Decimal string (e.g. "1.0"); `"0"` when `amount` is not a valid
+ *   bigint
+ * @example
+ * ```ts
+ * fromBaseUnits('1000000', 6) // '1'
+ * ```
+ * @public
+ */
+export declare function fromBaseUnits(amount: string, decimals: number): string;
+/**
+ * Convert a base-unit amount to a number.
+ *
+ * @param amount - Amount in base units
+ * @param decimals - Token decimals
+ * @returns Numeric value, or 0 if parsing fails
+ * @public
+ */
+export declare function fromBaseUnitsNumber(amount: string, decimals: number): number;
+//# sourceMappingURL=units.d.ts.map

package/dist/esm/utils/units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../../src/utils/units.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMtE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG5E"}

package/dist/esm/utils/units.js

@@ -0,0 +1,38 @@
+/**
+ * Token unit conversion utilities.
+ */
+import { formatUnits } from 'viem';
+/**
+ * Convert a base-unit amount (bigint string) to a human-readable decimal string.
+ *
+ * @param amount - Amount in base units (e.g. "1000000" for 1 USDC)
+ * @param decimals - Token decimals (e.g. 6 for USDC)
+ * @returns Decimal string (e.g. "1.0"); `"0"` when `amount` is not a valid
+ *   bigint
+ * @example
+ * ```ts
+ * fromBaseUnits('1000000', 6) // '1'
+ * ```
+ * @public
+ */
+export function fromBaseUnits(amount, decimals) {
+    try {
+        return formatUnits(BigInt(amount), decimals);
+    }
+    catch {
+        return '0';
+    }
+}
+/**
+ * Convert a base-unit amount to a number.
+ *
+ * @param amount - Amount in base units
+ * @param decimals - Token decimals
+ * @returns Numeric value, or 0 if parsing fails
+ * @public
+ */
+export function fromBaseUnitsNumber(amount, decimals) {
+    const value = Number(fromBaseUnits(amount, decimals));
+    return Number.isFinite(value) ? value : 0;
+}
+//# sourceMappingURL=units.js.map

package/dist/esm/utils/units.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.js","sourceRoot":"","sources":["../../../src/utils/units.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,MAAM,CAAA;AAElC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,QAAgB;IAC5D,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAA;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAA;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc,EAAE,QAAgB;IAClE,MAAM,KAAK,GAAG,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;IACrD,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;AAC3C,CAAC"}

package/dist/esm/utils/validation.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Order validation utilities.
+ */
+/**
+ * Validate margin input against available balance and exchange minimums.
+ *
+ * @param margin - Margin amount in USD
+ * @param _leverage - Position leverage (reserved for future use)
+ * @param availableBalance - Available balance, or null if unknown
+ * @param _feeRate - Fee rate as decimal, or null if unknown (reserved for future use)
+ * @param minMarginUsd - Minimum margin requirement in USD (exchange-specific).
+ *   Source this from the selected provider's `minOrderValueUsd` metadata
+ *   (see `@lifi/perps-types` `Provider`) rather than a client-side constant.
+ * @returns Error code: 'insufficient' | 'below-minimum' | '' (valid)
+ * @public
+ */
+export declare function validateMargin(margin: number, _leverage: number, availableBalance: number | null, _feeRate: number | null, minMarginUsd: number): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/esm/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,GAAG,IAAI,EAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,YAAY,EAAE,MAAM,GACnB,MAAM,CAcR"}

package/dist/esm/utils/validation.js

@@ -0,0 +1,29 @@
+/**
+ * Order validation utilities.
+ */
+/**
+ * Validate margin input against available balance and exchange minimums.
+ *
+ * @param margin - Margin amount in USD
+ * @param _leverage - Position leverage (reserved for future use)
+ * @param availableBalance - Available balance, or null if unknown
+ * @param _feeRate - Fee rate as decimal, or null if unknown (reserved for future use)
+ * @param minMarginUsd - Minimum margin requirement in USD (exchange-specific).
+ *   Source this from the selected provider's `minOrderValueUsd` metadata
+ *   (see `@lifi/perps-types` `Provider`) rather than a client-side constant.
+ * @returns Error code: 'insufficient' | 'below-minimum' | '' (valid)
+ * @public
+ */
+export function validateMargin(margin, _leverage, availableBalance, _feeRate, minMarginUsd) {
+    if (margin <= 0) {
+        return '';
+    }
+    if (availableBalance !== null && margin > availableBalance) {
+        return 'insufficient';
+    }
+    if (margin < minMarginUsd) {
+        return 'below-minimum';
+    }
+    return '';
+}
+//# sourceMappingURL=validation.js.map

package/dist/esm/utils/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAc,EACd,SAAiB,EACjB,gBAA+B,EAC/B,QAAuB,EACvB,YAAoB;IAEpB,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAChB,OAAO,EAAE,CAAA;IACX,CAAC;IAED,IAAI,gBAAgB,KAAK,IAAI,IAAI,MAAM,GAAG,gBAAgB,EAAE,CAAC;QAC3D,OAAO,cAAc,CAAA;IACvB,CAAC;IAED,IAAI,MAAM,GAAG,YAAY,EAAE,CAAC;QAC1B,OAAO,eAAe,CAAA;IACxB,CAAC;IAED,OAAO,EAAE,CAAA;AACX,CAAC"}

package/dist/esm/version.d.ts

@@ -1,3 +1,3 @@
 export declare const name = "@lifi/perps-sdk";
-export declare const version = "0.1.1-alpha.9";
+export declare const version = "1.0.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/esm/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,IAAI,oBAAoB,CAAA;AACrC,eAAO,MAAM,OAAO,kBAAkB,CAAA"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,IAAI,oBAAoB,CAAA;AACrC,eAAO,MAAM,OAAO,UAAU,CAAA"}

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 export const name = '@lifi/perps-sdk';
-export const version = '0.1.1-alpha.9';
+export const version = '1.0.0';
 //# sourceMappingURL=version.js.map

package/dist/esm/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,IAAI,GAAG,iBAAiB,CAAA;AACrC,MAAM,CAAC,MAAM,OAAO,GAAG,eAAe,CAAA"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,IAAI,GAAG,iBAAiB,CAAA;AACrC,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAA"}

package/dist/esm/websocket/PerpsWsClient.d.ts

@@ -0,0 +1,100 @@
+import { type Subscription } from '@lifi/perps-types';
+import type { GetQuoteParams } from '../services/getQuote.js';
+import type { PerpsSDKClient, QuoteListener } from '../types/provider.js';
+import type { EventForSubscription, WsProvider, WsStatusListener } from './types.js';
+/**
+ * Factory for a per-provider WS plugin. Invoked once per provider key the
+ * first time `subscribe(...)` is called against it.
+ *
+ * @public
+ */
+export type WsProviderFactory = (params: {
+    /** Provider key (e.g. `'lighter'`, `'hyperliquid'`). */
+    provider: string;
+    /** WS URL discovered from `/providers`. */
+    wsUrl: string;
+    /**
+     * Markets visible to this provider via `/providers`, optionally filtered
+     * by the consumer's `createPerpsClient({ providers: { [key]: { markets } } })`
+     * config. Each provider interprets these its own way — Hyperliquid uses
+     * them to decide which sub-DEXes to subscribe to; Lighter ignores them.
+     */
+    markets: string[];
+    /**
+     * The SDK client. WS providers use it to call core services (e.g.
+     * `getAssets` to source the wire-id ↔ display-symbol map) without
+     * duplicating backend orchestration in the WS layer.
+     */
+    client: PerpsSDKClient;
+}) => WsProvider;
+/**
+ * Options for {@link PerpsWsClient}.
+ *
+ * @public
+ */
+export interface PerpsWsClientOptions {
+    /**
+     * Per-provider WS factory map. Each key (e.g. `'hyperliquid'`,
+     * `'lighter'`) maps to a factory that returns a `WsProvider`. Concrete
+     * implementations ship with the provider packages — e.g.
+     * `@lifi/perps-sdk-provider-hyperliquid` exports `HyperliquidWsProvider`,
+     * `@lifi/perps-sdk-provider-lighter` exports `LighterWsProvider`.
+     * Subscribing to a provider key without a registered factory throws.
+     */
+    wsProviders?: Record<string, WsProviderFactory>;
+}
+/**
+ * Realtime client: lazily instantiates a per-provider {@link WsProvider} on
+ * first subscription and fans subscriptions out to it.
+ *
+ * @public
+ */
+export declare class PerpsWsClient {
+    private readonly client;
+    private readonly options;
+    private providers;
+    private initPromises;
+    constructor(client: PerpsSDKClient, options?: PerpsWsClientOptions);
+    /**
+     * Subscribe to a realtime channel, lazily creating the provider's WS
+     * connection. Returns an unsubscribe function.
+     *
+     * @param onStatus - Optional listener for the underlying connection's
+     *   health. Fires `reconnecting` on a transient drop and the terminal
+     *   `disconnected` once auto-reconnect is abandoned, so consumers can
+     *   surface a reconnecting/disconnected state instead of silently showing
+     *   stale data.
+     * @throws {PerpsError} When no WS provider factory is registered for the
+     *   subscription's `dex`.
+     * @public
+     */
+    subscribe<S extends Subscription>(sub: S, listener: (event: EventForSubscription<S>) => void, onStatus?: WsStatusListener): Promise<() => void>;
+    /**
+     * Stream live fill quotes for `params.symbol` on `params.provider`, lazily
+     * creating the provider's WS connection. The provider's WS plugin layers the
+     * quote on its orderbook channel, so a concurrent orderbook subscription on
+     * the same market shares one wire subscription. Returns an unsubscribe
+     * function.
+     *
+     * @throws {PerpsError} When no WS provider factory is registered for
+     *   `params.provider`, or no market matches the symbol+type.
+     * @public
+     */
+    subscribeQuote(params: GetQuoteParams, onQuote: QuoteListener): Promise<() => void>;
+    /**
+     * Close every open provider WS connection and drop all cached providers.
+     *
+     * @public
+     */
+    close(): void;
+    /**
+     * Reconnect an already-created provider when its socket reached terminal
+     * `disconnected`. Safe no-op when the provider is unknown or not terminal.
+     *
+     * @public
+     */
+    reconnect(provider: string): void;
+    private getOrCreateProvider;
+    private initProvider;
+}
+//# sourceMappingURL=PerpsWsClient.d.ts.map

package/dist/esm/websocket/PerpsWsClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PerpsWsClient.d.ts","sourceRoot":"","sources":["../../../src/websocket/PerpsWsClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEzE,OAAO,KAAK,EACV,oBAAoB,EAEpB,UAAU,EACV,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAEnB;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE;IACvC,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB;;;;OAIG;IACH,MAAM,EAAE,cAAc,CAAA;CACvB,KAAK,UAAU,CAAA;AAEhB;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;CAChD;AAED;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,SAAS,CAAgC;IACjD,OAAO,CAAC,YAAY,CAAyC;gBAEjD,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,oBAAyB;IAKtE;;;;;;;;;;;;OAYG;IACG,SAAS,CAAC,CAAC,SAAS,YAAY,EACpC,GAAG,EAAE,CAAC,EACN,QAAQ,EAAE,CAAC,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAAK,IAAI,EAClD,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,IAAI,CAAC;IAOtB;;;;;;;;;;OAUG;IACG,cAAc,CAClB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC;IAatB;;;;OAIG;IACH,KAAK;IAQL;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;YAInB,mBAAmB;YAmBnB,YAAY;CAqC3B"}

package/dist/esm/websocket/PerpsWsClient.js

@@ -0,0 +1,121 @@
+import { PerpsErrorCode } from '@lifi/perps-types';
+import { PerpsError } from '../errors/PerpsError.js';
+import { getProviders } from '../services/getProviders.js';
+import { cachePromise } from './cachePromise.js';
+/**
+ * Realtime client: lazily instantiates a per-provider {@link WsProvider} on
+ * first subscription and fans subscriptions out to it.
+ *
+ * @public
+ */
+export class PerpsWsClient {
+    client;
+    options;
+    providers = new Map();
+    initPromises = new Map();
+    constructor(client, options = {}) {
+        this.client = client;
+        this.options = options;
+    }
+    /**
+     * Subscribe to a realtime channel, lazily creating the provider's WS
+     * connection. Returns an unsubscribe function.
+     *
+     * @param onStatus - Optional listener for the underlying connection's
+     *   health. Fires `reconnecting` on a transient drop and the terminal
+     *   `disconnected` once auto-reconnect is abandoned, so consumers can
+     *   surface a reconnecting/disconnected state instead of silently showing
+     *   stale data.
+     * @throws {PerpsError} When no WS provider factory is registered for the
+     *   subscription's `dex`.
+     * @public
+     */
+    async subscribe(sub, listener, onStatus) {
+        const providerKey = sub.dex;
+        const provider = await this.getOrCreateProvider(providerKey);
+        provider.reconnect();
+        return provider.subscribe(sub, listener, onStatus);
+    }
+    /**
+     * Stream live fill quotes for `params.symbol` on `params.provider`, lazily
+     * creating the provider's WS connection. The provider's WS plugin layers the
+     * quote on its orderbook channel, so a concurrent orderbook subscription on
+     * the same market shares one wire subscription. Returns an unsubscribe
+     * function.
+     *
+     * @throws {PerpsError} When no WS provider factory is registered for
+     *   `params.provider`, or no market matches the symbol+type.
+     * @public
+     */
+    async subscribeQuote(params, onQuote) {
+        const provider = await this.getOrCreateProvider(params.provider);
+        return provider.subscribeQuote({
+            symbol: params.symbol,
+            side: params.side,
+            size: params.size,
+            type: params.type,
+        }, onQuote);
+    }
+    /**
+     * Close every open provider WS connection and drop all cached providers.
+     *
+     * @public
+     */
+    close() {
+        for (const p of this.providers.values()) {
+            p.close();
+        }
+        this.providers.clear();
+        this.initPromises.clear();
+    }
+    /**
+     * Reconnect an already-created provider when its socket reached terminal
+     * `disconnected`. Safe no-op when the provider is unknown or not terminal.
+     *
+     * @public
+     */
+    reconnect(provider) {
+        this.providers.get(provider)?.reconnect();
+    }
+    async getOrCreateProvider(provider) {
+        const existing = this.providers.get(provider);
+        if (existing) {
+            return existing;
+        }
+        return cachePromise(() => this.initPromises.get(provider), (p) => {
+            if (p) {
+                this.initPromises.set(provider, p);
+            }
+            else {
+                this.initPromises.delete(provider);
+            }
+        }, () => this.initProvider(provider));
+    }
+    async initProvider(provider) {
+        const factory = this.options.wsProviders?.[provider];
+        if (factory === undefined) {
+            throw new PerpsError(PerpsErrorCode.SDKError, `No WS provider factory registered for '${provider}'. Pass one via ` +
+                'new PerpsWsClient(client, { wsProviders: { [key]: factory } }).');
+        }
+        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.categories ?? []);
+        const providerConfig = this.client.config.providers?.[provider];
+        const configuredMarkets = providerConfig?.markets;
+        const markets = (configuredMarkets
+            ? allMarkets.filter((m) => configuredMarkets.includes(m.id))
+            : allMarkets).map((m) => m.id);
+        const wsProvider = factory({
+            provider,
+            wsUrl: providerInfo.wsUrl,
+            markets,
+            client: this.client,
+        });
+        this.providers.set(provider, wsProvider);
+        return wsProvider;
+    }
+}
+//# sourceMappingURL=PerpsWsClient.js.map

package/dist/esm/websocket/PerpsWsClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PerpsWsClient.js","sourceRoot":"","sources":["../../../src/websocket/PerpsWsClient.ts"],"names":[],"mappings":"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"}