@pythnetwork/pyth-lazer-sdk 6.0.0 → 6.2.0

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

@@ -1,10 +1,10 @@
+import type WebSocket from "isomorphic-ws";
 import type { ErrorEvent } from "isomorphic-ws";
-import WebSocket from "isomorphic-ws";
 import type { Logger } from "ts-log";
+import { IsomorphicEventEmitter } from "../emitter/index.js";
 import type { Request } from "../protocol.js";
 import type { ResilientWebSocketConfig } from "./resilient-websocket.js";
 import { ResilientWebSocket } from "./resilient-websocket.js";
-import { IsomorphicEventEmitter } from "../emitter/index.js";
 type WebSocketOnMessageCallback = (data: WebSocket.Data) => Promise<void>;
 export type WebSocketPoolConfig = {
     /**
@@ -46,13 +46,18 @@ export type WebSocketPoolEvents = {
 };
 export declare class WebSocketPool extends IsomorphicEventEmitter<WebSocketPoolEvents> {
     private readonly logger;
+    private readonly abortSignal?;
     rwsPool: ResilientWebSocket[];
     private cache;
     private subscriptions;
     private messageListeners;
     private allConnectionsDownListeners;
+    private connectionRestoredListeners;
+    private connectionTimeoutListeners;
+    private connectionReconnectListeners;
     private wasAllDown;
     private checkConnectionStatesInterval;
+    private isShutdown;
     private constructor();
     /**
      * Creates a new WebSocketPool instance that uses multiple redundant WebSocket connections for reliability.
@@ -62,7 +67,7 @@ export declare class WebSocketPool extends IsomorphicEventEmitter<WebSocketPoolE
      * @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 create(config: WebSocketPoolConfig, token: string, logger?: Logger): Promise<WebSocketPool>;
+    static create(config: WebSocketPoolConfig, token: string, abortSignal: AbortSignal | null | undefined, logger?: Logger): Promise<WebSocketPool>;
     private emitPoolError;
     /**
      * Checks for error responses in JSON messages and throws appropriate errors
@@ -83,6 +88,20 @@ export declare class WebSocketPool extends IsomorphicEventEmitter<WebSocketPoolE
      * The connections may still try to reconnect in the background.
      */
     addAllConnectionsDownListener(handler: () => void): void;
+    /**
+     * Calls the handler when at least one connection is restored after all connections were down.
+     */
+    addConnectionRestoredListener(handler: () => void): void;
+    /**
+     * Calls the handler when an individual connection times out (heartbeat timeout).
+     * @param handler - Callback with connection index and endpoint URL
+     */
+    addConnectionTimeoutListener(handler: (connectionIndex: number, endpoint: string) => void): void;
+    /**
+     * Calls the handler when an individual connection reconnects after being down.
+     * @param handler - Callback with connection index and endpoint URL
+     */
+    addConnectionReconnectListener(handler: (connectionIndex: number, endpoint: string) => void): void;
     private areAllConnectionsDown;
     private isAnyConnectionEstablished;
     private checkConnectionStates;

package/dist/esm/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/esm/client.mjs

@@ -7,27 +7,20 @@ const UINT16_NUM_BYTES = 2;
 const UINT32_NUM_BYTES = 4;
 const UINT64_NUM_BYTES = 8;
 export 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.
@@ -38,12 +31,20 @@ export class PythLazerClient {
         const metadataServiceUrl = (config.metadataServiceUrl ?? DEFAULT_METADATA_SERVICE_URL).replace(/\/+$/, "");
         const priceServiceUrl = (config.priceServiceUrl ?? DEFAULT_PRICE_SERVICE_URL).replace(/\/+$/, "");
         const logger = config.logger ?? 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.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.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.
@@ -51,9 +52,8 @@ export 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)
@@ -64,7 +64,7 @@ export class PythLazerClient {
             let pos = 0;
             const magic = buffData.subarray(pos, pos + UINT32_NUM_BYTES).readUint32LE();
             pos += UINT32_NUM_BYTES;
-            if (magic != BINARY_UPDATE_FORMAT_MAGIC_LE) {
+            if (magic !== BINARY_UPDATE_FORMAT_MAGIC_LE) {
                 throw new Error("binary update format magic mismatch");
             }
             // TODO: some uint64 values may not be representable as Number.
@@ -77,15 +77,15 @@ export 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 == FORMAT_MAGICS_LE.EVM) {
+                if (magic === FORMAT_MAGICS_LE.EVM) {
                     value.evm = buffData.subarray(pos, pos + len);
-                } else if (magic == FORMAT_MAGICS_LE.SOLANA) {
+                } else if (magic === FORMAT_MAGICS_LE.SOLANA) {
                     value.solana = buffData.subarray(pos, pos + len);
-                } else if (magic == FORMAT_MAGICS_LE.LE_ECDSA) {
+                } else if (magic === FORMAT_MAGICS_LE.LE_ECDSA) {
                     value.leEcdsa = buffData.subarray(pos, pos + len);
-                } else if (magic == FORMAT_MAGICS_LE.LE_UNSIGNED) {
+                } else if (magic === FORMAT_MAGICS_LE.LE_UNSIGNED) {
                     value.leUnsigned = buffData.subarray(pos, pos + len);
-                } else if (magic == FORMAT_MAGICS_LE.JSON) {
+                } else if (magic === 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()}`);
@@ -98,43 +98,67 @@ export 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
@@ -171,15 +195,15 @@ export 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()}`);
@@ -198,15 +222,15 @@ export 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/esm/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/esm/index.mjs

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

package/dist/esm/protocol.d.ts

@@ -2,7 +2,7 @@ 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" | "marketSession" | "emaPrice" | "emaConfidence" | "feedUpdateTimestamp";
-export type Channel = "real_time" | "fixed_rate@50ms" | "fixed_rate@200ms";
+export type Channel = "real_time" | "fixed_rate@50ms" | "fixed_rate@200ms" | "fixed_rate@1000ms";
 export type Request = {
     type: "subscribe";
     subscriptionId: number;
@@ -78,11 +78,11 @@ 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" | "eco" | "kalshi";
 export type SymbolsQueryParams = {

package/dist/esm/protocol.mjs

@@ -1,10 +1,10 @@
 export const BINARY_UPDATE_FORMAT_MAGIC_LE = 461_928_307;
 export 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
 };
 export var CustomSocketClosureCodes = /*#__PURE__*/ function(CustomSocketClosureCodes) {
     CustomSocketClosureCodes[CustomSocketClosureCodes["CLIENT_TIMEOUT_BUT_RECONNECTING"] = 4000] = "CLIENT_TIMEOUT_BUT_RECONNECTING";

package/dist/esm/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/esm/socket/resilient-websocket.mjs

@@ -30,6 +30,7 @@ export class ResilientWebSocket {
     onError;
     onMessage;
     onReconnect;
+    onTimeout;
     constructor(config){
         this.endpoint = config.endpoint;
         this.wsOptions = config.wsOptions;
@@ -47,6 +48,9 @@ export 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`);
@@ -114,6 +118,7 @@ export 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/esm/socket/websocket-pool.d.ts

@@ -1,10 +1,10 @@
+import type WebSocket from "isomorphic-ws";
 import type { ErrorEvent } from "isomorphic-ws";
-import WebSocket from "isomorphic-ws";
 import type { Logger } from "ts-log";
+import { IsomorphicEventEmitter } from "../emitter/index.js";
 import type { Request } from "../protocol.js";
 import type { ResilientWebSocketConfig } from "./resilient-websocket.js";
 import { ResilientWebSocket } from "./resilient-websocket.js";
-import { IsomorphicEventEmitter } from "../emitter/index.js";
 type WebSocketOnMessageCallback = (data: WebSocket.Data) => Promise<void>;
 export type WebSocketPoolConfig = {
     /**
@@ -46,13 +46,18 @@ export type WebSocketPoolEvents = {
 };
 export declare class WebSocketPool extends IsomorphicEventEmitter<WebSocketPoolEvents> {
     private readonly logger;
+    private readonly abortSignal?;
     rwsPool: ResilientWebSocket[];
     private cache;
     private subscriptions;
     private messageListeners;
     private allConnectionsDownListeners;
+    private connectionRestoredListeners;
+    private connectionTimeoutListeners;
+    private connectionReconnectListeners;
     private wasAllDown;
     private checkConnectionStatesInterval;
+    private isShutdown;
     private constructor();
     /**
      * Creates a new WebSocketPool instance that uses multiple redundant WebSocket connections for reliability.
@@ -62,7 +67,7 @@ export declare class WebSocketPool extends IsomorphicEventEmitter<WebSocketPoolE
      * @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 create(config: WebSocketPoolConfig, token: string, logger?: Logger): Promise<WebSocketPool>;
+    static create(config: WebSocketPoolConfig, token: string, abortSignal: AbortSignal | null | undefined, logger?: Logger): Promise<WebSocketPool>;
     private emitPoolError;
     /**
      * Checks for error responses in JSON messages and throws appropriate errors
@@ -83,6 +88,20 @@ export declare class WebSocketPool extends IsomorphicEventEmitter<WebSocketPoolE
      * The connections may still try to reconnect in the background.
      */
     addAllConnectionsDownListener(handler: () => void): void;
+    /**
+     * Calls the handler when at least one connection is restored after all connections were down.
+     */
+    addConnectionRestoredListener(handler: () => void): void;
+    /**
+     * Calls the handler when an individual connection times out (heartbeat timeout).
+     * @param handler - Callback with connection index and endpoint URL
+     */
+    addConnectionTimeoutListener(handler: (connectionIndex: number, endpoint: string) => void): void;
+    /**
+     * Calls the handler when an individual connection reconnects after being down.
+     * @param handler - Callback with connection index and endpoint URL
+     */
+    addConnectionReconnectListener(handler: (connectionIndex: number, endpoint: string) => void): void;
     private areAllConnectionsDown;
     private isAnyConnectionEstablished;
     private checkConnectionStates;