@blackcube/xgate-sdk 0.25.0 → 0.25.2

package/README.md

@@ -5,6 +5,46 @@ un catalogue, des bougies, des prix, un portefeuille et du trading — quelle qu
 
 > **SDK communautaire / non officiel.** Non affilié aux exchanges couverts. Usage à vos risques.
 
+## ⚠️ Si ça ne passe pas par XGate, arrête-toi
+
+**XGate est la seule porte vers les venues.** Importer un `@blackcube/*-sdk` directement dans une
+application, c'est contourner — et un contournement ne se voit pas : le code compile, les tests
+passent, et la divergence n'apparaît qu'en production, sur la venue que personne n'a exercée.
+
+Tu t'apprêtes à écrire quelque chose qui ne passe pas par XGate ? **Il n'y a que deux cas, et
+aucun des deux ne consiste à contourner.**
+
+**1. Tu n'as pas trouvé — c'est le cas le plus fréquent.** La méthode existe sous un autre nom. Le
+vocabulaire d'XGate n'est celui d'aucune venue : il est unifié.
+
+| tu cherches | c'est | et pas |
+|---|---|---|
+| passer un ordre | `openWithProtection` | `place` — qui n'existe pas ici |
+| fermer | `closePosition` | un ordre marché `reduceOnly` à la main |
+| modifier un stop | `moveStop` | annuler puis reposer |
+| le levier | `setLeverage` | `updateLeverage` |
+| l'état du compte | `accountInfo` | `getAccountInfo` |
+| l'historique des ordres | `orderHistory` | `getHistory` |
+| le funding payé | `fundingHistory` | `getFundingHistory` |
+| les exécutions en direct | `WsTradesService.subscribe` | `subscribeUserTrades` |
+| N marchés en temps réel | `CandlesStreamRegistry.of()` | N × `WsCandlesService` |
+
+**Vérifie avant de conclure** : `grep -rn "public " node_modules/@blackcube/xgate-sdk/dist/index.d.ts`
+ou la table des services plus bas. Ce README documente **35 méthodes publiques sur 35** — si tu ne
+trouves pas, cherche encore.
+
+**2. C'est un vrai trou.** Alors **dis-le, et discutes-en** — ne le comble pas dans ton coin.
+Certaines absences sont des **décisions** : `place`, `placeProtection`, `cancelProtection`,
+`subscribeAllCandles`, `subscribePrices` n'existent pas *exprès*, et les raisons sont écrites plus
+bas. Les recréer côté application, c'est réintroduire ce qui a été retiré après incident.
+
+D'autres absences sont réelles — `getOrderBook`, `edit`, `getExchangeInfo`, `withdraw`,
+`subscribeOrderBook`, `subscribeBbo`. Elles se comblent **dans XGate**, où elles profitent à tous
+les appelants et sont exercées contre les venues, jamais dans l'application.
+
+> **Le réflexe qui trahit le contournement** : tu es sur le point d'écrire `import { Hyperliquid }
+> from '@blackcube/hyperliquid-sdk'` dans du code applicatif. Arrête-toi là.
+
 ## Installation
 
 ```bash

package/dist/index.cjs

@@ -97,6 +97,24 @@ function toCandle(wire, xex, interval, quote) {
   };
 }
 
+// src/helpers/socket-error.ts
+function lisible(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  const event = error;
+  if (event !== null && typeof event === "object") {
+    const message = event.message ?? event.error?.message;
+    if (typeof message === "string" && message !== "") {
+      return message;
+    }
+    if (typeof event.type === "string" && event.type !== "") {
+      return `\xE9v\xE9nement \xAB ${event.type} \xBB`;
+    }
+  }
+  return String(error);
+}
+
 // src/helpers/ws-limits.ts
 var WS_SUBSCRIPTION_LIMITS = {
   aster: 200,
@@ -266,20 +284,36 @@ var CandlesStreamService = class {
   unsubscribes = [];
   /** Le plafond de souscriptions documenté par la venue, ou `null` si personne ne l'a publié. */
   maxSubscriptions;
+  /**
+   * Notifié quand le flux meurt — après que les souscriptions ont été coupées.
+   *
+   * **Ce crochet a remplacé un `throw`.** Lever depuis un rappel de socket ne remonte à aucun
+   * appelant : l'exception sort en `unhandledRejection` et **tue le process entier**, ce qui est
+   * arrivé le 2026-08-13 sur Blips par un autre chemin. « Impossible à ignorer » et « fatal pour
+   * tout le monde » ne sont pas la même chose : la première est une garantie, la seconde une panne.
+   *
+   * Le contrat reste franc — le flux est coupé, il ne repartira pas tout seul, et le silence est
+   * journalisé en `.error` de toute façon. Mais c'est à l'appelant de décider ce qu'il en fait :
+   * rouvrir, basculer de venue, ou s'arrêter.
+   */
+  onFailure = null;
   /**
    * Ouvre le flux sur une LISTE de marchés, sur une seule socket.
    *
-   * **UNE ERREUR DE FLUX COUPE TOUT, PUIS LÈVE.** Elle n'arrive pas à la souscription : mesuré le
+   * **UNE ERREUR DE FLUX COUPE TOUT, PUIS NOTIFIE.** Elle n'arrive pas à la souscription : mesuré le
    * 2026-08-07, la venue accepte un symbole inconnu sans broncher, puis ferme la connexion en le
    * découvrant. Le SDK reconnecte, elle referme — cinq cycles en douze secondes, et sur une socket
    * partagée **tous** les marchés valides cessent de recevoir, en silence.
    *
    * On refuse cette boucle : à la première erreur, les souscriptions sont coupées, l'incident est
-   * journalisé en `error`, et l'exception part. Un flux à moitié mort qui se tait coûte plus cher
-   * qu'un arrêt franc — on ne découvre le premier qu'en constatant l'absence de données.
+   * journalisé en `error`, et {@link onFailure} est notifié. Un flux à moitié mort qui se tait
+   * coûte plus cher qu'un arrêt franc — on ne découvre le premier qu'en constatant l'absence de
+   * données.
    *
-   * ⚠️ L'exception naît dans un rappel de socket : elle ne remonte pas à l'appelant de `start()`,
-   * elle sort en erreur non capturée. C'est délibéré — elle doit être impossible à ignorer.
+   * ⚠️ **On ne lève pas depuis le rappel de socket.** Une exception née là ne remonte à aucun
+   * appelant de `start()` : elle sort en `unhandledRejection` et emporte le process entier — pas
+   * seulement le flux fautif, mais les crons et tout ce qui tournait à côté. C'est {@link onFailure}
+   * qui porte l'information, et l'appelant qui décide.
    *
    * **binance et bybit ne remontent pas encore leurs erreurs** : leur client gère la fermeture en
    * interne sans l'exposer. Sur ces deux venues, la boucle silencieuse reste possible.
@@ -291,7 +325,7 @@ var CandlesStreamService = class {
         const raison = lisible(error);
         this.logger.error(`${this.xex} : erreur de flux \u2014 ${raison}. Souscriptions coup\xE9es.`);
         this.stop();
-        throw new Error(`stream(${this.xex}) : flux interrompu \u2014 ${raison}`);
+        this.onFailure?.(new Error(`stream(${this.xex}) : flux interrompu \u2014 ${raison}`));
       };
     }
     for (const symbolXex of symbolsXex) {
@@ -374,22 +408,6 @@ exports.CandlesStreamRegistry = class CandlesStreamRegistry {
 exports.CandlesStreamRegistry = __decorateClass([
   common.Injectable()
 ], exports.CandlesStreamRegistry);
-function lisible(error) {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  const event = error;
-  if (event !== null && typeof event === "object") {
-    const message = event.message ?? event.error?.message;
-    if (typeof message === "string" && message !== "") {
-      return message;
-    }
-    if (typeof event.type === "string" && event.type !== "") {
-      return `\xE9v\xE9nement \xAB ${event.type} \xBB`;
-    }
-  }
-  return String(error);
-}
 
 // src/enums/timeframe.enums.ts
 var Timeframe = /* @__PURE__ */ ((Timeframe2) => {
@@ -1821,6 +1839,8 @@ exports.WalletService = __decorateClass([
 ], exports.WalletService);
 exports.WsCandlesService = class WsCandlesService {
   logger = new common.Logger(exports.WsCandlesService.name);
+  /** Un client temps réel par venue — voir {@link wireOf}. La clé EST la venue. */
+  wires = /* @__PURE__ */ new Map();
   /**
    * Souscrit aux bougies d'un marché chez une venue. Rend la fonction de désabonnement.
    *
@@ -1836,9 +1856,12 @@ exports.WsCandlesService = class WsCandlesService {
   subscribe(xex, query, handler) {
     const quote = this.quoteOf(query.symbol);
     this.logger.log(`souscription bougies ${query.symbol} ${query.interval} sur ${xex}`);
-    return createPublicXex(xex).ws().subscribeCandles({ name: query.symbol, interval: query.interval }, (wire) => {
-      handler(toCandle(wire, xex, query.interval, quote));
-    });
+    return this.wireOf(xex).subscribeCandles(
+      { name: query.symbol, interval: query.interval },
+      (wire) => {
+        handler(toCandle(wire, xex, query.interval, quote));
+      }
+    );
   }
   /**
    * Souscrit au MÊME marché chez plusieurs venues, avec un seul handler.
@@ -1865,6 +1888,35 @@ exports.WsCandlesService = class WsCandlesService {
       }
     };
   }
+  /**
+   * Le client temps réel d'une venue — **créé une seule fois, donc UNE SOCKET PAR VENUE**.
+   *
+   * C'est la règle que `CandlesStreamService` énonce déjà et que ce service violait : chaque
+   * `subscribe()` appelait `createPublicXex(xex)`, qui construit une façade NEUVE. Or la façade
+   * mémoïse son client temps réel (`unifiedWs()`), et c'est lui qui porte la socket : une façade
+   * par souscription, c'est une socket par souscription.
+   *
+   * Mesuré le 2026-08-13 sur Blips : 1 104 souscriptions ont ouvert **1 104 sockets** sur sept
+   * venues, quand hyperliquid n'en accepte que 10 par IP. Les descripteurs s'épuisent, les venues
+   * refusent, et chaque connexion refusée rejetait une promesse que personne n'attendait — le
+   * process entier mourait deux minutes après l'ouverture des flux. Ici : **sept sockets**.
+   *
+   * Rien à fermer explicitement : le ref-count vit dans les SDK (`refs += 1` / `release()`), donc
+   * la socket se ferme d'elle-même au dernier désabonnement de la venue, et se rouvre au suivant.
+   */
+  wireOf(xex) {
+    let wire = this.wires.get(xex);
+    if (wire === void 0) {
+      wire = createPublicXex(xex).ws();
+      if ("onError" in wire) {
+        wire.onError = (error) => {
+          this.logger.error(`${xex} : erreur de flux \u2014 ${lisible(error)}`);
+        };
+      }
+      this.wires.set(xex, wire);
+    }
+    return wire;
+  }
   /** Voir `CandlesService.quoteOf` : la cotation se déduit du symbole natif, faute d'être publiée. */
   quoteOf(symbolXex) {
     const parts = symbolXex.split("-");