@syldel/hl-shared-types 0.0.21 → 0.0.23

package/LICENSE.MD

@@ -1,5 +1,5 @@
-Copyright (c) 2026, Syl-Studio Inc. c/o Syl. D.
-
-Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
-
+Copyright (c) 2026, Syl-Studio Inc. c/o Syl. D.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/dist/interfaces/perp/balance.interfaces.d.ts

@@ -1,15 +1,52 @@
 import { DecimalString, Timestamp } from '../common';
 /**
  * Leverage configuration for a perpetual position.
+ *
+ * ============================================================================
+ * UNE UNION, PARCE QUE LES DEUX MODES NE PORTENT PAS LES MÊMES CHAMPS
+ *
+ * `rawUsd` était déclaré **obligatoire** pour les deux modes, et le faux
+ * gateway devait donc mentir par une assertion de type pour construire une
+ * position cross plausible — exactement ce qu'un double n'a pas le droit de
+ * faire.
+ *
+ * La forme vient du **SDK Python officiel** (`hyperliquid-dex/
+ * hyperliquid-python-sdk`, `hyperliquid/utils/types.py`), qui déclare la même
+ * union, discriminée sur `type` :
+ *
+ *     CrossLeverage    = {"type": Literal["cross"],    "value": int}
+ *     IsolatedLeverage = {"type": Literal["isolated"], "value": int,
+ *                         "rawUsd": str}
+ *     Leverage = Union[CrossLeverage, IsolatedLeverage]
+ *
+ * Deux relevés la recoupent, chacun pour une branche : les captures du gateway
+ * du 2026-09-22 n'ont que des leviers `cross`, tous en `{ type, value }` nus ;
+ * l'exemple de la doc de `clearinghouseState` n'a qu'une position isolée, qui
+ * porte `rawUsd: "-95.059824"`. Aucun des deux ne couvre l'autre branche — le
+ * SDK, lui, les couvre toutes les deux.
+ *
+ * Pourquoi l'union et non `rawUsd?: DecimalString` : l'optionnel rendrait
+ * `lev.rawUsd` lisible sans vérifier `type`, et `Number(undefined)` rend `NaN`
+ * sans un mot. L'union en fait une erreur de compilation. Et si un cross
+ * portait un jour `rawUsd`, le coût de s'être trompé ici est nul — personne ne
+ * lit ce champ, il serait simplement invisible — là où le coût du `NaN`
+ * silencieux se paierait sur un dimensionnement.
+ * ============================================================================
  */
-export interface HLPerpLeverage {
-    /** Notional value in USD used for leverage calculation. */
-    rawUsd: DecimalString;
+export type HLPerpLeverage = {
     /** Margin mode used for the position. */
-    type: 'isolated' | 'cross';
+    type: 'cross';
     /** Current leverage multiplier. */
     value: number;
-}
+} | {
+    type: 'isolated';
+    value: number;
+    /**
+     * Notional value in USD used for leverage calculation. Propre à l'isolé,
+     * où la marge est cantonnée à la position.
+     */
+    rawUsd: DecimalString;
+};
 /**
  * Funding payments accumulated for a perpetual position.
  */
@@ -33,8 +70,25 @@ export interface HLPerpPositionDetail {
     entryPx: DecimalString;
     /** Leverage configuration. */
     leverage: HLPerpLeverage;
-    /** Estimated liquidation price. */
-    liquidationPx: DecimalString;
+    /**
+     * Estimated liquidation price, **`null`** quand l'exchange n'en publie pas.
+     *
+     * Relevé le 2026-09-22 dans les captures réelles du gateway : sur 6 états
+     * distincts d'une même paire (`xyz:MU`, cross), les 3 **longs** rendent
+     * `null` et les 2 **shorts** rendent une chaîne. Un seul coin sur un seul
+     * dex : cette corrélation avec le sens de la position n'explique rien, et je
+     * ne connais pas la règle.
+     *
+     * Ce qui est établi suffit pourtant, et c'est asymétrique : une nullité se
+     * prouve par un seul contre-exemple, alors que la non-nullité demanderait de
+     * l'avoir épuisée. Trois `null` mesurés closent la question du type ; ils ne
+     * disent rien de *quand*.
+     *
+     * Conséquence pour un consommateur : le `null` s'écarte, il ne se convertit
+     * pas. `Number(null)` rend `0`, et un prix de liquidation à zéro est le plus
+     * rassurant des mensonges — il paraît infiniment loin du prix courant.
+     */
+    liquidationPx: DecimalString | null;
     /** Margin currently used by the position. */
     marginUsed: DecimalString;
     /** Maximum allowed leverage for this market. */
@@ -52,7 +106,17 @@ export interface HLPerpPositionDetail {
  * Wrapper describing a perpetual asset position.
  */
 export interface HLPerpAssetPosition {
-    /** Position details (null if no active position). */
+    /**
+     * Position details (null if no active position).
+     *
+     * ⚠️ Laissé nullable bien qu'aucune des entrées relevées le 2026-09-22 ne
+     * soit nulle : des observations d'une valeur présente ne prouvent pas qu'elle
+     * le soit toujours — et celles-ci portent sur une seule paire —, la doc nomme
+     * le cas, et deux des trois lecteurs du bot le gardaient déjà. Le troisième
+     * ne le gardait pas, et levait un `Cannot read properties of null` juste
+     * après une entrée remplie : c'est ce défaut qui a fait garder ce `| null`
+     * plutôt que le resserrer.
+     */
     position: HLPerpPositionDetail | null;
     /** Position mode configuration. */
     type: 'oneWay' | 'hedged';

package/dist/interfaces/perp/meta.interfaces.d.ts

@@ -1,4 +1,26 @@
 import { DecimalString } from '../common';
+/**
+ * ============================================================================
+ * DÉCLARER CE QUE L'EXCHANGE REND, PAS CE QU'IL POURRAIT RENDRE
+ *
+ * Les champs ci-dessous ont été relevés le 2026-10-01 sur les cinq dex vivants
+ * (`''`, `xyz`, `para`, `mkts`, `io`) : 434 entrées d'univers et 363 contextes
+ * d'actif, via `meta` et `metaAndAssetCtxs`. Les commentaires portent ces
+ * comptes parce qu'un type optimiste coûte plus cher qu'un type absent : tant
+ * que `midPx` était déclaré `string`, `Number(ctx.midPx)` rendait **`0`** sur
+ * les marchés délistés — un prix, pas une erreur.
+ *
+ * Deux traitements, selon ce que l'absence du champ signifie déjà :
+ *
+ * - **Drapeau de présence** (`onlyIsolated`, `isDelisted`) : l'absence porte le
+ *   sens complémentaire, donc une seule valeur est utile et le type la fixe
+ *   (`?: true`). Écrire `false` serait redondant, et dans un double ce serait
+ *   rendre une forme que l'exchange ne rend pas.
+ * - **Dimension à valeurs** (`growthMode`, `marginMode`, `deployerFeeScale`) :
+ *   d'autres valeurs sont plausibles même si une seule a été observée, donc le
+ *   type reste ouvert et le commentaire dit ce qui a été vu.
+ * ============================================================================
+ */
 /**
  * Metadata describing a perpetual market.
  */
@@ -9,12 +31,71 @@ export interface HLPerpMarketInfo {
     szDecimals: number;
     /** Maximum leverage allowed. */
     maxLeverage: number;
-    /** Whether the market only supports isolated margin. */
-    onlyIsolated?: boolean;
-    /** Whether the market has been delisted. */
-    isDelisted?: boolean;
-    /** Optional margin mode restriction. */
+    /**
+     * Clé de la table de marge qui s'applique à ce marché, à chercher dans
+     * `HLPerpMeta.marginTables`.
+     *
+     * **Requis**, et non optionnel : présent sur **434/434** marchés des cinq
+     * dex, délistés compris. Le déclarer optionnel n'évitait aucune erreur — il
+     * autorisait seulement des doubles à l'omettre, donc à rendre une forme que
+     * l'exchange ne rend jamais.
+     */
+    marginTableId: number;
+    /**
+     * Présent **uniquement** sur les marchés restreints à la marge isolée, et
+     * toujours accompagné de `marginMode` (0 contre-exemple sur 434).
+     *
+     * ⚠️ Ce champ n'est **pas** déprécié, contrairement à ce que suggère le dex
+     * principal : il n'y survit que sur 8 marchés, tous délistés. Les HIP-3 le
+     * rendent partout — `io` 8/8 vivants, `xyz` 90/110, `para` 26/29, soit 126
+     * marchés vivants au total. Le marquer `@deprecated` ferait clignoter du
+     * code juste.
+     *
+     * `true` et non `boolean` : les 162 occurrences relevées valent `true`.
+     */
+    onlyIsolated?: true;
+    /**
+     * Présent **uniquement** sur les marchés délistés, et toujours à `true` —
+     * c'est ainsi que l'exchange marque un marché mort (doc `meta`, exemple
+     * `LOOM`). Un marché vivant n'a pas la clé du tout.
+     *
+     * `true` et non `boolean`, pour que le compilateur refuse
+     * `isDelisted: false` : écrit dans un double, il rendrait une forme que le
+     * vrai ne rend pas, et c'est précisément ce qu'un double ne doit pas faire.
+     */
+    isDelisted?: true;
+    /**
+     * Restriction de mode de marge. Toujours accompagnée de `onlyIsolated`, dans
+     * les deux sens. Valeurs relevées : `strictIsolated` sur 52 marchés du dex
+     * principal et de `xyz`, `noCross` sur 129 HIP-3.
+     */
     marginMode?: 'strictIsolated' | 'noCross';
+    /**
+     * Relevé sur les quatre dex HIP-3, jamais sur le principal (0/234).
+     *
+     * Laissé ouvert (`string`) bien que `'enabled'` soit la seule valeur vue sur
+     * 154 marchés : le champ nomme un mode, d'autres états sont plausibles, et il
+     * **subsiste sur 13 marchés délistés** — donc il n'est pas tenu à jour et ne
+     * dit rien de la vivacité d'un marché. Pour ça, `isDelisted`.
+     */
+    growthMode?: string;
+    /**
+     * Multiplicateur appliqué aux frais du déployeur. Relevé sur les quatre dex
+     * HIP-3 (200 marchés), jamais sur le principal. Valeurs vues : `'1.0'` et
+     * `'0.5'` — laissé ouvert, c'est une échelle.
+     */
+    deployerFeeScale?: DecimalString;
+    /**
+     * Date du dernier changement de `deployerFeeScale`.
+     *
+     * ⚠️ Une **chaîne**, malgré le `Time` du nom, et une chaîne piégeuse :
+     * `"2025-11-23T17:37:10.033211662"` — 9 décimales de seconde et **aucun
+     * fuseau**. `Date.parse` l'accepte sans broncher, tronque les nanosecondes
+     * **et l'interprète en heure locale** : mesuré, cette valeur donne
+     * `16:37:10Z` sur une machine en UTC+1 et un autre instant ailleurs. Donc
+     * jamais `number`, et pas de parsing sans imposer le fuseau explicitement.
+     */
+    lastFeeScaleChangeTime?: string;
 }
 /**
  * Margin tier defining leverage limits for a position size range.
@@ -83,53 +164,77 @@ export interface HLPerpMarketUniverse extends HLPerpMarketInfo {
 export interface HLPerpAssetCtx {
     /** Daily notional trading volume. */
     dayNtlVlm: string;
+    /**
+     * Volume quotidien exprimé dans l'actif de base, là où `dayNtlVlm` l'exprime
+     * en notionnel. Relevé sur 363/363 contextes ; il traversait déjà le fil sans
+     * qu'aucun type ne le déclare.
+     */
+    dayBaseVlm: string;
     /** Current funding rate. */
     funding: string;
-    /** Impact price levels used for slippage estimation. */
-    impactPxs: string[];
-    /** Mark price used for PnL calculations. */
+    /**
+     * Prix d'impact estimés, `[bid, ask]`.
+     *
+     * **`null`** quand l'exchange n'a pas de carnet à montrer : mesuré sur 75/363
+     * contextes, tous délistés. Le tableau, lui, fait toujours exactement deux
+     * entrées quand il existe (288/288).
+     */
+    impactPxs: string[] | null;
+    /**
+     * Mark price used for PnL calculations. Jamais `null` sur les 363 contextes
+     * relevés, délistés compris — c'est le seul prix sur lequel on peut compter.
+     */
     markPx: string;
-    /** Mid price between best bid and ask. */
-    midPx: string;
+    /**
+     * Prix milieu du spread, **`null`** sur les mêmes 75 contextes délistés.
+     *
+     * C'est le champ qui a motivé ce chantier. Déclaré `string`, il faisait
+     * rendre `0` à `Number(ctx.midPx)` — et `0` n'est pas une absence de réponse
+     * mais une réponse affirmative : dans une comparaison `mid >= oracle`, un
+     * `NaN` aurait rendu les deux côtés `false`, `0` tranche. Un consommateur
+     * doit donc écarter le `null` avant de calculer, pas le convertir.
+     */
+    midPx: string | null;
     /** Total open interest. */
     openInterest: string;
     /** Oracle price reference. */
     oraclePx: string;
-    /** Price premium relative to the oracle. */
-    premium: string;
+    /** Price premium relative to the oracle. **`null`** sur les mêmes 75. */
+    premium: string | null;
     /** Previous day's closing price. */
     prevDayPx: string;
 }
 /**
  * Response combining market metadata and runtime context.
+ *
+ * Le premier élément est le **`HLPerpMeta` complet** : relevé le 2026-10-01 sur
+ * `''` et `xyz`, `metaAndAssetCtxs[0]` porte exactement les mêmes trois clés
+ * que `meta` — `universe`, `marginTables`, `collateralToken`. Il était typé
+ * `{ universe }` seul, ce qui rendait le collatéral du dex illisible depuis cet
+ * appel alors qu'il était déjà sur le fil : il fallait un second appel à `meta`
+ * pour obtenir une donnée reçue.
  */
-export type HLPerpMetaAndCtx = [{
-    universe: HLPerpMarketInfo[];
-}, HLPerpAssetCtx[]];
+export type HLPerpMetaAndCtx = [HLPerpMeta, HLPerpAssetCtx[]];
 /**
  * Normalized representation of a perpetual market used by the SDK.
+ *
+ * Étend `HLPerpMarketInfo` au lieu d'en recopier les champs : la copie avait
+ * déjà divergé — `marginTableId` y était déclaré alors qu'il manquait à la
+ * source, et les trois champs HIP-3 traversaient le gateway (`{ ...market }`)
+ * sans qu'aucun des deux types ne les connaisse. Un champ ajouté par l'exchange
+ * se propage maintenant aux deux formes, ou à aucune.
  */
-export interface HLPerpMarket {
+export interface HLPerpMarket extends HLPerpMarketInfo {
     /** Market index in the universe list. */
     index: number;
-    /** Market symbol (e.g. BTC). */
-    name: string;
-    /** Size precision for orders. */
-    szDecimals: number;
-    /** Maximum leverage allowed. */
-    maxLeverage: number;
-    /** Margin table identifier. */
-    marginTableId?: number;
-    /** Whether the market only supports isolated margin mode. */
-    onlyIsolated?: boolean;
-    /** Whether the market has been delisted by the exchange. */
-    isDelisted?: boolean;
-    /** Optional restriction applied to the market margin mode. */
-    marginMode?: 'strictIsolated' | 'noCross';
     /** Current mark price. */
     markPrice?: DecimalString;
-    /** Current mid price. */
-    midPrice?: DecimalString;
+    /**
+     * Current mid price, `null` quand l'exchange n'en publie pas (marché
+     * délisté). `undefined` dit autre chose : la ligne de contexte manquait en
+     * face de l'entrée d'univers — deux incidents, deux diagnostics.
+     */
+    midPrice?: DecimalString | null;
     /** Current funding rate. */
     funding?: DecimalString;
     /** Current open interest. */
@@ -141,8 +246,8 @@ export interface HLPerpMarket {
 export interface HLPerpMarketExtended extends HLPerpMarket {
     /** Oracle price reference. */
     oraclePrice?: DecimalString;
-    /** Premium vs oracle. */
-    premium?: DecimalString;
+    /** Premium vs oracle, `null` sur un marché sans prix milieu. */
+    premium?: DecimalString | null;
     /** Daily notional volume. */
     dayNotionalVolume?: DecimalString;
     /** Estimated bid impact price. */

package/package.json

@@ -1,54 +1,54 @@
-{
-  "name": "@syldel/hl-shared-types",
-  "version": "0.0.21",
-  "description": "Shared TypeScript interfaces and types for Hyperliquid integration.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Syldel/hl-shared-types.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Syldel/hl-shared-types/issues"
-  },
-  "homepage": "https://github.com/Syldel/hl-shared-types#readme",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "test": "jest",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "clean": "rm -rf dist",
-    "build": "npm run lint && npm run test && npm run clean && tsc",
-    "prepublishOnly": "npm run build",
-    "release": "npm run build && npm version patch && npm publish"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "hyperliquid",
-    "trading",
-    "types",
-    "interfaces",
-    "crypto",
-    "exchange",
-    "defi"
-  ],
-  "author": "Syl. D.",
-  "license": "ISC",
-  "devDependencies": {
-    "@types/jest": "^30.0.0",
-    "eslint": "^9.39.2",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-jsonc": "^2.21.0",
-    "eslint-plugin-prettier": "^5.5.5",
-    "jest": "^30.5.2",
-    "jsonc-eslint-parser": "^2.4.2",
-    "prettier": "^3.8.0",
-    "ts-jest": "^29.4.13",
-    "typescript": "^5.3.3",
-    "typescript-eslint": "^8.53.0"
-  }
-}
+{
+  "name": "@syldel/hl-shared-types",
+  "version": "0.0.23",
+  "description": "Shared TypeScript interfaces and types for Hyperliquid integration.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Syldel/hl-shared-types.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Syldel/hl-shared-types/issues"
+  },
+  "homepage": "https://github.com/Syldel/hl-shared-types#readme",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "clean": "rm -rf dist",
+    "build": "npm run lint && npm run test && npm run clean && tsc",
+    "prepublishOnly": "npm run build",
+    "release": "npm run build && npm version patch && npm publish"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "hyperliquid",
+    "trading",
+    "types",
+    "interfaces",
+    "crypto",
+    "exchange",
+    "defi"
+  ],
+  "author": "Syl. D.",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsonc": "^2.21.0",
+    "eslint-plugin-prettier": "^5.5.5",
+    "jest": "^30.5.2",
+    "jsonc-eslint-parser": "^2.4.2",
+    "prettier": "^3.8.0",
+    "ts-jest": "^29.4.13",
+    "typescript": "^5.3.3",
+    "typescript-eslint": "^8.53.0"
+  }
+}