@syldel/hl-shared-types 0.0.20 → 0.0.22

package/dist/interfaces/infos/collateral-balance.interfaces.d.ts

@@ -57,4 +57,28 @@ export type CollateralBalance =
     status: 'unknown-collateral';
     mode: AccountAbstractionMode;
     asset: string;
+}
+/**
+ * Le compte est dans un mode dont ce gateway ne sait pas lire le collatéral.
+ *
+ * Deux cas, et c'est un refus **délibéré** plutôt qu'une approximation :
+ *
+ * - **`portfolioMargin`** réunit plusieurs actifs en un seul portefeuille
+ *   (HYPE, BTC, USDC, USDT à ce jour). Rendre le solde d'un seul d'entre eux
+ *   sous-estimerait le capital, et les agréger demanderait de valoriser HYPE
+ *   et BTC en dollars — donc d'introduire une source de **prix** dans un
+ *   calcul de collatéral. C'est un chantier, pas une ligne ;
+ * - **`dexAbstraction`** est arrêté par l'exchange. La doc le décrit (USDC
+ *   depuis le solde perp, tout autre collatéral depuis le spot), mais aucun
+ *   compte ne permet de l'éprouver — et une implémentation non exercée d'un
+ *   mode qu'on ne peut pas tester vaut moins qu'un refus net.
+ *
+ * L'appelant doit le traiter comme les autres statuts sans montant : ne rien
+ * dimensionner, et le dire. Un nombre plausible aurait traversé tout le
+ * système sans rien déclencher.
+ */
+ | {
+    status: 'unsupported-mode';
+    mode: AccountAbstractionMode;
+    asset: string;
 };

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,6 +1,6 @@
 {
   "name": "@syldel/hl-shared-types",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "Shared TypeScript interfaces and types for Hyperliquid integration.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",