@pythnetwork/pyth-lazer-sdk 5.2.1 → 6.2.0

package/dist/cjs/client.cjs

@@ -17,27 +17,20 @@ const UINT16_NUM_BYTES = 2;
 const UINT32_NUM_BYTES = 4;
 const UINT64_NUM_BYTES = 8;
 class PythLazerClient {
-    token;
+    logger;
     metadataServiceUrl;
     priceServiceUrl;
-    logger;
+    token;
     wsp;
-    constructor(token, metadataServiceUrl, priceServiceUrl, logger, wsp){
-        this.token = token;
+    abortSignal;
+    constructor({ abortSignal, logger, metadataServiceUrl, priceServiceUrl, token, wsp }){
+        this.abortSignal = abortSignal;
+        this.logger = logger;
         this.metadataServiceUrl = metadataServiceUrl;
         this.priceServiceUrl = priceServiceUrl;
-        this.logger = logger;
+        this.token = token;
         this.wsp = wsp;
-    }
-    /**
-   * Gets the WebSocket pool. If the WebSocket pool is not configured, an error is thrown.
-   * @throws Error if WebSocket pool is not configured
-   * @returns The WebSocket pool
-   */ getWebSocketPool() {
-        if (!this.wsp) {
-            throw new Error("WebSocket pool is not available. Make sure to provide webSocketPoolConfig when creating the client.");
-        }
-        return this.wsp;
+        this.bindHandlers();
     }
     /**
    * Creates a new PythLazerClient instance.
@@ -48,12 +41,20 @@ class PythLazerClient {
         const metadataServiceUrl = (config.metadataServiceUrl ?? _constants.DEFAULT_METADATA_SERVICE_URL).replace(/\/+$/, "");
         const priceServiceUrl = (config.priceServiceUrl ?? _constants.DEFAULT_PRICE_SERVICE_URL).replace(/\/+$/, "");
         const logger = config.logger ?? _tslog.dummyLogger;
-        // If webSocketPoolConfig is provided, create a WebSocket pool and block until at least one connection is established.
-        let wsp;
-        if (config.webSocketPoolConfig) {
-            wsp = await _websocketpool.WebSocketPool.create(config.webSocketPoolConfig, token, logger);
-        }
-        return new PythLazerClient(token, metadataServiceUrl, priceServiceUrl, logger, wsp);
+        // the prior API was mismatched, in that it marked a websocket pool as optional,
+        // yet all internal code on the Pyth Pro client used it and threw if it didn't exist.
+        // now, the typings indicate it's no longer optional and we don't sanity check
+        // if it's set
+        const wsp = await _websocketpool.WebSocketPool.create(config.webSocketPoolConfig, token, config.abortSignal, logger);
+        const client = new PythLazerClient({
+            abortSignal: config.abortSignal,
+            logger,
+            metadataServiceUrl,
+            priceServiceUrl,
+            token,
+            wsp
+        });
+        return client;
     }
     /**
    * Adds a message listener that receives either JSON or binary responses from the WebSocket connections.
@@ -61,9 +62,8 @@ class PythLazerClient {
    * @param handler - Callback function that receives the parsed message. The message can be either a JSON response
    * or a binary response containing EVM, Solana, or parsed payload data.
    */ addMessageListener(handler) {
-        const wsp = this.getWebSocketPool();
-        wsp.addMessageListener(async (data)=>{
-            if (typeof data == "string") {
+        this.wsp.addMessageListener(async (data)=>{
+            if (typeof data === "string") {
                 handler({
                     type: "json",
                     value: JSON.parse(data)
@@ -74,7 +74,7 @@ class PythLazerClient {
             let pos = 0;
             const magic = buffData.subarray(pos, pos + UINT32_NUM_BYTES).readUint32LE();
             pos += UINT32_NUM_BYTES;
-            if (magic != _protocol.BINARY_UPDATE_FORMAT_MAGIC_LE) {
+            if (magic !== _protocol.BINARY_UPDATE_FORMAT_MAGIC_LE) {
                 throw new Error("binary update format magic mismatch");
             }
             // TODO: some uint64 values may not be representable as Number.
@@ -87,15 +87,15 @@ class PythLazerClient {
                 const len = buffData.subarray(pos, pos + UINT16_NUM_BYTES).readUint16BE();
                 pos += UINT16_NUM_BYTES;
                 const magic = buffData.subarray(pos, pos + UINT32_NUM_BYTES).readUint32LE();
-                if (magic == _protocol.FORMAT_MAGICS_LE.EVM) {
+                if (magic === _protocol.FORMAT_MAGICS_LE.EVM) {
                     value.evm = buffData.subarray(pos, pos + len);
-                } else if (magic == _protocol.FORMAT_MAGICS_LE.SOLANA) {
+                } else if (magic === _protocol.FORMAT_MAGICS_LE.SOLANA) {
                     value.solana = buffData.subarray(pos, pos + len);
-                } else if (magic == _protocol.FORMAT_MAGICS_LE.LE_ECDSA) {
+                } else if (magic === _protocol.FORMAT_MAGICS_LE.LE_ECDSA) {
                     value.leEcdsa = buffData.subarray(pos, pos + len);
-                } else if (magic == _protocol.FORMAT_MAGICS_LE.LE_UNSIGNED) {
+                } else if (magic === _protocol.FORMAT_MAGICS_LE.LE_UNSIGNED) {
                     value.leUnsigned = buffData.subarray(pos, pos + len);
-                } else if (magic == _protocol.FORMAT_MAGICS_LE.JSON) {
+                } else if (magic === _protocol.FORMAT_MAGICS_LE.JSON) {
                     value.parsed = JSON.parse(buffData.subarray(pos + UINT32_NUM_BYTES, pos + len).toString());
                 } else {
                     throw new Error(`unknown magic:  ${magic.toString()}`);
@@ -108,43 +108,67 @@ class PythLazerClient {
             });
         });
     }
+    /**
+   * binds any internal event handlers
+   */ bindHandlers() {
+        this.abortSignal?.addEventListener("abort", this.abortHandler);
+    }
     subscribe(request) {
-        const wsp = this.getWebSocketPool();
         if (request.type !== "subscribe") {
             throw new Error("Request must be a subscribe request");
         }
-        wsp.addSubscription(request);
+        this.wsp.addSubscription(request);
     }
     unsubscribe(subscriptionId) {
-        const wsp = this.getWebSocketPool();
-        wsp.removeSubscription(subscriptionId);
+        this.wsp.removeSubscription(subscriptionId);
     }
     send(request) {
-        const wsp = this.getWebSocketPool();
-        wsp.sendRequest(request);
+        this.wsp.sendRequest(request);
     }
     /**
    * Registers a handler function that will be called whenever all WebSocket connections are down or attempting to reconnect.
    * The connections may still try to reconnect in the background. To shut down the pool, call `shutdown()`.
    * @param handler - Function to be called when all connections are down
    */ addAllConnectionsDownListener(handler) {
-        const wsp = this.getWebSocketPool();
-        wsp.addAllConnectionsDownListener(handler);
+        this.wsp.addAllConnectionsDownListener(handler);
+    }
+    /**
+   * Registers a handler function that will be called when at least one connection is restored after all were down.
+   * @param handler - Function to be called when connection is restored
+   */ addConnectionRestoredListener(handler) {
+        this.wsp.addConnectionRestoredListener(handler);
     }
+    /**
+   * Registers a handler function that will be called when an individual connection times out (heartbeat timeout).
+   * @param handler - Function to be called with connection index and endpoint URL
+   */ addConnectionTimeoutListener(handler) {
+        this.wsp.addConnectionTimeoutListener(handler);
+    }
+    /**
+   * Registers a handler function that will be called when an individual connection reconnects.
+   * @param handler - Function to be called with connection index and endpoint URL
+   */ addConnectionReconnectListener(handler) {
+        this.wsp.addConnectionReconnectListener(handler);
+    }
+    /**
+   * called if and only if a user provided an abort signal and it was aborted
+   */ abortHandler = ()=>{
+        this.shutdown();
+    };
     shutdown() {
-        const wsp = this.getWebSocketPool();
-        wsp.shutdown();
+        // Clean up abort signal listener to prevent memory leak
+        this.abortSignal?.removeEventListener("abort", this.abortHandler);
+        this.wsp.shutdown();
     }
     /**
    * Private helper method to make authenticated HTTP requests with Bearer token
    * @param url - The URL to fetch
    * @param options - Additional fetch options
    * @returns Promise resolving to the fetch Response
-   */ async authenticatedFetch(url, options = {}) {
-        const headers = {
-            Authorization: `Bearer ${this.token}`,
-            ...options.headers
-        };
+   */ authenticatedFetch(url, options = {}) {
+        // Handle all possible types of headers (Headers object, array, or plain object)
+        const headers = new Headers(options.headers);
+        headers.set("Authorization", headers.get("authorization") ?? `Bearer ${this.token}`);
         return fetch(url, {
             ...options,
             headers
@@ -181,15 +205,15 @@ class PythLazerClient {
         try {
             const body = JSON.stringify(params);
             this.logger.debug("getLatestPrice", {
-                url,
-                body
+                body,
+                url
             });
             const response = await this.authenticatedFetch(url, {
-                method: "POST",
+                body: body,
                 headers: {
                     "Content-Type": "application/json"
                 },
-                body: body
+                method: "POST"
             });
             if (!response.ok) {
                 throw new Error(`HTTP error! status: ${String(response.status)} - ${await response.text()}`);
@@ -208,15 +232,15 @@ class PythLazerClient {
         try {
             const body = JSON.stringify(params);
             this.logger.debug("getPrice", {
-                url,
-                body
+                body,
+                url
             });
             const response = await this.authenticatedFetch(url, {
-                method: "POST",
+                body: body,
                 headers: {
                     "Content-Type": "application/json"
                 },
-                body: body
+                method: "POST"
             });
             if (!response.ok) {
                 throw new Error(`HTTP error! status: ${String(response.status)} - ${await response.text()}`);

package/dist/cjs/client.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from "ts-log";
-import type { ParsedPayload, Request, Response, SymbolResponse, SymbolsQueryParams, LatestPriceRequest, PriceRequest, JsonUpdate } from "./protocol.js";
+import type { JsonUpdate, LatestPriceRequest, ParsedPayload, PriceRequest, Request, Response, SymbolResponse, SymbolsQueryParams } from "./protocol.js";
 import type { WebSocketPoolConfig } from "./socket/websocket-pool.js";
 export type BinaryResponse = {
     subscriptionId: number;
@@ -17,25 +17,25 @@ export type JsonOrBinaryResponse = {
     value: BinaryResponse;
 };
 export type LazerClientConfig = {
+    /**
+     * if provided and the signal is detected as canceled,
+     * all active listeners and connections will be unbound and killed.
+     */
+    abortSignal?: AbortSignal;
     token: string;
     metadataServiceUrl?: string;
     priceServiceUrl?: string;
     logger?: Logger;
-    webSocketPoolConfig?: WebSocketPoolConfig;
+    webSocketPoolConfig: WebSocketPoolConfig;
 };
 export declare class PythLazerClient {
-    private readonly token;
-    private readonly metadataServiceUrl;
-    private readonly priceServiceUrl;
-    private readonly logger;
-    private readonly wsp?;
+    private logger;
+    private metadataServiceUrl;
+    private priceServiceUrl;
+    private token;
+    private wsp;
+    private abortSignal;
     private constructor();
-    /**
-     * Gets the WebSocket pool. If the WebSocket pool is not configured, an error is thrown.
-     * @throws Error if WebSocket pool is not configured
-     * @returns The WebSocket pool
-     */
-    private getWebSocketPool;
     /**
      * Creates a new PythLazerClient instance.
      * @param config - Configuration including token, metadata service URL, and price service URL, and WebSocket pool configuration
@@ -48,6 +48,10 @@ export declare class PythLazerClient {
      * or a binary response containing EVM, Solana, or parsed payload data.
      */
     addMessageListener(handler: (event: JsonOrBinaryResponse) => void): void;
+    /**
+     * binds any internal event handlers
+     */
+    bindHandlers(): void;
     subscribe(request: Request): void;
     unsubscribe(subscriptionId: number): void;
     send(request: Request): void;
@@ -57,6 +61,25 @@ export declare class PythLazerClient {
      * @param handler - Function to be called when all connections are down
      */
     addAllConnectionsDownListener(handler: () => void): void;
+    /**
+     * Registers a handler function that will be called when at least one connection is restored after all were down.
+     * @param handler - Function to be called when connection is restored
+     */
+    addConnectionRestoredListener(handler: () => void): void;
+    /**
+     * Registers a handler function that will be called when an individual connection times out (heartbeat timeout).
+     * @param handler - Function to be called with connection index and endpoint URL
+     */
+    addConnectionTimeoutListener(handler: (connectionIndex: number, endpoint: string) => void): void;
+    /**
+     * Registers a handler function that will be called when an individual connection reconnects.
+     * @param handler - Function to be called with connection index and endpoint URL
+     */
+    addConnectionReconnectListener(handler: (connectionIndex: number, endpoint: string) => void): void;
+    /**
+     * called if and only if a user provided an abort signal and it was aborted
+     */
+    protected abortHandler: () => void;
     shutdown(): void;
     /**
      * Private helper method to make authenticated HTTP requests with Bearer token

package/dist/cjs/index.cjs

@@ -3,8 +3,8 @@ Object.defineProperty(exports, "__esModule", {
     value: true
 });
 _export_star(require("./client.cjs"), exports);
-_export_star(require("./protocol.cjs"), exports);
 _export_star(require("./constants.cjs"), exports);
+_export_star(require("./protocol.cjs"), exports);
 function _export_star(from, to) {
     Object.keys(from).forEach(function(k) {
         if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {

package/dist/cjs/index.d.ts

@@ -1,3 +1,3 @@
 export * from "./client.js";
-export * from "./protocol.js";
 export * from "./constants.js";
+export * from "./protocol.js";

package/dist/cjs/protocol.cjs

@@ -21,11 +21,11 @@ _export(exports, {
 });
 const BINARY_UPDATE_FORMAT_MAGIC_LE = 461_928_307;
 const FORMAT_MAGICS_LE = {
-    JSON: 3_302_625_434,
     EVM: 2_593_727_018,
-    SOLANA: 2_182_742_457,
+    JSON: 3_302_625_434,
     LE_ECDSA: 1_296_547_300,
-    LE_UNSIGNED: 1_499_680_012
+    LE_UNSIGNED: 1_499_680_012,
+    SOLANA: 2_182_742_457
 };
 var CustomSocketClosureCodes = /*#__PURE__*/ function(CustomSocketClosureCodes) {
     CustomSocketClosureCodes[CustomSocketClosureCodes["CLIENT_TIMEOUT_BUT_RECONNECTING"] = 4000] = "CLIENT_TIMEOUT_BUT_RECONNECTING";

package/dist/cjs/protocol.d.ts

@@ -1,18 +1,19 @@
 export type Format = "evm" | "solana" | "leEcdsa" | "leUnsigned";
 export type DeliveryFormat = "json" | "binary";
 export type JsonBinaryEncoding = "base64" | "hex";
-export type PriceFeedProperty = "price" | "bestBidPrice" | "bestAskPrice" | "exponent" | "publisherCount" | "confidence" | "fundingRate" | "fundingTimestamp" | "fundingRateInterval";
-export type Channel = "real_time" | "fixed_rate@50ms" | "fixed_rate@200ms";
+export type PriceFeedProperty = "price" | "bestBidPrice" | "bestAskPrice" | "exponent" | "publisherCount" | "confidence" | "fundingRate" | "fundingTimestamp" | "fundingRateInterval" | "marketSession" | "emaPrice" | "emaConfidence" | "feedUpdateTimestamp";
+export type Channel = "real_time" | "fixed_rate@50ms" | "fixed_rate@200ms" | "fixed_rate@1000ms";
 export type Request = {
     type: "subscribe";
     subscriptionId: number;
-    priceFeedIds: number[];
+    priceFeedIds?: number[] | undefined;
+    symbols?: string[] | undefined;
     properties: PriceFeedProperty[];
     formats: Format[];
-    deliveryFormat?: DeliveryFormat;
-    jsonBinaryEncoding?: JsonBinaryEncoding;
-    parsed?: boolean;
-    ignoreInvalidFeedIds?: boolean;
+    deliveryFormat?: DeliveryFormat | undefined;
+    jsonBinaryEncoding?: JsonBinaryEncoding | undefined;
+    parsed?: boolean | undefined;
+    ignoreInvalidFeedIds?: boolean | undefined;
     channel: Channel;
 } | {
     type: "unsubscribe";
@@ -25,7 +26,14 @@ export type ParsedFeedPayload = {
     bestAskPrice?: string | undefined;
     publisherCount?: number | undefined;
     exponent?: number | undefined;
-    confidence?: string | undefined;
+    confidence?: number | undefined;
+    fundingRate?: number | undefined;
+    fundingTimestamp?: number | undefined;
+    fundingRateInterval?: number | undefined;
+    marketSession?: string | undefined;
+    emaPrice?: string | undefined;
+    emaConfidence?: number | undefined;
+    feedUpdateTimestamp?: number | undefined;
 };
 export type ParsedPayload = {
     timestampUs: string;
@@ -70,13 +78,13 @@ export type Response = {
 };
 export declare const BINARY_UPDATE_FORMAT_MAGIC_LE = 461928307;
 export declare const FORMAT_MAGICS_LE: {
-    JSON: number;
     EVM: number;
-    SOLANA: number;
+    JSON: number;
     LE_ECDSA: number;
     LE_UNSIGNED: number;
+    SOLANA: number;
 };
-export type AssetType = "crypto" | "fx" | "equity" | "metal" | "rates" | "nav" | "commodity" | "funding-rate";
+export type AssetType = "crypto" | "fx" | "equity" | "metal" | "rates" | "nav" | "commodity" | "funding-rate" | "eco" | "kalshi";
 export type SymbolsQueryParams = {
     query?: string;
     asset_type?: AssetType;

package/dist/cjs/socket/resilient-websocket.cjs

@@ -45,6 +45,7 @@ class ResilientWebSocket {
     onError;
     onMessage;
     onReconnect;
+    onTimeout;
     constructor(config){
         this.endpoint = config.endpoint;
         this.wsOptions = config.wsOptions;
@@ -62,6 +63,9 @@ class ResilientWebSocket {
         this.onReconnect = ()=>{
         // Empty function, can be set by the user.
         };
+        this.onTimeout = ()=>{
+        // Empty function, can be set by the user.
+        };
     }
     send(data) {
         this.logger.debug(`Sending message`);
@@ -129,6 +133,7 @@ class ResilientWebSocket {
         this.heartbeatTimeout = setTimeout(()=>{
             const warnMsg = "Connection timed out. Reconnecting...";
             this.logger.warn(warnMsg);
+            this.onTimeout();
             if (this.wsClient) {
                 if (typeof this.wsClient.terminate === "function") {
                     this.wsClient.terminate();

package/dist/cjs/socket/resilient-websocket.d.ts

@@ -44,6 +44,7 @@ export declare class ResilientWebSocket {
     onError: (error: ErrorEvent) => void;
     onMessage: (data: WebSocket.Data) => void;
     onReconnect: () => void;
+    onTimeout: () => void;
     constructor(config: ResilientWebSocketConfig);
     send(data: string | Buffer): void;
     startWebSocket(): void;

package/dist/cjs/socket/websocket-pool.cjs

@@ -10,10 +10,10 @@ Object.defineProperty(exports, "WebSocketPool", {
 });
 const _ttlcache = /*#__PURE__*/ _interop_require_default(require("@isaacs/ttlcache"));
 const _tslog = require("ts-log");
-const _resilientwebsocket = require("./resilient-websocket.cjs");
 const _constants = require("../constants.cjs");
 const _index = require("../emitter/index.cjs");
 const _index1 = require("../util/index.cjs");
+const _resilientwebsocket = require("./resilient-websocket.cjs");
 function _interop_require_default(obj) {
     return obj && obj.__esModule ? obj : {
         default: obj
@@ -22,15 +22,20 @@ function _interop_require_default(obj) {
 const DEFAULT_NUM_CONNECTIONS = 4;
 class WebSocketPool extends _index.IsomorphicEventEmitter {
     logger;
+    abortSignal;
     rwsPool;
     cache;
     subscriptions;
     messageListeners;
     allConnectionsDownListeners;
+    connectionRestoredListeners;
+    connectionTimeoutListeners;
+    connectionReconnectListeners;
     wasAllDown = true;
     checkConnectionStatesInterval;
-    constructor(logger){
-        super(), this.logger = logger;
+    isShutdown = false;
+    constructor(logger, abortSignal){
+        super(), this.logger = logger, this.abortSignal = abortSignal;
         this.rwsPool = [];
         this.cache = new _ttlcache.default({
             ttl: 1000 * 10
@@ -38,6 +43,9 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
         this.subscriptions = new Map();
         this.messageListeners = [];
         this.allConnectionsDownListeners = [];
+        this.connectionRestoredListeners = [];
+        this.connectionTimeoutListeners = [];
+        this.connectionReconnectListeners = [];
         // Start monitoring connection states
         this.checkConnectionStatesInterval = setInterval(()=>{
             this.checkConnectionStates();
@@ -50,13 +58,13 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
    * @param token - Authentication token to use for the connections
    * @param numConnections - Number of parallel WebSocket connections to maintain (default: 3)
    * @param logger - Optional logger to get socket level logs. Compatible with most loggers such as the built-in console and `bunyan`.
-   */ static async create(config, token, logger) {
+   */ static async create(config, token, abortSignal, logger) {
         const urls = config.urls ?? [
             _constants.DEFAULT_STREAM_SERVICE_0_URL,
             _constants.DEFAULT_STREAM_SERVICE_1_URL
         ];
         const log = logger ?? _tslog.dummyLogger;
-        const pool = new WebSocketPool(log);
+        const pool = new WebSocketPool(log, abortSignal);
         const numConnections = config.numConnections ?? DEFAULT_NUM_CONNECTIONS;
         // bind a handler to capture any emitted errors and send them to the user-provided
         // onWebSocketPoolError callback (if it is present)
@@ -83,15 +91,20 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
             const rws = new _resilientwebsocket.ResilientWebSocket({
                 ...config.rwsConfig,
                 endpoint: url,
-                wsOptions,
-                logger: log
+                logger: log,
+                wsOptions
             });
+            const connectionIndex = i;
+            const connectionEndpoint = url;
             // If a websocket client unexpectedly disconnects, ResilientWebSocket will reestablish
             // the connection and call the onReconnect callback.
             rws.onReconnect = ()=>{
-                if (rws.wsUserClosed) {
+                if (rws.wsUserClosed || pool.isShutdown || pool.abortSignal?.aborted) {
                     return;
                 }
+                for (const listener of pool.connectionReconnectListeners){
+                    listener(connectionIndex, connectionEndpoint);
+                }
                 for (const [, request] of pool.subscriptions){
                     try {
                         rws.send(JSON.stringify(request));
@@ -100,6 +113,11 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
                     }
                 }
             };
+            rws.onTimeout = ()=>{
+                for (const listener of pool.connectionTimeoutListeners){
+                    listener(connectionIndex, connectionEndpoint);
+                }
+            };
             // eslint-disable-next-line @typescript-eslint/no-deprecated
             const onErrorHandler = config.onWebSocketError ?? config.onError;
             if (typeof onErrorHandler === "function") {
@@ -116,6 +134,11 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
         }
         pool.logger.info(`Started WebSocketPool with ${numConnections.toString()} connections. Waiting for at least one to connect...`);
         while(!pool.isAnyConnectionEstablished()){
+            if (pool.abortSignal?.aborted) {
+                pool.logger.warn("the WebSocket Pool's abort signal was aborted during connection. Shutting down.");
+                pool.shutdown();
+                return pool;
+            }
             await new Promise((resolve)=>setTimeout(resolve, 100));
         }
         pool.logger.info(`At least one WebSocket connection is established. WebSocketPool is ready.`);
@@ -171,6 +194,10 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
         }
     };
     sendRequest(request) {
+        if (this.isShutdown || this.abortSignal?.aborted) {
+            this.logger.warn("Cannot send request: WebSocketPool is shutdown or aborted");
+            return;
+        }
         for (const rws of this.rwsPool){
             try {
                 rws.send(JSON.stringify(request));
@@ -180,6 +207,10 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
         }
     }
     addSubscription(request) {
+        if (this.isShutdown || this.abortSignal?.aborted) {
+            this.logger.warn("Cannot add subscription: WebSocketPool is shutdown or aborted");
+            return;
+        }
         if (request.type !== "subscribe") {
             this.emitPoolError(new Error("Request must be a subscribe request"));
             return;
@@ -188,10 +219,14 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
         this.sendRequest(request);
     }
     removeSubscription(subscriptionId) {
+        if (this.isShutdown || this.abortSignal?.aborted) {
+            this.logger.warn("Cannot remove subscription: WebSocketPool is shutdown or aborted");
+            return;
+        }
         this.subscriptions.delete(subscriptionId);
         const request = {
-            type: "unsubscribe",
-            subscriptionId
+            subscriptionId,
+            type: "unsubscribe"
         };
         this.sendRequest(request);
     }
@@ -204,6 +239,23 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
    */ addAllConnectionsDownListener(handler) {
         this.allConnectionsDownListeners.push(handler);
     }
+    /**
+   * Calls the handler when at least one connection is restored after all connections were down.
+   */ addConnectionRestoredListener(handler) {
+        this.connectionRestoredListeners.push(handler);
+    }
+    /**
+   * Calls the handler when an individual connection times out (heartbeat timeout).
+   * @param handler - Callback with connection index and endpoint URL
+   */ addConnectionTimeoutListener(handler) {
+        this.connectionTimeoutListeners.push(handler);
+    }
+    /**
+   * Calls the handler when an individual connection reconnects after being down.
+   * @param handler - Callback with connection index and endpoint URL
+   */ addConnectionReconnectListener(handler) {
+        this.connectionReconnectListeners.push(handler);
+    }
     areAllConnectionsDown() {
         return this.rwsPool.every((ws)=>!ws.isConnected() || ws.isReconnecting());
     }
@@ -211,6 +263,10 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
         return this.rwsPool.some((ws)=>ws.isConnected());
     }
     checkConnectionStates() {
+        // Stop monitoring if shutdown or aborted
+        if (this.isShutdown || this.abortSignal?.aborted) {
+            return;
+        }
         const allDown = this.areAllConnectionsDown();
         // If all connections just went down
         if (allDown && !this.wasAllDown) {
@@ -225,12 +281,25 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
                 }
             }
         }
-        // If at least one connection was restored
+        // If at least one connection was restored after all were down
         if (!allDown && this.wasAllDown) {
             this.wasAllDown = false;
+            this.logger.info("At least one WebSocket connection restored");
+            for (const listener of this.connectionRestoredListeners){
+                try {
+                    listener();
+                } catch (error) {
+                    this.emitPoolError(error, "Connection-restored listener threw");
+                }
+            }
         }
     }
     shutdown() {
+        // Prevent multiple shutdown calls
+        if (this.isShutdown) {
+            return;
+        }
+        this.isShutdown = true;
         for (const rws of this.rwsPool){
             rws.closeWebSocket();
         }
@@ -238,6 +307,9 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
         this.subscriptions.clear();
         this.messageListeners = [];
         this.allConnectionsDownListeners = [];
+        this.connectionRestoredListeners = [];
+        this.connectionTimeoutListeners = [];
+        this.connectionReconnectListeners = [];
         clearInterval(this.checkConnectionStatesInterval);
         // execute all bound shutdown handlers
         for (const shutdownHandler of this.getListeners("shutdown")){