@pythnetwork/pyth-lazer-sdk 6.2.1 → 6.2.3

package/README.md

@@ -60,3 +60,77 @@ c.subscribe({
   jsonBinaryEncoding: "hex",
 });
 ```
+
+## Error callbacks and outage detection
+
+The SDK exposes two error callbacks and an "all connections down" listener that
+serve distinct purposes. Choose what to handle based on whether you want
+visibility into per-socket churn or a signal that the price stream has actually
+stopped.
+
+### `onWebSocketError` (per-socket errors)
+
+Passed via `webSocketPoolConfig.onWebSocketError`. Fires for individual
+socket-level errors on a single underlying WebSocket — for example, a transient
+`502` from one endpoint during a server upgrade or chaos test:
+
+```json
+{
+  "at": "pyth#connect",
+  "level": "ERROR",
+  "error": "Unexpected server response: 502"
+}
+```
+
+**In most cases you never need to handle `onWebSocketError` — it is purely
+informational.** The pool manages each socket's lifecycle (reconnect, retry,
+failover across the configured URLs), so these errors are expected churn when
+one endpoint hiccups. When the SDK is configured with redundant connections
+(`numConnections > 1`, multiple `urls`), a single socket failing does **not**
+mean the stream is dark — the other connections continue delivering messages.
+Treat it as diagnostic only; don't page or alert on it.
+
+### `onWebSocketPoolError` (pool-level errors)
+
+Passed via `webSocketPoolConfig.onWebSocketPoolError`. Fires for errors that
+originate from the pool itself rather than a single socket — server-sent
+`subscriptionError`/`error` messages, exceptions thrown by your message
+listeners, send failures, and other internal errors that would otherwise
+surface as unhandled rejections. Applications should listen to this and surface
+it (log, alert, etc.).
+
+```javascript
+webSocketPoolConfig: {
+  onWebSocketError: (error) => {
+    // Individual socket error — usually safe to log at info/debug.
+    console.warn("websocket error (single connection):", error.message);
+  },
+  onWebSocketPoolError: (error) => {
+    // Pool-level error — surface this.
+    console.error("websocket pool error:", error);
+  },
+},
+```
+
+### `addAllConnectionsDownListener` (stream is dark)
+
+Registered on the client. Fires when **every** redundant connection is down or
+reconnecting at the same time — i.e., the price stream really has stopped.
+This is the right signal for outage detection and paging:
+
+```javascript
+c.addAllConnectionsDownListener(() => {
+  console.error("All Lazer connections are down — stream is dark.");
+});
+```
+
+A matching `addConnectionRestoredListener` fires when at least one connection
+comes back after an all-down period.
+
+### Recommendation
+
+For detecting real outages, handle `onWebSocketPoolError` and
+`addAllConnectionsDownListener`. Do not page or panic solely on
+`onWebSocketError` when the SDK is configured with redundant endpoints and
+prices are still flowing — individual sockets are expected to flap during
+server upgrades and chaos tests.

package/dist/cjs/constants.cjs

@@ -30,7 +30,7 @@ _export(exports, {
 });
 const SOLANA_LAZER_PROGRAM_ID = "pytd2yyk641x7ak7mkaasSJVXh6YYZnC7wTmtgAyxPt";
 const SOLANA_LAZER_STORAGE_ID = "3rdJbqfnagQ4yx9HXJViD4zc4xpiSqmFsKpPuSCQVyQL";
-const DEFAULT_METADATA_SERVICE_URL = "https://history.pyth-lazer.dourolabs.app/history";
+const DEFAULT_METADATA_SERVICE_URL = "https://pyth.dourolabs.app";
 const DEFAULT_PRICE_SERVICE_URL = "https://pyth-lazer-0.dourolabs.app";
 const DEFAULT_STREAM_SERVICE_0_URL = "wss://pyth-lazer-0.dourolabs.app/v1/stream";
 const DEFAULT_STREAM_SERVICE_1_URL = "wss://pyth-lazer-1.dourolabs.app/v1/stream";

package/dist/cjs/constants.d.ts

@@ -1,6 +1,6 @@
 export declare const SOLANA_LAZER_PROGRAM_ID = "pytd2yyk641x7ak7mkaasSJVXh6YYZnC7wTmtgAyxPt";
 export declare const SOLANA_LAZER_STORAGE_ID = "3rdJbqfnagQ4yx9HXJViD4zc4xpiSqmFsKpPuSCQVyQL";
-export declare const DEFAULT_METADATA_SERVICE_URL = "https://history.pyth-lazer.dourolabs.app/history";
+export declare const DEFAULT_METADATA_SERVICE_URL = "https://pyth.dourolabs.app";
 export declare const DEFAULT_PRICE_SERVICE_URL = "https://pyth-lazer-0.dourolabs.app";
 export declare const DEFAULT_STREAM_SERVICE_0_URL = "wss://pyth-lazer-0.dourolabs.app/v1/stream";
 export declare const DEFAULT_STREAM_SERVICE_1_URL = "wss://pyth-lazer-1.dourolabs.app/v1/stream";

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

@@ -84,46 +84,68 @@ class ResilientWebSocket {
             this.logger.info("WebSocket client already started.");
             return;
         }
-        if (this.wsFailedAttempts == 0) {
+        if (this.wsFailedAttempts === 0) {
             this.logger.info(`Creating Web Socket client`);
         }
         if (this.retryTimeout !== undefined) {
             clearTimeout(this.retryTimeout);
             this.retryTimeout = undefined;
         }
-        // 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 _isomorphicws.default(this.endpoint, (0, _envutil.envIsBrowserOrWorker)() ? undefined : this.wsOptions);
-        this.wsClient.addEventListener("open", ()=>{
-            this.logger.info("WebSocket connection established");
-            this.wsFailedAttempts = 0;
-            this._isReconnecting = false;
-            this.resetHeartbeat();
-            this.onReconnect();
-        });
-        this.wsClient.addEventListener("close", (e)=>{
-            if (this.wsUserClosed) {
-                this.logger.info(`WebSocket connection to ${this.endpoint} closed by user`);
-            } else {
-                if (this.shouldLogRetry()) {
-                    this.logger.warn(`WebSocket connection to ${this.endpoint} closed unexpectedly: Code: ${e.code.toString()}`);
+        // we wrap the new WebSocket() construction in a try / catch because,
+        // if one of our instances legitimately goes down or there's some network
+        // error that impacts connectivity, the WebSocket constructor will throw
+        // an uncaught DOMException in the browser (or equivalent in Node, Bun or Deno)
+        // and potentially blow up the process (if running in Node, Bun or Deno)
+        try {
+            // 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 _isomorphicws.default(this.endpoint, (0, _envutil.envIsBrowserOrWorker)() ? undefined : this.wsOptions);
+            this.wsClient.addEventListener("open", ()=>{
+                this.logger.info("WebSocket connection established");
+                this.wsFailedAttempts = 0;
+                this._isReconnecting = false;
+                this.resetHeartbeat();
+                try {
+                    this.onReconnect();
+                } catch (error) {
+                    this.logger.error("Error in onReconnect callback:", error);
                 }
-                this.handleReconnect();
-            }
-        });
-        this.wsClient.addEventListener("error", (event)=>{
-            this.onError(event);
-        });
-        this.wsClient.addEventListener("message", (event)=>{
-            this.resetHeartbeat();
-            this.onMessage(event.data);
-        });
-        if ("on" in this.wsClient) {
-            this.wsClient.on("ping", ()=>{
-                this.logger.info("Ping received");
+            });
+            this.wsClient.addEventListener("close", (e)=>{
+                if (this.wsUserClosed) {
+                    this.logger.info(`WebSocket connection to ${this.endpoint} closed by user`);
+                } else {
+                    if (this.shouldLogRetry()) {
+                        this.logger.warn(`WebSocket connection to ${this.endpoint} closed unexpectedly: Code: ${e.code.toString()}`);
+                    }
+                    this.handleReconnect();
+                }
+            });
+            this.wsClient.addEventListener("error", (event)=>{
+                try {
+                    this.onError(event);
+                } catch (error) {
+                    this.logger.error("Error in onError callback:", error);
+                }
+            });
+            this.wsClient.addEventListener("message", (event)=>{
                 this.resetHeartbeat();
+                try {
+                    this.onMessage(event.data);
+                } catch (error) {
+                    this.logger.error("Error in onMessage callback:", error);
+                }
             });
+            if (typeof this.wsClient?.on === "function") {
+                this.wsClient.on("ping", ()=>{
+                    this.logger.debug("Ping received");
+                    this.resetHeartbeat();
+                });
+            }
+        } catch (error) {
+            this.logger.error("Failed to create WebSocket client:", error);
+            this.handleReconnect();
         }
     }
     resetHeartbeat() {
@@ -133,7 +155,11 @@ class ResilientWebSocket {
         this.heartbeatTimeout = setTimeout(()=>{
             const warnMsg = "Connection timed out. Reconnecting...";
             this.logger.warn(warnMsg);
-            this.onTimeout();
+            try {
+                this.onTimeout();
+            } catch (error) {
+                this.logger.error("Error in onTimeout callback:", error);
+            }
             if (this.wsClient) {
                 if (typeof this.wsClient.terminate === "function") {
                     this.wsClient.terminate();
@@ -144,7 +170,8 @@ class ResilientWebSocket {
                     this.wsClient.close(_protocol.CustomSocketClosureCodes.CLIENT_TIMEOUT_BUT_RECONNECTING, warnMsg);
                 }
             }
-            this.handleReconnect();
+        // No direct call to handleReconnect() here
+        // terminate/close will trigger the 'close' event, which will call it.
         }, this.heartbeatTimeoutDurationMs);
     }
     handleReconnect() {
@@ -169,11 +196,12 @@ class ResilientWebSocket {
         }, this.retryDelayMs());
     }
     closeWebSocket() {
-        if (this.wsClient !== undefined) {
+        // immediately block duplicate calls to this function
+        this.wsUserClosed = true;
+        if (typeof this.wsClient?.close === "function") {
             this.wsClient.close();
             this.wsClient = undefined;
         }
-        this.wsUserClosed = true;
     }
     /**
    * Calculates the delay in milliseconds for exponential backoff based on the number of failed attempts.

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

@@ -8,17 +8,12 @@ Object.defineProperty(exports, "WebSocketPool", {
         return WebSocketPool;
     }
 });
-const _ttlcache = /*#__PURE__*/ _interop_require_default(require("@isaacs/ttlcache"));
+const _ttlcache = require("@isaacs/ttlcache");
 const _tslog = require("ts-log");
 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
-    };
-}
 const DEFAULT_NUM_CONNECTIONS = 4;
 class WebSocketPool extends _index.IsomorphicEventEmitter {
     logger;
@@ -36,7 +31,7 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
     constructor(logger){
         super(), this.logger = logger;
         this.rwsPool = [];
-        this.cache = new _ttlcache.default({
+        this.cache = new _ttlcache.TTLCache({
             ttl: 1000 * 10
         }); // TTL of 10 seconds
         this.subscriptions = new Map();

package/dist/esm/constants.d.ts

@@ -1,6 +1,6 @@
 export declare const SOLANA_LAZER_PROGRAM_ID = "pytd2yyk641x7ak7mkaasSJVXh6YYZnC7wTmtgAyxPt";
 export declare const SOLANA_LAZER_STORAGE_ID = "3rdJbqfnagQ4yx9HXJViD4zc4xpiSqmFsKpPuSCQVyQL";
-export declare const DEFAULT_METADATA_SERVICE_URL = "https://history.pyth-lazer.dourolabs.app/history";
+export declare const DEFAULT_METADATA_SERVICE_URL = "https://pyth.dourolabs.app";
 export declare const DEFAULT_PRICE_SERVICE_URL = "https://pyth-lazer-0.dourolabs.app";
 export declare const DEFAULT_STREAM_SERVICE_0_URL = "wss://pyth-lazer-0.dourolabs.app/v1/stream";
 export declare const DEFAULT_STREAM_SERVICE_1_URL = "wss://pyth-lazer-1.dourolabs.app/v1/stream";

package/dist/esm/constants.mjs

@@ -1,6 +1,6 @@
 export const SOLANA_LAZER_PROGRAM_ID = "pytd2yyk641x7ak7mkaasSJVXh6YYZnC7wTmtgAyxPt";
 export const SOLANA_LAZER_STORAGE_ID = "3rdJbqfnagQ4yx9HXJViD4zc4xpiSqmFsKpPuSCQVyQL";
-export const DEFAULT_METADATA_SERVICE_URL = "https://history.pyth-lazer.dourolabs.app/history";
+export const DEFAULT_METADATA_SERVICE_URL = "https://pyth.dourolabs.app";
 export const DEFAULT_PRICE_SERVICE_URL = "https://pyth-lazer-0.dourolabs.app";
 export const DEFAULT_STREAM_SERVICE_0_URL = "wss://pyth-lazer-0.dourolabs.app/v1/stream";
 export const DEFAULT_STREAM_SERVICE_1_URL = "wss://pyth-lazer-1.dourolabs.app/v1/stream";

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

@@ -69,46 +69,68 @@ export class ResilientWebSocket {
             this.logger.info("WebSocket client already started.");
             return;
         }
-        if (this.wsFailedAttempts == 0) {
+        if (this.wsFailedAttempts === 0) {
             this.logger.info(`Creating Web Socket client`);
         }
         if (this.retryTimeout !== undefined) {
             clearTimeout(this.retryTimeout);
             this.retryTimeout = undefined;
         }
-        // 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;
-            this._isReconnecting = false;
-            this.resetHeartbeat();
-            this.onReconnect();
-        });
-        this.wsClient.addEventListener("close", (e)=>{
-            if (this.wsUserClosed) {
-                this.logger.info(`WebSocket connection to ${this.endpoint} closed by user`);
-            } else {
-                if (this.shouldLogRetry()) {
-                    this.logger.warn(`WebSocket connection to ${this.endpoint} closed unexpectedly: Code: ${e.code.toString()}`);
+        // we wrap the new WebSocket() construction in a try / catch because,
+        // if one of our instances legitimately goes down or there's some network
+        // error that impacts connectivity, the WebSocket constructor will throw
+        // an uncaught DOMException in the browser (or equivalent in Node, Bun or Deno)
+        // and potentially blow up the process (if running in Node, Bun or Deno)
+        try {
+            // 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;
+                this._isReconnecting = false;
+                this.resetHeartbeat();
+                try {
+                    this.onReconnect();
+                } catch (error) {
+                    this.logger.error("Error in onReconnect callback:", error);
                 }
-                this.handleReconnect();
-            }
-        });
-        this.wsClient.addEventListener("error", (event)=>{
-            this.onError(event);
-        });
-        this.wsClient.addEventListener("message", (event)=>{
-            this.resetHeartbeat();
-            this.onMessage(event.data);
-        });
-        if ("on" in this.wsClient) {
-            this.wsClient.on("ping", ()=>{
-                this.logger.info("Ping received");
+            });
+            this.wsClient.addEventListener("close", (e)=>{
+                if (this.wsUserClosed) {
+                    this.logger.info(`WebSocket connection to ${this.endpoint} closed by user`);
+                } else {
+                    if (this.shouldLogRetry()) {
+                        this.logger.warn(`WebSocket connection to ${this.endpoint} closed unexpectedly: Code: ${e.code.toString()}`);
+                    }
+                    this.handleReconnect();
+                }
+            });
+            this.wsClient.addEventListener("error", (event)=>{
+                try {
+                    this.onError(event);
+                } catch (error) {
+                    this.logger.error("Error in onError callback:", error);
+                }
+            });
+            this.wsClient.addEventListener("message", (event)=>{
                 this.resetHeartbeat();
+                try {
+                    this.onMessage(event.data);
+                } catch (error) {
+                    this.logger.error("Error in onMessage callback:", error);
+                }
             });
+            if (typeof this.wsClient?.on === "function") {
+                this.wsClient.on("ping", ()=>{
+                    this.logger.debug("Ping received");
+                    this.resetHeartbeat();
+                });
+            }
+        } catch (error) {
+            this.logger.error("Failed to create WebSocket client:", error);
+            this.handleReconnect();
         }
     }
     resetHeartbeat() {
@@ -118,7 +140,11 @@ export class ResilientWebSocket {
         this.heartbeatTimeout = setTimeout(()=>{
             const warnMsg = "Connection timed out. Reconnecting...";
             this.logger.warn(warnMsg);
-            this.onTimeout();
+            try {
+                this.onTimeout();
+            } catch (error) {
+                this.logger.error("Error in onTimeout callback:", error);
+            }
             if (this.wsClient) {
                 if (typeof this.wsClient.terminate === "function") {
                     this.wsClient.terminate();
@@ -129,7 +155,8 @@ export class ResilientWebSocket {
                     this.wsClient.close(CustomSocketClosureCodes.CLIENT_TIMEOUT_BUT_RECONNECTING, warnMsg);
                 }
             }
-            this.handleReconnect();
+        // No direct call to handleReconnect() here
+        // terminate/close will trigger the 'close' event, which will call it.
         }, this.heartbeatTimeoutDurationMs);
     }
     handleReconnect() {
@@ -154,11 +181,12 @@ export class ResilientWebSocket {
         }, this.retryDelayMs());
     }
     closeWebSocket() {
-        if (this.wsClient !== undefined) {
+        // immediately block duplicate calls to this function
+        this.wsUserClosed = true;
+        if (typeof this.wsClient?.close === "function") {
             this.wsClient.close();
             this.wsClient = undefined;
         }
-        this.wsUserClosed = true;
     }
     /**
    * Calculates the delay in milliseconds for exponential backoff based on the number of failed attempts.

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

@@ -1,4 +1,4 @@
-import TTLCache from "@isaacs/ttlcache";
+import { TTLCache } from "@isaacs/ttlcache";
 import { dummyLogger } from "ts-log";
 import { DEFAULT_STREAM_SERVICE_0_URL, DEFAULT_STREAM_SERVICE_1_URL } from "../constants.mjs";
 import { IsomorphicEventEmitter } from "../emitter/index.mjs";

package/package.json

@@ -1,20 +1,20 @@
 {
   "bugs": {
-    "url": "https://github.com/pyth-network/pyth-crosschain/issues"
+    "url": "https://github.com/pyth-network/pyth-lazer-public/issues"
   },
   "dependencies": {
-    "@isaacs/ttlcache": "^1.4.1",
-    "buffer": "^6.0.3",
-    "isomorphic-ws": "^5.0.0",
-    "ts-log": "^2.2.7",
-    "ws": "^8.19.0"
+    "@isaacs/ttlcache": "catalog:",
+    "buffer": "catalog:",
+    "isomorphic-ws": "catalog:",
+    "ts-log": "catalog:",
+    "ws": "catalog:"
   },
   "description": "Pyth Lazer SDK",
   "devDependencies": {
-    "@cprussin/tsconfig": "^4.0.2",
-    "@types/node": "^24.10.1",
-    "@types/ws": "^8.18.1",
-    "typedoc": "^0.28.17"
+    "@cprussin/tsconfig": "catalog:",
+    "@types/node": "catalog:",
+    "@types/ws": "catalog:",
+    "typedoc": "catalog:"
   },
   "engines": {
     "node": "^24.0.0"
@@ -135,7 +135,7 @@
   "files": [
     "dist/**/*"
   ],
-  "homepage": "https://github.com/pyth-network/pyth-crosschain/tree/main/lazer/sdk/js",
+  "homepage": "https://github.com/pyth-network/pyth-lazer-public/tree/main/sdk/js",
   "keywords": [
     "pyth",
     "oracle"
@@ -148,9 +148,9 @@
     "access": "public"
   },
   "repository": {
-    "directory": "lazer/sdk/js",
+    "directory": "sdk/js",
     "type": "git",
-    "url": "https://github.com/pyth-network/pyth-crosschain"
+    "url": "https://github.com/pyth-network/pyth-lazer-public"
   },
   "scripts": {
     "build": "ts-duality --clean",
@@ -164,5 +164,5 @@
   },
   "type": "module",
   "types": "./dist/cjs/index.d.ts",
-  "version": "6.2.1"
+  "version": "6.2.3"
 }