@syldel/hl-shared-types 0.0.22 → 0.0.24

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/README.md

@@ -119,10 +119,48 @@ git push origin main --follow-tags
 
 ---
 
+## 🔍 Avant de déclarer un champ : d'où vient l'information
+
+Chaque champ de ce paquet est une **affirmation sur ce que l'exchange rend**, et les trois
+dépôts la croient. Une affirmation fausse ne se voit pas : elle se paie plus loin, sur un
+dimensionnement ou un affichage. Avant d'ajouter, de resserrer ou d'élargir un type, lire
+[`nest-hyperliquid-gateway/docs/sources.md`](https://github.com/Syldel/nest-hyperliquid-gateway/blob/main/docs/sources.md).
+
+En résumé de ce document :
+
+* **La mesure** (captures du gateway, lectures `/hyperliquid/info/*`) prouve qu'une forme
+  existe, jamais qu'elle soit la seule. Un `null` vu une fois clôt la nullité d'un champ ;
+  mille valeurs présentes ne closent rien. Et un échantillon se décrit honnêtement — 22
+  instantanés d'une même position ne sont pas 22 observations.
+* **La doc officielle** fait autorité sur les noms, et tient sur **un exemple par
+  endpoint** : elle est donc muette sur ce qui varie. Un champ absent d'un exemple n'est ni
+  absent de l'API ni optionnel.
+* **Le SDK Python officiel**
+  ([hyperliquid-dex/hyperliquid-python-sdk](https://github.com/hyperliquid-dex/hyperliquid-python-sdk))
+  est de première partie **et typé** : il tranche les unions, les champs propres à une
+  variante et les valeurs énumérées que la prose laisse en suspens. Mais il ne type pas
+  tout, et son silence n'est pas une réponse.
+* **Les SDK communautaires ne concluent pas.** La page d'API en recommande plusieurs — un en
+  Rust, deux en TypeScript, plus CCXT — et le dit : ils sont écrits par la communauté. Être
+  lié par la doc officielle donne de la visibilité, pas de l'autorité ; ils lisent la même
+  API que nous et peuvent s'être trompés pareil. Ils servent à repérer une question, jamais
+  à la clore — et le piège est celui en TypeScript, dont on a envie de recopier une union
+  toute faite. Il n'existe **aucun SDK TypeScript de première partie**.
+
+`HLPerpLeverage` est le cas d'école : ni les captures (que du `cross`) ni l'exemple de la
+doc (que de l'`isolated`) ne pouvaient trancher, et `hyperliquid/utils/types.py` déclare les
+deux branches. Les types portent leur source et leur date en commentaire — c'est ce qui
+permet de les contredire plus tard au lieu de devoir tout remesurer.
+
+---
+
 ## 📝 Conventions de code
 
 * **Sauts de ligne** : Une ligne vide est automatiquement insérée entre chaque `interface` pour une meilleure lisibilité.
 * **Naming** : Toutes les interfaces commencent par `HL`.
 * **Types stricts** : Usage de `DecimalString` pour la précision financière.
+* **Fins de ligne** : LF partout, imposé par `.gitattributes` et non par la configuration de
+  la machine — le paquet publié embarque du code généré par `tsc`, dont les fins de ligne
+  suivent celles des sources.
 
 ---

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

@@ -1,15 +1,58 @@
 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.
+ *
+ * ⚠️ Ce « officiel » ne se déduit **pas** du nom de l'organisation GitHub, qui
+ * n'est d'ailleurs pas vérifiée (`is_verified: false`). Il repose sur la page
+ * d'API de la documentation, qui distingue ce SDK des bibliothèques
+ * communautaires, et sur PyPI, qui le publie sous `hello@hyperliquid.xyz`. La
+ * chaîne et ses limites : `nest-hyperliquid-gateway/docs/sources.md`.
+ *
+ * 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 +76,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 +112,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/funding.interfaces.d.ts

@@ -0,0 +1,115 @@
+import { DecimalString, Timestamp } from '../common';
+/**
+ * ============================================================================
+ * L'HISTORIQUE DE FUNDING — LE SEUL CHAMP DE CONTEXTE QUI AIT UNE VRAIE SÉRIE
+ *
+ * `fundingHistory` est, au 2026-10-06, le **seul** endpoint d'information qui
+ * rende une série temporelle d'un champ de contexte de marché. Il n'existe
+ * aucun endpoint documenté pour l'historique de l'intérêt ouvert, ni pour celui
+ * des prix d'impact : ces valeurs ne sont lisibles qu'à l'instant courant.
+ *
+ * C'est ce qui décide de ce qu'un moteur de règles peut en faire : une
+ * transformation glissante (z-score, pente, percentile) a besoin d'une série,
+ * donc elle n'est légitime que sur `fundingRate` et `premium`.
+ *
+ * ## Ce qui a été mesuré, le 2026-10-06
+ *
+ * Deux appels, sur six heures, sur `api.hyperliquid.xyz` :
+ *
+ * - **BTC** (vivant) : 6 entrées pour 6 heures — la cadence est bien horaire,
+ *   ce que la documentation confirme (« funding is paid every hour at one
+ *   eighth of the computed rate »). Quatre clés, toutes en chaîne sauf `time`.
+ *   **Aucun nul**, sur aucun champ.
+ * - **MATIC** (délisté) : 6 entrées également, avec `fundingRate: "0.0"` et
+ *   `premium: "0.0"`.
+ * - **xyz:XYZ100** (HIP-3, vivant) : 6 entrées, écarts de 3 600 000 ms ± 20 ms,
+ *   et le `coin` rendu est identique à celui demandé, préfixe compris.
+ *
+ * ⚠️ Les horodatages ne tombent **pas exactement** sur l'heure : les restes
+ * modulo une heure relevés valaient 37, 39, 27, 7, 46 et 24 ms. Aligner une
+ * fenêtre de requête sur l'heure pleine reste correct — `startTime` est
+ * inclusif, donc arrondir vers le bas attrape l'entrée — mais comparer un
+ * horodatage à une frontière d'heure par égalité ne marcherait pas.
+ *
+ * ## ⚠️ Trois pièges que ces mesures révèlent
+ *
+ * **1. `"0.0"` a trois significations différentes, et rien ne les distingue
+ * dans cette réponse.** Mesuré le 2026-10-06 via `perpDexs` :
+ *
+ * - un **marché délisté** rend `"0.0"` (MATIC) ;
+ * - un **marché vivant et sain** peut rendre `"0.0"` en permanence, parce que
+ *   son dex déclare un multiplicateur de funding nul : `assetToFundingMultiplier`
+ *   vaut `0.0` sur **tous** les actifs de `flx` et de `vntl` ;
+ * - et un financement réellement nul à cette heure-là.
+ *
+ * Une règle du genre `funding <= 0` serait donc vraie en permanence sur des
+ * marchés parfaitement vivants. Un consommateur doit croiser cette série avec
+ * `isDelisted` (voir `HLPerpMarketInfo`) **et** avec le multiplicateur du dex
+ * (voir `HLPerpDex.assetToFundingMultiplier`). L'API fournit ici elle-même la
+ * valeur de repli plausible et fausse que ce dépôt refuse d'habitude de
+ * fabriquer.
+ *
+ * **2. Un seuil de funding absolu n'est pas transposable d'un marché à
+ * l'autre.** Les multiplicateurs relevés vont de `0.0` (`flx`, `vntl`) à
+ * `0.000001` (`cash`), `0.01` à `1.0` (`hyna`, qui les fait varier **par
+ * actif** dans un même dex), `0.1` à `0.6` (`para`), `0.125` à `0.5` (`io`),
+ * `0.5` partout sur `xyz`. Trois dex n'en déclarent aucun. Un `funding >
+ * 0.00001` serait donc courant sur l'un et impossible sur l'autre : ce champ
+ * se compare **relativement** (z-score, percentile) ou normalisé par le
+ * multiplicateur, jamais à une constante écrite en dur.
+ *
+ * **3. `fundingRate` est souvent constant.** Sur BTC, les trois heures relevées
+ * valaient toutes `0.0000125`, soit exactement le plancher (un huitième de
+ * 0,01 %) ; sur `xyz:XYZ100`, toutes `0.00000625`, soit ce même plancher
+ * multiplié par le `0.5` du dex. Une transformation glissante sur un taux au
+ * plancher voit une série plate : son écart-type est nul, et un z-score n'y a
+ * aucun sens. `premium`, lui, varie en continu sur les deux marchés — c'est la
+ * série informative des deux.
+ *
+ * ## `premium` ici n'est pas `premium` dans `metaAndAssetCtxs`
+ *
+ * La documentation dit que « the premium is sampled **every 5 seconds and
+ * averaged over the hour** », et que `premium = impact_price_difference /
+ * oracle_price`. Le champ rendu ici est donc une **moyenne horaire** sur
+ * environ 720 échantillons, là où le `premium` d'un contexte d'actif est la
+ * lecture de l'instant. Les deux portent le même nom et ne sont pas la même
+ * quantité.
+ * ============================================================================
+ */
+/**
+ * Une entrée de l'historique de funding, telle que `fundingHistory` la rend.
+ *
+ * Aucun champ n'est optionnel ni nullable : mesuré sur un marché vivant **et**
+ * sur un marché délisté, l'endpoint rend toujours les quatre, et rend `"0.0"`
+ * plutôt que `null` quand il n'y a rien à payer.
+ */
+export interface HLFundingHistoryEntry {
+    /** Le marché concerné, tel que demandé (ex. `BTC`, `xyz:XYZ100`). */
+    coin: string;
+    /**
+     * Le taux **horaire** réellement appliqué, soit un huitième du taux calculé
+     * sur 8 heures. `"0.0"` sur un marché délisté — voir l'en-tête.
+     */
+    fundingRate: DecimalString;
+    /**
+     * La prime moyenne de l'heure : `impact_price_difference / oracle_price`,
+     * échantillonnée toutes les 5 secondes et moyennée. Peut être négative.
+     */
+    premium: DecimalString;
+    /** Début de l'heure de funding, en millisecondes. */
+    time: Timestamp;
+}
+/**
+ * Les paramètres de `fundingHistory`.
+ *
+ * ⚠️ À plat dans le corps de la requête, contrairement à `candleSnapshot` qui
+ * imbrique les siens sous une clé `req`. Deux endpoints voisins, deux formes :
+ * c'est le genre d'écart qui se découvre par un appel qui échoue.
+ */
+export interface HLFundingHistoryRequest {
+    coin: string;
+    /** Inclusif, en millisecondes. Requis. */
+    startTime: Timestamp;
+    /** Inclusif. Par défaut, l'instant courant. */
+    endTime?: Timestamp;
+}

package/dist/interfaces/perp/funding.interfaces.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,3 +1,4 @@
 export * from './balance.interfaces';
 export * from './meta.interfaces';
 export * from './dexs.interfaces';
+export * from './funding.interfaces';

package/dist/interfaces/perp/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./balance.interfaces"), exports);
 __exportStar(require("./meta.interfaces"), exports);
 __exportStar(require("./dexs.interfaces"), exports);
+__exportStar(require("./funding.interfaces"), exports);

package/package.json

@@ -1,54 +1,54 @@
-{
-  "name": "@syldel/hl-shared-types",
-  "version": "0.0.22",
-  "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.24",
+  "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"
+  }
+}