@pythnetwork/pyth-lazer-sdk 4.0.0 → 5.0.0

package/README.md

@@ -3,3 +3,60 @@
 ## Contributing & Development
 
 See [contributing.md](docs/contributing/contributing.md) for information on how to develop or contribute to this project!
+
+## How to use
+
+```javascript
+import { PythLazerClient } from "@pythnetwork/pyth-lazer-sdk";
+
+const c = await PythLazerClient.create({
+  token: "YOUR-AUTH-TOKEN-HERE",
+  logger: console, // Optionally log operations (to the console in this case.)
+  webSocketPoolConfig: {
+    numConnections: 4, // Optionally specify number of parallel redundant connections to reduce the chance of dropped messages. The connections will round-robin across the provided URLs. Default is 4.
+    onError: (error) => {
+      console.error("⛔️ WebSocket error:", error.message);
+    },
+    // Optional configuration for resilient WebSocket connections
+    rwsConfig: {
+      heartbeatTimeoutDurationMs: 5000, // Optional heartbeat timeout duration in milliseconds
+      maxRetryDelayMs: 1000, // Optional maximum retry delay in milliseconds
+      logAfterRetryCount: 10, // Optional log after how many retries
+    },
+  },
+});
+
+c.addMessageListener((message) => {
+  console.info("received the following from the Lazer stream:", message);
+});
+
+// Monitor for all connections in the pool being down simultaneously (e.g. if the internet goes down)
+// The connections may still try to reconnect in the background. To shut down the client completely, call shutdown().
+c.addAllConnectionsDownListener(() => {
+  console.error("All connections are down!");
+});
+
+// Create and remove one or more subscriptions on the fly
+c.subscribe({
+  type: "subscribe",
+  subscriptionId: 1,
+  priceFeedIds: [1, 2],
+  properties: ["price"],
+  formats: ["solana"],
+  deliveryFormat: "binary",
+  channel: "fixed_rate@200ms",
+  parsed: false,
+  jsonBinaryEncoding: "base64",
+});
+c.subscribe({
+  type: "subscribe",
+  subscriptionId: 2,
+  priceFeedIds: [1, 2, 3, 4, 5],
+  properties: ["price", "exponent", "publisherCount", "confidence"],
+  formats: ["evm"],
+  deliveryFormat: "json",
+  channel: "fixed_rate@200ms",
+  parsed: true,
+  jsonBinaryEncoding: "hex",
+});
+```

package/dist/cjs/client.js

@@ -1,14 +1,11 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PythLazerClient = void 0;
-const cross_fetch_1 = __importDefault(require("cross-fetch"));
 const ts_log_1 = require("ts-log");
 const constants_js_1 = require("./constants.js");
 const protocol_js_1 = require("./protocol.js");
 const websocket_pool_js_1 = require("./socket/websocket-pool.js");
+const buffer_util_js_1 = require("./util/buffer-util.js");
 const UINT16_NUM_BYTES = 2;
 const UINT32_NUM_BYTES = 4;
 const UINT64_NUM_BYTES = 8;
@@ -61,55 +58,56 @@ class PythLazerClient {
      */
     addMessageListener(handler) {
         const wsp = this.getWebSocketPool();
-        wsp.addMessageListener((data) => {
+        wsp.addMessageListener(async (data) => {
             if (typeof data == "string") {
                 handler({
                     type: "json",
                     value: JSON.parse(data),
                 });
+                return;
             }
-            else if (Buffer.isBuffer(data)) {
-                let pos = 0;
-                const magic = data.subarray(pos, pos + UINT32_NUM_BYTES).readUint32LE();
-                pos += UINT32_NUM_BYTES;
-                if (magic != protocol_js_1.BINARY_UPDATE_FORMAT_MAGIC_LE) {
-                    throw new Error("binary update format magic mismatch");
+            const buffData = await (0, buffer_util_js_1.bufferFromWebsocketData)(data);
+            let pos = 0;
+            const magic = buffData
+                .subarray(pos, pos + UINT32_NUM_BYTES)
+                .readUint32LE();
+            pos += UINT32_NUM_BYTES;
+            if (magic != protocol_js_1.BINARY_UPDATE_FORMAT_MAGIC_LE) {
+                throw new Error("binary update format magic mismatch");
+            }
+            // TODO: some uint64 values may not be representable as Number.
+            const subscriptionId = Number(buffData.subarray(pos, pos + UINT64_NUM_BYTES).readBigInt64BE());
+            pos += UINT64_NUM_BYTES;
+            const value = { subscriptionId };
+            while (pos < buffData.length) {
+                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_js_1.FORMAT_MAGICS_LE.EVM) {
+                    value.evm = buffData.subarray(pos, pos + len);
                 }
-                // TODO: some uint64 values may not be representable as Number.
-                const subscriptionId = Number(data.subarray(pos, pos + UINT64_NUM_BYTES).readBigInt64BE());
-                pos += UINT64_NUM_BYTES;
-                const value = { subscriptionId };
-                while (pos < data.length) {
-                    const len = data.subarray(pos, pos + UINT16_NUM_BYTES).readUint16BE();
-                    pos += UINT16_NUM_BYTES;
-                    const magic = data
-                        .subarray(pos, pos + UINT32_NUM_BYTES)
-                        .readUint32LE();
-                    if (magic == protocol_js_1.FORMAT_MAGICS_LE.EVM) {
-                        value.evm = data.subarray(pos, pos + len);
-                    }
-                    else if (magic == protocol_js_1.FORMAT_MAGICS_LE.SOLANA) {
-                        value.solana = data.subarray(pos, pos + len);
-                    }
-                    else if (magic == protocol_js_1.FORMAT_MAGICS_LE.LE_ECDSA) {
-                        value.leEcdsa = data.subarray(pos, pos + len);
-                    }
-                    else if (magic == protocol_js_1.FORMAT_MAGICS_LE.LE_UNSIGNED) {
-                        value.leUnsigned = data.subarray(pos, pos + len);
-                    }
-                    else if (magic == protocol_js_1.FORMAT_MAGICS_LE.JSON) {
-                        value.parsed = JSON.parse(data.subarray(pos + UINT32_NUM_BYTES, pos + len).toString());
-                    }
-                    else {
-                        throw new Error("unknown magic: " + magic.toString());
-                    }
-                    pos += len;
+                else if (magic == protocol_js_1.FORMAT_MAGICS_LE.SOLANA) {
+                    value.solana = buffData.subarray(pos, pos + len);
                 }
-                handler({ type: "binary", value });
-            }
-            else {
-                throw new TypeError("unexpected event data type");
+                else if (magic == protocol_js_1.FORMAT_MAGICS_LE.LE_ECDSA) {
+                    value.leEcdsa = buffData.subarray(pos, pos + len);
+                }
+                else if (magic == protocol_js_1.FORMAT_MAGICS_LE.LE_UNSIGNED) {
+                    value.leUnsigned = buffData.subarray(pos, pos + len);
+                }
+                else if (magic == protocol_js_1.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()}`);
+                }
+                pos += len;
             }
+            handler({ type: "binary", value });
         });
     }
     subscribe(request) {
@@ -151,7 +149,7 @@ class PythLazerClient {
             Authorization: `Bearer ${this.token}`,
             ...options.headers,
         };
-        return (0, cross_fetch_1.default)(url, {
+        return fetch(url, {
             ...options,
             headers,
         });

package/dist/cjs/protocol.d.ts

@@ -122,3 +122,6 @@ export type JsonUpdate = {
     leEcdsa?: JsonBinaryData;
     leUnsigned?: JsonBinaryData;
 };
+export declare enum CustomSocketClosureCodes {
+    CLIENT_TIMEOUT_BUT_RECONNECTING = 4000
+}

package/dist/cjs/protocol.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FORMAT_MAGICS_LE = exports.BINARY_UPDATE_FORMAT_MAGIC_LE = void 0;
+exports.CustomSocketClosureCodes = exports.FORMAT_MAGICS_LE = exports.BINARY_UPDATE_FORMAT_MAGIC_LE = void 0;
 exports.BINARY_UPDATE_FORMAT_MAGIC_LE = 461_928_307;
 exports.FORMAT_MAGICS_LE = {
     JSON: 3_302_625_434,
@@ -9,3 +9,7 @@ exports.FORMAT_MAGICS_LE = {
     LE_ECDSA: 1_296_547_300,
     LE_UNSIGNED: 1_499_680_012,
 };
+var CustomSocketClosureCodes;
+(function (CustomSocketClosureCodes) {
+    CustomSocketClosureCodes[CustomSocketClosureCodes["CLIENT_TIMEOUT_BUT_RECONNECTING"] = 4000] = "CLIENT_TIMEOUT_BUT_RECONNECTING";
+})(CustomSocketClosureCodes || (exports.CustomSocketClosureCodes = CustomSocketClosureCodes = {}));

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

@@ -10,6 +10,19 @@ export type ResilientWebSocketConfig = {
     maxRetryDelayMs?: number;
     logAfterRetryCount?: number;
 };
+/**
+ * the isomorphic-ws package ships with some slightly-erroneous typings.
+ * namely, it returns a WebSocket with typings that indicate the "terminate()" function
+ * is available on all platforms.
+ * Given that, under the hood, it is using the globalThis.WebSocket class, if it's available,
+ * and falling back to using the https://www.npmjs.com/package/ws package, this
+ * means there are API differences between the native WebSocket (the one in a web browser)
+ * and the server-side version from the "ws" package.
+ *
+ * This type creates a WebSocket type reference we use to indicate the unknown
+ * nature of the env in which is code is run.
+ */
+type UnsafeWebSocket = Omit<WebSocket, "terminate"> & Partial<Pick<WebSocket, "terminate">>;
 export declare class ResilientWebSocket {
     private endpoint;
     private wsOptions?;
@@ -17,7 +30,7 @@ export declare class ResilientWebSocket {
     private heartbeatTimeoutDurationMs;
     private maxRetryDelayMs;
     private logAfterRetryCount;
-    wsClient: undefined | WebSocket;
+    wsClient: UnsafeWebSocket | undefined;
     wsUserClosed: boolean;
     private wsFailedAttempts;
     private heartbeatTimeout?;
@@ -47,3 +60,4 @@ export declare class ResilientWebSocket {
      */
     private retryDelayMs;
 }
+export {};

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

@@ -6,6 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ResilientWebSocket = void 0;
 const isomorphic_ws_1 = __importDefault(require("isomorphic-ws"));
 const ts_log_1 = require("ts-log");
+const protocol_js_1 = require("../protocol.js");
+const env_util_js_1 = require("../util/env-util.js");
 const DEFAULT_HEARTBEAT_TIMEOUT_DURATION_MS = 5000; // 5 seconds
 const DEFAULT_MAX_RETRY_DELAY_MS = 1000; // 1 second'
 const DEFAULT_LOG_AFTER_RETRY_COUNT = 10;
@@ -80,7 +82,10 @@ class ResilientWebSocket {
             clearTimeout(this.retryTimeout);
             this.retryTimeout = undefined;
         }
-        this.wsClient = new isomorphic_ws_1.default(this.endpoint, this.wsOptions);
+        // browser constructor supports a different 2nd argument for the constructor,
+        // so we need to ensure it's not included if we're running in that environment:
+        // https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket#protocols
+        this.wsClient = new isomorphic_ws_1.default(this.endpoint, (0, env_util_js_1.envIsBrowserOrWorker)() ? undefined : this.wsOptions);
         this.wsClient.addEventListener("open", () => {
             this.logger.info("WebSocket connection established");
             this.wsFailedAttempts = 0;
@@ -118,8 +123,19 @@ class ResilientWebSocket {
             clearTimeout(this.heartbeatTimeout);
         }
         this.heartbeatTimeout = setTimeout(() => {
-            this.logger.warn("Connection timed out. Reconnecting...");
-            this.wsClient?.terminate();
+            const warnMsg = "Connection timed out. Reconnecting...";
+            this.logger.warn(warnMsg);
+            if (this.wsClient) {
+                if (typeof this.wsClient.terminate === "function") {
+                    this.wsClient.terminate();
+                }
+                else {
+                    // terminate is an implementation detail of the node-friendly
+                    // https://www.npmjs.com/package/ws package, but is not a native WebSocket API,
+                    // so we have to use the close method
+                    this.wsClient.close(protocol_js_1.CustomSocketClosureCodes.CLIENT_TIMEOUT_BUT_RECONNECTING, warnMsg);
+                }
+            }
             this.handleReconnect();
         }, this.heartbeatTimeoutDurationMs);
     }

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

@@ -4,6 +4,7 @@ import type { Logger } from "ts-log";
 import type { Request } from "../protocol.js";
 import type { ResilientWebSocketConfig } from "./resilient-websocket.js";
 import { ResilientWebSocket } from "./resilient-websocket.js";
+type WebSocketOnMessageCallback = (data: WebSocket.Data) => void | Promise<void>;
 export type WebSocketPoolConfig = {
     urls?: string[];
     numConnections?: number;
@@ -33,15 +34,16 @@ export declare class WebSocketPool {
      * Checks for error responses in JSON messages and throws appropriate errors
      */
     private handleErrorMessages;
+    private constructCacheKeyFromWebsocketData;
     /**
      * Handles incoming websocket messages by deduplicating identical messages received across
      * multiple connections before forwarding to registered handlers
      */
-    dedupeHandler: (data: WebSocket.Data) => void;
+    dedupeHandler: (data: WebSocket.Data) => Promise<void>;
     sendRequest(request: Request): void;
     addSubscription(request: Request): void;
     removeSubscription(subscriptionId: number): void;
-    addMessageListener(handler: (data: WebSocket.Data) => void): void;
+    addMessageListener(handler: WebSocketOnMessageCallback): void;
     /**
      * Calls the handler if all websocket connections are currently down or in reconnecting state.
      * The connections may still try to reconnect in the background.
@@ -52,3 +54,4 @@ export declare class WebSocketPool {
     private checkConnectionStates;
     shutdown(): void;
 }
+export {};

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

@@ -8,6 +8,7 @@ const ttlcache_1 = __importDefault(require("@isaacs/ttlcache"));
 const ts_log_1 = require("ts-log");
 const resilient_websocket_js_1 = require("./resilient-websocket.js");
 const constants_js_1 = require("../constants.js");
+const index_js_1 = require("../util/index.js");
 const DEFAULT_NUM_CONNECTIONS = 4;
 class WebSocketPool {
     logger;
@@ -47,15 +48,17 @@ class WebSocketPool {
         const pool = new WebSocketPool(log);
         const numConnections = config.numConnections ?? DEFAULT_NUM_CONNECTIONS;
         for (let i = 0; i < numConnections; i++) {
-            const url = urls[i % urls.length];
+            const baseUrl = urls[i % urls.length];
+            const isBrowser = (0, index_js_1.envIsBrowserOrWorker)();
+            const url = isBrowser
+                ? (0, index_js_1.addAuthTokenToWebSocketUrl)(baseUrl, token)
+                : baseUrl;
             if (!url) {
                 throw new Error(`URLs must not be null or empty`);
             }
             const wsOptions = {
                 ...config.rwsConfig?.wsOptions,
-                headers: {
-                    Authorization: `Bearer ${token}`,
-                },
+                headers: isBrowser ? undefined : { Authorization: `Bearer ${token}` },
             };
             const rws = new resilient_websocket_js_1.ResilientWebSocket({
                 ...config.rwsConfig,
@@ -82,7 +85,12 @@ class WebSocketPool {
                 rws.onError = config.onError;
             }
             // Handle all client messages ourselves. Dedupe before sending to registered message handlers.
-            rws.onMessage = pool.dedupeHandler;
+            rws.onMessage = (data) => {
+                pool.dedupeHandler(data).catch((error) => {
+                    const errMsg = `An error occurred in the WebSocket pool's dedupeHandler: ${error instanceof Error ? error.message : String(error)}`;
+                    throw new Error(errMsg);
+                });
+            };
             pool.rwsPool.push(rws);
             rws.startWebSocket();
         }
@@ -105,14 +113,18 @@ class WebSocketPool {
             throw new Error(`Error: ${message.error}`);
         }
     }
+    async constructCacheKeyFromWebsocketData(data) {
+        if (typeof data === "string")
+            return data;
+        const buff = await (0, index_js_1.bufferFromWebsocketData)(data);
+        return buff.toString("hex");
+    }
     /**
      * Handles incoming websocket messages by deduplicating identical messages received across
      * multiple connections before forwarding to registered handlers
      */
-    dedupeHandler = (data) => {
-        const cacheKey = typeof data === "string"
-            ? data
-            : Buffer.from(data).toString("hex");
+    dedupeHandler = async (data) => {
+        const cacheKey = await this.constructCacheKeyFromWebsocketData(data);
         if (this.cache.has(cacheKey)) {
             this.logger.debug("Dropping duplicate message");
             return;
@@ -121,9 +133,7 @@ class WebSocketPool {
         if (typeof data === "string") {
             this.handleErrorMessages(data);
         }
-        for (const handler of this.messageListeners) {
-            handler(data);
-        }
+        await Promise.all(this.messageListeners.map((handler) => handler(data)));
     };
     sendRequest(request) {
         for (const rws of this.rwsPool) {

package/dist/cjs/util/buffer-util.d.ts

@@ -0,0 +1,7 @@
+import type { Data } from "isomorphic-ws";
+/**
+ * given a relatively unknown websocket frame data object,
+ * returns a valid Buffer instance that is safe to use
+ * isomorphically in any JS runtime environment
+ */
+export declare function bufferFromWebsocketData(data: Data): Promise<Buffer>;

package/dist/cjs/util/buffer-util.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bufferFromWebsocketData = bufferFromWebsocketData;
+// the linting rules don't allow importing anything that might clash with
+// a global, top-level import. we disable this rule because we need this
+// imported from our installed dependency
+// eslint-disable-next-line unicorn/prefer-node-protocol
+const buffer_1 = require("buffer");
+const BufferClassToUse = "Buffer" in globalThis ? globalThis.Buffer : buffer_1.Buffer;
+/**
+ * given a relatively unknown websocket frame data object,
+ * returns a valid Buffer instance that is safe to use
+ * isomorphically in any JS runtime environment
+ */
+async function bufferFromWebsocketData(data) {
+    if (typeof data === "string") {
+        return BufferClassToUse.from(new TextEncoder().encode(data).buffer);
+    }
+    if (data instanceof BufferClassToUse)
+        return data;
+    if (data instanceof Blob) {
+        // let the uncaught promise exception bubble up if there's an issue
+        return BufferClassToUse.from(await data.arrayBuffer());
+    }
+    if (data instanceof ArrayBuffer)
+        return BufferClassToUse.from(data);
+    if (Array.isArray(data)) {
+        // an array of buffers is highly unlikely, but it is a possibility
+        // indicated by the WebSocket Data interface
+        return BufferClassToUse.concat(data);
+    }
+    return data;
+}

package/dist/cjs/util/env-util.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Detects if this code is running within any Service or WebWorker context.
+ * @returns true if in a worker of some kind, false if otherwise
+ */
+export declare function envIsServiceOrWebWorker(): boolean;
+/**
+ * Detects if the code is running in a regular DOM or Web Worker context.
+ * @returns true if running in a DOM or Web Worker context, false if running in Node.js
+ */
+export declare function envIsBrowser(): boolean;
+/**
+ * a convenience method that returns whether or not
+ * this code is executing in some type of browser-centric environment
+ *
+ * @returns true if in the browser's main UI thread or in a worker, false if otherwise
+ */
+export declare function envIsBrowserOrWorker(): boolean;

package/dist/cjs/util/env-util.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envIsServiceOrWebWorker = envIsServiceOrWebWorker;
+exports.envIsBrowser = envIsBrowser;
+exports.envIsBrowserOrWorker = envIsBrowserOrWorker;
+// we create this local-only type, which has assertions made to indicate
+// that we do not know and cannot guarantee which JS environment we are in
+const g = globalThis;
+/**
+ * Detects if this code is running within any Service or WebWorker context.
+ * @returns true if in a worker of some kind, false if otherwise
+ */
+function envIsServiceOrWebWorker() {
+    return (typeof WorkerGlobalScope !== "undefined" &&
+        g.self instanceof WorkerGlobalScope);
+}
+/**
+ * Detects if the code is running in a regular DOM or Web Worker context.
+ * @returns true if running in a DOM or Web Worker context, false if running in Node.js
+ */
+function envIsBrowser() {
+    return g.window !== undefined;
+}
+/**
+ * a convenience method that returns whether or not
+ * this code is executing in some type of browser-centric environment
+ *
+ * @returns true if in the browser's main UI thread or in a worker, false if otherwise
+ */
+function envIsBrowserOrWorker() {
+    return envIsServiceOrWebWorker() || envIsBrowser();
+}

package/dist/cjs/util/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./buffer-util.js";
+export * from "./env-util.js";
+export * from "./url-util.js";

package/dist/cjs/util/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./buffer-util.js"), exports);
+__exportStar(require("./env-util.js"), exports);
+__exportStar(require("./url-util.js"), exports);

package/dist/cjs/util/url-util.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Given a URL to a hosted lazer stream service and a possible auth token,
+ * appends the auth token as a query parameter and returns the URL with the token
+ * contained within.
+ * If the URL provided is nullish, it is returned as-is (in the same nullish format).
+ * If the token is nullish, the baseUrl given is returned, instead.
+ */
+export declare function addAuthTokenToWebSocketUrl(baseUrl: string | null | undefined, authToken: string | null | undefined): string | null | undefined;

package/dist/cjs/util/url-util.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addAuthTokenToWebSocketUrl = addAuthTokenToWebSocketUrl;
+const ACCESS_TOKEN_QUERY_PARAM_KEY = "ACCESS_TOKEN";
+/**
+ * Given a URL to a hosted lazer stream service and a possible auth token,
+ * appends the auth token as a query parameter and returns the URL with the token
+ * contained within.
+ * If the URL provided is nullish, it is returned as-is (in the same nullish format).
+ * If the token is nullish, the baseUrl given is returned, instead.
+ */
+function addAuthTokenToWebSocketUrl(baseUrl, authToken) {
+    if (!baseUrl || !authToken)
+        return baseUrl;
+    const parsedUrl = new URL(baseUrl);
+    parsedUrl.searchParams.set(ACCESS_TOKEN_QUERY_PARAM_KEY, authToken);
+    return parsedUrl.toString();
+}

package/dist/esm/client.js

@@ -1,9 +1,9 @@
-import fetch from "cross-fetch";
 import WebSocket from "isomorphic-ws";
 import { dummyLogger } from "ts-log";
 import { DEFAULT_METADATA_SERVICE_URL, DEFAULT_PRICE_SERVICE_URL, } from "./constants.js";
 import { BINARY_UPDATE_FORMAT_MAGIC_LE, FORMAT_MAGICS_LE } from "./protocol.js";
 import { WebSocketPool } from "./socket/websocket-pool.js";
+import { bufferFromWebsocketData } from "./util/buffer-util.js";
 const UINT16_NUM_BYTES = 2;
 const UINT32_NUM_BYTES = 4;
 const UINT64_NUM_BYTES = 8;
@@ -56,55 +56,56 @@ export class PythLazerClient {
      */
     addMessageListener(handler) {
         const wsp = this.getWebSocketPool();
-        wsp.addMessageListener((data) => {
+        wsp.addMessageListener(async (data) => {
             if (typeof data == "string") {
                 handler({
                     type: "json",
                     value: JSON.parse(data),
                 });
+                return;
             }
-            else if (Buffer.isBuffer(data)) {
-                let pos = 0;
-                const magic = data.subarray(pos, pos + UINT32_NUM_BYTES).readUint32LE();
-                pos += UINT32_NUM_BYTES;
-                if (magic != BINARY_UPDATE_FORMAT_MAGIC_LE) {
-                    throw new Error("binary update format magic mismatch");
+            const buffData = await bufferFromWebsocketData(data);
+            let pos = 0;
+            const magic = buffData
+                .subarray(pos, pos + UINT32_NUM_BYTES)
+                .readUint32LE();
+            pos += UINT32_NUM_BYTES;
+            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.
+            const subscriptionId = Number(buffData.subarray(pos, pos + UINT64_NUM_BYTES).readBigInt64BE());
+            pos += UINT64_NUM_BYTES;
+            const value = { subscriptionId };
+            while (pos < buffData.length) {
+                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) {
+                    value.evm = buffData.subarray(pos, pos + len);
                 }
-                // TODO: some uint64 values may not be representable as Number.
-                const subscriptionId = Number(data.subarray(pos, pos + UINT64_NUM_BYTES).readBigInt64BE());
-                pos += UINT64_NUM_BYTES;
-                const value = { subscriptionId };
-                while (pos < data.length) {
-                    const len = data.subarray(pos, pos + UINT16_NUM_BYTES).readUint16BE();
-                    pos += UINT16_NUM_BYTES;
-                    const magic = data
-                        .subarray(pos, pos + UINT32_NUM_BYTES)
-                        .readUint32LE();
-                    if (magic == FORMAT_MAGICS_LE.EVM) {
-                        value.evm = data.subarray(pos, pos + len);
-                    }
-                    else if (magic == FORMAT_MAGICS_LE.SOLANA) {
-                        value.solana = data.subarray(pos, pos + len);
-                    }
-                    else if (magic == FORMAT_MAGICS_LE.LE_ECDSA) {
-                        value.leEcdsa = data.subarray(pos, pos + len);
-                    }
-                    else if (magic == FORMAT_MAGICS_LE.LE_UNSIGNED) {
-                        value.leUnsigned = data.subarray(pos, pos + len);
-                    }
-                    else if (magic == FORMAT_MAGICS_LE.JSON) {
-                        value.parsed = JSON.parse(data.subarray(pos + UINT32_NUM_BYTES, pos + len).toString());
-                    }
-                    else {
-                        throw new Error("unknown magic: " + magic.toString());
-                    }
-                    pos += len;
+                else if (magic == FORMAT_MAGICS_LE.SOLANA) {
+                    value.solana = buffData.subarray(pos, pos + len);
                 }
-                handler({ type: "binary", value });
-            }
-            else {
-                throw new TypeError("unexpected event data type");
+                else if (magic == FORMAT_MAGICS_LE.LE_ECDSA) {
+                    value.leEcdsa = buffData.subarray(pos, pos + len);
+                }
+                else if (magic == FORMAT_MAGICS_LE.LE_UNSIGNED) {
+                    value.leUnsigned = buffData.subarray(pos, pos + len);
+                }
+                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()}`);
+                }
+                pos += len;
             }
+            handler({ type: "binary", value });
         });
     }
     subscribe(request) {

package/dist/esm/protocol.d.ts

@@ -122,3 +122,6 @@ export type JsonUpdate = {
     leEcdsa?: JsonBinaryData;
     leUnsigned?: JsonBinaryData;
 };
+export declare enum CustomSocketClosureCodes {
+    CLIENT_TIMEOUT_BUT_RECONNECTING = 4000
+}

package/dist/esm/protocol.js

@@ -6,3 +6,7 @@ export const FORMAT_MAGICS_LE = {
     LE_ECDSA: 1_296_547_300,
     LE_UNSIGNED: 1_499_680_012,
 };
+export var CustomSocketClosureCodes;
+(function (CustomSocketClosureCodes) {
+    CustomSocketClosureCodes[CustomSocketClosureCodes["CLIENT_TIMEOUT_BUT_RECONNECTING"] = 4000] = "CLIENT_TIMEOUT_BUT_RECONNECTING";
+})(CustomSocketClosureCodes || (CustomSocketClosureCodes = {}));

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

@@ -10,6 +10,19 @@ export type ResilientWebSocketConfig = {
     maxRetryDelayMs?: number;
     logAfterRetryCount?: number;
 };
+/**
+ * the isomorphic-ws package ships with some slightly-erroneous typings.
+ * namely, it returns a WebSocket with typings that indicate the "terminate()" function
+ * is available on all platforms.
+ * Given that, under the hood, it is using the globalThis.WebSocket class, if it's available,
+ * and falling back to using the https://www.npmjs.com/package/ws package, this
+ * means there are API differences between the native WebSocket (the one in a web browser)
+ * and the server-side version from the "ws" package.
+ *
+ * This type creates a WebSocket type reference we use to indicate the unknown
+ * nature of the env in which is code is run.
+ */
+type UnsafeWebSocket = Omit<WebSocket, "terminate"> & Partial<Pick<WebSocket, "terminate">>;
 export declare class ResilientWebSocket {
     private endpoint;
     private wsOptions?;
@@ -17,7 +30,7 @@ export declare class ResilientWebSocket {
     private heartbeatTimeoutDurationMs;
     private maxRetryDelayMs;
     private logAfterRetryCount;
-    wsClient: undefined | WebSocket;
+    wsClient: UnsafeWebSocket | undefined;
     wsUserClosed: boolean;
     private wsFailedAttempts;
     private heartbeatTimeout?;
@@ -47,3 +60,4 @@ export declare class ResilientWebSocket {
      */
     private retryDelayMs;
 }
+export {};

package/dist/esm/socket/resilient-websocket.js

@@ -1,5 +1,7 @@
 import WebSocket from "isomorphic-ws";
 import { dummyLogger } from "ts-log";
+import { CustomSocketClosureCodes } from "../protocol.js";
+import { envIsBrowserOrWorker } from "../util/env-util.js";
 const DEFAULT_HEARTBEAT_TIMEOUT_DURATION_MS = 5000; // 5 seconds
 const DEFAULT_MAX_RETRY_DELAY_MS = 1000; // 1 second'
 const DEFAULT_LOG_AFTER_RETRY_COUNT = 10;
@@ -74,7 +76,10 @@ export class ResilientWebSocket {
             clearTimeout(this.retryTimeout);
             this.retryTimeout = undefined;
         }
-        this.wsClient = new WebSocket(this.endpoint, this.wsOptions);
+        // browser constructor supports a different 2nd argument for the constructor,
+        // so we need to ensure it's not included if we're running in that environment:
+        // https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket#protocols
+        this.wsClient = new WebSocket(this.endpoint, envIsBrowserOrWorker() ? undefined : this.wsOptions);
         this.wsClient.addEventListener("open", () => {
             this.logger.info("WebSocket connection established");
             this.wsFailedAttempts = 0;
@@ -112,8 +117,19 @@ export class ResilientWebSocket {
             clearTimeout(this.heartbeatTimeout);
         }
         this.heartbeatTimeout = setTimeout(() => {
-            this.logger.warn("Connection timed out. Reconnecting...");
-            this.wsClient?.terminate();
+            const warnMsg = "Connection timed out. Reconnecting...";
+            this.logger.warn(warnMsg);
+            if (this.wsClient) {
+                if (typeof this.wsClient.terminate === "function") {
+                    this.wsClient.terminate();
+                }
+                else {
+                    // terminate is an implementation detail of the node-friendly
+                    // https://www.npmjs.com/package/ws package, but is not a native WebSocket API,
+                    // so we have to use the close method
+                    this.wsClient.close(CustomSocketClosureCodes.CLIENT_TIMEOUT_BUT_RECONNECTING, warnMsg);
+                }
+            }
             this.handleReconnect();
         }, this.heartbeatTimeoutDurationMs);
     }

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

@@ -4,6 +4,7 @@ import type { Logger } from "ts-log";
 import type { Request } from "../protocol.js";
 import type { ResilientWebSocketConfig } from "./resilient-websocket.js";
 import { ResilientWebSocket } from "./resilient-websocket.js";
+type WebSocketOnMessageCallback = (data: WebSocket.Data) => void | Promise<void>;
 export type WebSocketPoolConfig = {
     urls?: string[];
     numConnections?: number;
@@ -33,15 +34,16 @@ export declare class WebSocketPool {
      * Checks for error responses in JSON messages and throws appropriate errors
      */
     private handleErrorMessages;
+    private constructCacheKeyFromWebsocketData;
     /**
      * Handles incoming websocket messages by deduplicating identical messages received across
      * multiple connections before forwarding to registered handlers
      */
-    dedupeHandler: (data: WebSocket.Data) => void;
+    dedupeHandler: (data: WebSocket.Data) => Promise<void>;
     sendRequest(request: Request): void;
     addSubscription(request: Request): void;
     removeSubscription(subscriptionId: number): void;
-    addMessageListener(handler: (data: WebSocket.Data) => void): void;
+    addMessageListener(handler: WebSocketOnMessageCallback): void;
     /**
      * Calls the handler if all websocket connections are currently down or in reconnecting state.
      * The connections may still try to reconnect in the background.
@@ -52,3 +54,4 @@ export declare class WebSocketPool {
     private checkConnectionStates;
     shutdown(): void;
 }
+export {};

package/dist/esm/socket/websocket-pool.js

@@ -3,6 +3,7 @@ import WebSocket from "isomorphic-ws";
 import { dummyLogger } from "ts-log";
 import { ResilientWebSocket } from "./resilient-websocket.js";
 import { DEFAULT_STREAM_SERVICE_0_URL, DEFAULT_STREAM_SERVICE_1_URL, } from "../constants.js";
+import { addAuthTokenToWebSocketUrl, bufferFromWebsocketData, envIsBrowserOrWorker, } from "../util/index.js";
 const DEFAULT_NUM_CONNECTIONS = 4;
 export class WebSocketPool {
     logger;
@@ -42,15 +43,17 @@ export class WebSocketPool {
         const pool = new WebSocketPool(log);
         const numConnections = config.numConnections ?? DEFAULT_NUM_CONNECTIONS;
         for (let i = 0; i < numConnections; i++) {
-            const url = urls[i % urls.length];
+            const baseUrl = urls[i % urls.length];
+            const isBrowser = envIsBrowserOrWorker();
+            const url = isBrowser
+                ? addAuthTokenToWebSocketUrl(baseUrl, token)
+                : baseUrl;
             if (!url) {
                 throw new Error(`URLs must not be null or empty`);
             }
             const wsOptions = {
                 ...config.rwsConfig?.wsOptions,
-                headers: {
-                    Authorization: `Bearer ${token}`,
-                },
+                headers: isBrowser ? undefined : { Authorization: `Bearer ${token}` },
             };
             const rws = new ResilientWebSocket({
                 ...config.rwsConfig,
@@ -77,7 +80,12 @@ export class WebSocketPool {
                 rws.onError = config.onError;
             }
             // Handle all client messages ourselves. Dedupe before sending to registered message handlers.
-            rws.onMessage = pool.dedupeHandler;
+            rws.onMessage = (data) => {
+                pool.dedupeHandler(data).catch((error) => {
+                    const errMsg = `An error occurred in the WebSocket pool's dedupeHandler: ${error instanceof Error ? error.message : String(error)}`;
+                    throw new Error(errMsg);
+                });
+            };
             pool.rwsPool.push(rws);
             rws.startWebSocket();
         }
@@ -100,14 +108,18 @@ export class WebSocketPool {
             throw new Error(`Error: ${message.error}`);
         }
     }
+    async constructCacheKeyFromWebsocketData(data) {
+        if (typeof data === "string")
+            return data;
+        const buff = await bufferFromWebsocketData(data);
+        return buff.toString("hex");
+    }
     /**
      * Handles incoming websocket messages by deduplicating identical messages received across
      * multiple connections before forwarding to registered handlers
      */
-    dedupeHandler = (data) => {
-        const cacheKey = typeof data === "string"
-            ? data
-            : Buffer.from(data).toString("hex");
+    dedupeHandler = async (data) => {
+        const cacheKey = await this.constructCacheKeyFromWebsocketData(data);
         if (this.cache.has(cacheKey)) {
             this.logger.debug("Dropping duplicate message");
             return;
@@ -116,9 +128,7 @@ export class WebSocketPool {
         if (typeof data === "string") {
             this.handleErrorMessages(data);
         }
-        for (const handler of this.messageListeners) {
-            handler(data);
-        }
+        await Promise.all(this.messageListeners.map((handler) => handler(data)));
     };
     sendRequest(request) {
         for (const rws of this.rwsPool) {

package/dist/esm/util/buffer-util.d.ts

@@ -0,0 +1,7 @@
+import type { Data } from "isomorphic-ws";
+/**
+ * given a relatively unknown websocket frame data object,
+ * returns a valid Buffer instance that is safe to use
+ * isomorphically in any JS runtime environment
+ */
+export declare function bufferFromWebsocketData(data: Data): Promise<Buffer>;

package/dist/esm/util/buffer-util.js

@@ -0,0 +1,30 @@
+// the linting rules don't allow importing anything that might clash with
+// a global, top-level import. we disable this rule because we need this
+// imported from our installed dependency
+// eslint-disable-next-line unicorn/prefer-node-protocol
+import { Buffer as BrowserBuffer } from "buffer";
+const BufferClassToUse = "Buffer" in globalThis ? globalThis.Buffer : BrowserBuffer;
+/**
+ * given a relatively unknown websocket frame data object,
+ * returns a valid Buffer instance that is safe to use
+ * isomorphically in any JS runtime environment
+ */
+export async function bufferFromWebsocketData(data) {
+    if (typeof data === "string") {
+        return BufferClassToUse.from(new TextEncoder().encode(data).buffer);
+    }
+    if (data instanceof BufferClassToUse)
+        return data;
+    if (data instanceof Blob) {
+        // let the uncaught promise exception bubble up if there's an issue
+        return BufferClassToUse.from(await data.arrayBuffer());
+    }
+    if (data instanceof ArrayBuffer)
+        return BufferClassToUse.from(data);
+    if (Array.isArray(data)) {
+        // an array of buffers is highly unlikely, but it is a possibility
+        // indicated by the WebSocket Data interface
+        return BufferClassToUse.concat(data);
+    }
+    return data;
+}

package/dist/esm/util/env-util.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Detects if this code is running within any Service or WebWorker context.
+ * @returns true if in a worker of some kind, false if otherwise
+ */
+export declare function envIsServiceOrWebWorker(): boolean;
+/**
+ * Detects if the code is running in a regular DOM or Web Worker context.
+ * @returns true if running in a DOM or Web Worker context, false if running in Node.js
+ */
+export declare function envIsBrowser(): boolean;
+/**
+ * a convenience method that returns whether or not
+ * this code is executing in some type of browser-centric environment
+ *
+ * @returns true if in the browser's main UI thread or in a worker, false if otherwise
+ */
+export declare function envIsBrowserOrWorker(): boolean;

package/dist/esm/util/env-util.js

@@ -0,0 +1,27 @@
+// we create this local-only type, which has assertions made to indicate
+// that we do not know and cannot guarantee which JS environment we are in
+const g = globalThis;
+/**
+ * Detects if this code is running within any Service or WebWorker context.
+ * @returns true if in a worker of some kind, false if otherwise
+ */
+export function envIsServiceOrWebWorker() {
+    return (typeof WorkerGlobalScope !== "undefined" &&
+        g.self instanceof WorkerGlobalScope);
+}
+/**
+ * Detects if the code is running in a regular DOM or Web Worker context.
+ * @returns true if running in a DOM or Web Worker context, false if running in Node.js
+ */
+export function envIsBrowser() {
+    return g.window !== undefined;
+}
+/**
+ * a convenience method that returns whether or not
+ * this code is executing in some type of browser-centric environment
+ *
+ * @returns true if in the browser's main UI thread or in a worker, false if otherwise
+ */
+export function envIsBrowserOrWorker() {
+    return envIsServiceOrWebWorker() || envIsBrowser();
+}

package/dist/esm/util/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./buffer-util.js";
+export * from "./env-util.js";
+export * from "./url-util.js";

package/dist/esm/util/index.js

@@ -0,0 +1,3 @@
+export * from "./buffer-util.js";
+export * from "./env-util.js";
+export * from "./url-util.js";

package/dist/esm/util/url-util.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Given a URL to a hosted lazer stream service and a possible auth token,
+ * appends the auth token as a query parameter and returns the URL with the token
+ * contained within.
+ * If the URL provided is nullish, it is returned as-is (in the same nullish format).
+ * If the token is nullish, the baseUrl given is returned, instead.
+ */
+export declare function addAuthTokenToWebSocketUrl(baseUrl: string | null | undefined, authToken: string | null | undefined): string | null | undefined;

package/dist/esm/util/url-util.js

@@ -0,0 +1,15 @@
+const ACCESS_TOKEN_QUERY_PARAM_KEY = "ACCESS_TOKEN";
+/**
+ * Given a URL to a hosted lazer stream service and a possible auth token,
+ * appends the auth token as a query parameter and returns the URL with the token
+ * contained within.
+ * If the URL provided is nullish, it is returned as-is (in the same nullish format).
+ * If the token is nullish, the baseUrl given is returned, instead.
+ */
+export function addAuthTokenToWebSocketUrl(baseUrl, authToken) {
+    if (!baseUrl || !authToken)
+        return baseUrl;
+    const parsedUrl = new URL(baseUrl);
+    parsedUrl.searchParams.set(ACCESS_TOKEN_QUERY_PARAM_KEY, authToken);
+    return parsedUrl.toString();
+}

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@pythnetwork/pyth-lazer-sdk",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Pyth Lazer SDK",
+  "engines": {
+    "node": ">=22"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -48,7 +51,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@isaacs/ttlcache": "^1.4.1",
-    "cross-fetch": "^4.0.0",
+    "buffer": "^6.0.3",
     "isomorphic-ws": "^5.0.0",
     "ts-log": "^2.2.7",
     "ws": "^8.18.0"