@blackcube/xgate-sdk 0.25.0 → 0.25.1

package/dist/index.d.cts

@@ -282,6 +282,8 @@ type Unsubscribe = () => void;
  */
 declare class WsCandlesService {
     private readonly logger;
+    /** Un client temps réel par venue — voir {@link wireOf}. La clé EST la venue. */
+    private readonly wires;
     /**
      * Souscrit aux bougies d'un marché chez une venue. Rend la fonction de désabonnement.
      *
@@ -308,6 +310,23 @@ declare class WsCandlesService {
         symbol: string;
         interval: Timeframe;
     }, handler: (candle: ICandle) => void): Unsubscribe;
+    /**
+     * 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.
+     */
+    private wireOf;
     /** Voir `CandlesService.quoteOf` : la cotation se déduit du symbole natif, faute d'être publiée. */
     private quoteOf;
 }
@@ -340,23 +359,39 @@ declare class CandlesStreamService {
     private readonly unsubscribes;
     /** Le plafond de souscriptions documenté par la venue, ou `null` si personne ne l'a publié. */
     readonly maxSubscriptions: number | null;
+    /**
+     * 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: ((error: Error) => void) | null;
     constructor(xex: XgateEx, 
     /** Le marché écouté. Le comptant n'est servi que par binance et bybit. */
     kind?: MarketKind);
     /**
      * 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.
-     *
-     * ⚠️ 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.
+     * 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.
+     *
+     * ⚠️ **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.

package/dist/index.d.ts

@@ -282,6 +282,8 @@ type Unsubscribe = () => void;
  */
 declare class WsCandlesService {
     private readonly logger;
+    /** Un client temps réel par venue — voir {@link wireOf}. La clé EST la venue. */
+    private readonly wires;
     /**
      * Souscrit aux bougies d'un marché chez une venue. Rend la fonction de désabonnement.
      *
@@ -308,6 +310,23 @@ declare class WsCandlesService {
         symbol: string;
         interval: Timeframe;
     }, handler: (candle: ICandle) => void): Unsubscribe;
+    /**
+     * 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.
+     */
+    private wireOf;
     /** Voir `CandlesService.quoteOf` : la cotation se déduit du symbole natif, faute d'être publiée. */
     private quoteOf;
 }
@@ -340,23 +359,39 @@ declare class CandlesStreamService {
     private readonly unsubscribes;
     /** Le plafond de souscriptions documenté par la venue, ou `null` si personne ne l'a publié. */
     readonly maxSubscriptions: number | null;
+    /**
+     * 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: ((error: Error) => void) | null;
     constructor(xex: XgateEx, 
     /** Le marché écouté. Le comptant n'est servi que par binance et bybit. */
     kind?: MarketKind);
     /**
      * 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.
-     *
-     * ⚠️ 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.
+     * 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.
+     *
+     * ⚠️ **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.

package/dist/index.js

@@ -95,6 +95,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,
@@ -264,20 +282,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.
@@ -289,7 +323,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) {
@@ -372,22 +406,6 @@ var CandlesStreamRegistry = class {
 CandlesStreamRegistry = __decorateClass([
   Injectable()
 ], 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) => {
@@ -1819,6 +1837,8 @@ WalletService = __decorateClass([
 ], WalletService);
 var WsCandlesService = class {
   logger = new Logger(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.
    *
@@ -1834,9 +1854,12 @@ var WsCandlesService = class {
   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.
@@ -1863,6 +1886,35 @@ var WsCandlesService = class {
       }
     };
   }
+  /**
+   * 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("-");