@pythnetwork/pyth-lazer-sdk 6.2.4 → 7.0.0

package/README.md

@@ -9,58 +9,81 @@ See [contributing.md](docs/contributing/contributing.md) for information on how
 ```javascript
 import { PythLazerClient } from "@pythnetwork/pyth-lazer-sdk";
 
-const c = await PythLazerClient.create({
+const client = await PythLazerClient.create({
+  // Your Lazer access token.
+  // The SDK sends it during the WebSocket handshake via
+  // `Sec-WebSocket-Protocol`.
+  // refer to the "Authentication" section, below.
   token: "YOUR-AUTH-TOKEN-HERE",
-  logger: console, // Optionally log operations (to the console in this case.)
+  logger: console, // Optional. Customize where connection logs are routed
   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) => {
+    // Optional.
+    // Parallel redundant connections, round-robined across `urls`, to
+    // reduce dropped messages.
+    // Default is 4.
+    numConnections: 4,
+
+    // Optional.
+    // Override the stream endpoint(s). Round-robined across `numConnections`.
+    // Defaults to the api service instances (pyth-0/1/2.dourolabs.app).
+    // urls: ["wss://pyth-0.dourolabs.app/v1/prices/stream"],
+    onWebSocketError: (error) => {
       console.error("⛔️ WebSocket error:", error.message);
     },
-    // Optional configuration for resilient WebSocket connections
+
+    // Optional.
+    // Tune the underlying resilient connections. Auth, endpoint, and logger
+    // are managed by the SDK and cannot be set here.
     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
+      heartbeatTimeoutDurationMs: 5000, // Reconnect if no message/ping within this window.
+      maxRetryDelayMs: 1000, // Cap on exponential reconnect backoff.
+      logAfterRetryCount: 10, // Log every Nth failed reconnect attempt.
     },
   },
 });
 
-c.addMessageListener((message) => {
+client.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(() => {
+// Fires when every connection is down at once.
+// Connections keep retrying in the background
+client.addAllConnectionsDownListener(() => {
   console.error("All connections are down!");
 });
 
-// Create and remove one or more subscriptions on the fly
-c.subscribe({
+// Subscribe on the fly.
+client.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"],
+  formats: [],
   deliveryFormat: "json",
   channel: "fixed_rate@200ms",
   parsed: true,
-  jsonBinaryEncoding: "hex",
 });
 ```
 
+## Authentication
+
+Pass your access token as `token` — that is the only auth step. The SDK sends it
+to the server during the WebSocket handshake via the **`Sec-WebSocket-Protocol`**
+header (`Sec-WebSocket-Protocol: pyth-lazer-auth, <token>`), the same way in the
+browser and in Node. It is never placed in the URL as a query parameter, so the
+token stays out of URLs, browser history, and proxy/server access logs — worth
+knowing if you care about credential hygiene.
+
+Connections default to the redundant Lazer api service stream instances
+(`wss://pyth-{0,1,2}.dourolabs.app/v1/prices/stream`), round-robined across
+`numConnections` (override via `webSocketPoolConfig.urls`). They serve parsed /
+unsigned JSON updates; signed `evm` / `solana` update payloads are not served on
+this stream.
+
+> **v7 breaking change:** the token moved from `?ACCESS_TOKEN=` to
+> `Sec-WebSocket-Protocol`, and the default stream moved from the router to the
+> api service. See [CHANGELOG.md](CHANGELOG.md).
+
 ## Error callbacks and outage detection
 
 The SDK exposes two error callbacks and an "all connections down" listener that

package/dist/cjs/constants.cjs

@@ -9,17 +9,17 @@ function _export(target, all) {
     });
 }
 _export(exports, {
+    get AUTH_SUBPROTOCOL () {
+        return AUTH_SUBPROTOCOL;
+    },
     get DEFAULT_METADATA_SERVICE_URL () {
         return DEFAULT_METADATA_SERVICE_URL;
     },
     get DEFAULT_PRICE_SERVICE_URL () {
         return DEFAULT_PRICE_SERVICE_URL;
     },
-    get DEFAULT_STREAM_SERVICE_0_URL () {
-        return DEFAULT_STREAM_SERVICE_0_URL;
-    },
-    get DEFAULT_STREAM_SERVICE_1_URL () {
-        return DEFAULT_STREAM_SERVICE_1_URL;
+    get DEFAULT_STREAM_SERVICE_URLS () {
+        return DEFAULT_STREAM_SERVICE_URLS;
     },
     get SOLANA_LAZER_PROGRAM_ID () {
         return SOLANA_LAZER_PROGRAM_ID;
@@ -32,5 +32,9 @@ const SOLANA_LAZER_PROGRAM_ID = "pytd2yyk641x7ak7mkaasSJVXh6YYZnC7wTmtgAyxPt";
 const SOLANA_LAZER_STORAGE_ID = "3rdJbqfnagQ4yx9HXJViD4zc4xpiSqmFsKpPuSCQVyQL";
 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";
+const DEFAULT_STREAM_SERVICE_URLS = [
+    "wss://pyth-0.dourolabs.app/v1/prices/stream",
+    "wss://pyth-1.dourolabs.app/v1/prices/stream",
+    "wss://pyth-2.dourolabs.app/v1/prices/stream"
+];
+const AUTH_SUBPROTOCOL = "pyth-lazer-auth";

package/dist/cjs/constants.d.ts

@@ -2,5 +2,15 @@ export declare const SOLANA_LAZER_PROGRAM_ID = "pytd2yyk641x7ak7mkaasSJVXh6YYZnC
 export declare const SOLANA_LAZER_STORAGE_ID = "3rdJbqfnagQ4yx9HXJViD4zc4xpiSqmFsKpPuSCQVyQL";
 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";
+/**
+ * Default stream endpoints, round-robined across the pool's connections when
+ * the caller does not supply their own `urls`. These are redundant instances
+ * of the Lazer api-service stream.
+ */
+export declare const DEFAULT_STREAM_SERVICE_URLS: string[];
+/**
+ * WebSocket subprotocol marker that carries the auth token during the handshake
+ * (used in every environment): clients send
+ * `Sec-WebSocket-Protocol: pyth-lazer-auth, <token>`.
+ */
+export declare const AUTH_SUBPROTOCOL = "pyth-lazer-auth";

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

@@ -11,7 +11,6 @@ Object.defineProperty(exports, "ResilientWebSocket", {
 const _isomorphicws = /*#__PURE__*/ _interop_require_default(require("isomorphic-ws"));
 const _tslog = require("ts-log");
 const _protocol = require("../protocol.cjs");
-const _envutil = require("../util/env-util.cjs");
 function _interop_require_default(obj) {
     return obj && obj.__esModule ? obj : {
         default: obj
@@ -22,7 +21,7 @@ const DEFAULT_MAX_RETRY_DELAY_MS = 1000; // 1 second'
 const DEFAULT_LOG_AFTER_RETRY_COUNT = 10;
 class ResilientWebSocket {
     endpoint;
-    wsOptions;
+    protocols;
     logger;
     heartbeatTimeoutDurationMs;
     maxRetryDelayMs;
@@ -48,7 +47,7 @@ class ResilientWebSocket {
     onTimeout;
     constructor(config){
         this.endpoint = config.endpoint;
-        this.wsOptions = config.wsOptions;
+        this.protocols = config.protocols;
         this.logger = config.logger ?? _tslog.dummyLogger;
         this.heartbeatTimeoutDurationMs = config.heartbeatTimeoutDurationMs ?? DEFAULT_HEARTBEAT_TIMEOUT_DURATION_MS;
         this.maxRetryDelayMs = config.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS;
@@ -97,10 +96,7 @@ class ResilientWebSocket {
         // 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 = new _isomorphicws.default(this.endpoint, this.protocols);
             this.wsClient.addEventListener("open", ()=>{
                 this.logger.info("WebSocket connection established");
                 this.wsFailedAttempts = 0;

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

@@ -1,10 +1,10 @@
-import type { ClientRequestArgs } from "node:http";
-import type { ClientOptions, ErrorEvent } from "isomorphic-ws";
+import type { ErrorEvent } from "isomorphic-ws";
 import WebSocket from "isomorphic-ws";
 import type { Logger } from "ts-log";
 export type ResilientWebSocketConfig = {
     endpoint: string;
-    wsOptions?: ClientOptions | ClientRequestArgs | undefined;
+    /** WebSocket subprotocols, used to carry the auth token. */
+    protocols?: string[] | undefined;
     logger?: Logger;
     heartbeatTimeoutDurationMs?: number;
     maxRetryDelayMs?: number;
@@ -25,7 +25,7 @@ export type ResilientWebSocketConfig = {
 type UnsafeWebSocket = Omit<WebSocket, "terminate"> & Partial<Pick<WebSocket, "terminate">>;
 export declare class ResilientWebSocket {
     private endpoint;
-    private wsOptions?;
+    private protocols?;
     private logger;
     private heartbeatTimeoutDurationMs;
     private maxRetryDelayMs;

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

@@ -52,7 +52,7 @@ 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, abortSignal, logger) {
+   */ static async create(config, token, abortSignal, logger, deps = {}) {
         // Helper to check if aborted and throw
         const throwIfAborted = ()=>{
             if (abortSignal?.aborted) {
@@ -61,11 +61,9 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
         };
         // Check before starting
         throwIfAborted();
-        const urls = config.urls ?? [
-            _constants.DEFAULT_STREAM_SERVICE_0_URL,
-            _constants.DEFAULT_STREAM_SERVICE_1_URL
-        ];
+        const urls = config.urls ?? _constants.DEFAULT_STREAM_SERVICE_URLS;
         const log = logger ?? _tslog.dummyLogger;
+        const createConnection = deps.createConnection ?? ((rwsConfig)=>new _resilientwebsocket.ResilientWebSocket(rwsConfig));
         const pool = new WebSocketPool(log);
         try {
             const numConnections = config.numConnections ?? DEFAULT_NUM_CONNECTIONS;
@@ -80,25 +78,24 @@ class WebSocketPool extends _index.IsomorphicEventEmitter {
             }
             for(let i = 0; i < numConnections; i++){
                 const baseUrl = urls[i % urls.length];
-                const isBrowser = (0, _index1.envIsBrowserOrWorker)();
-                const url = isBrowser ? (0, _index1.addAuthTokenToWebSocketUrl)(baseUrl, token) : baseUrl;
-                if (!url) {
+                if (!baseUrl) {
                     throw new Error(`URLs must not be null or empty`);
                 }
-                const wsOptions = {
-                    ...config.rwsConfig?.wsOptions,
-                    headers: isBrowser ? undefined : {
-                        Authorization: `Bearer ${token}`
-                    }
-                };
-                const rws = new _resilientwebsocket.ResilientWebSocket({
+                const rwsInit = {
                     ...config.rwsConfig,
-                    endpoint: url,
+                    // Pool-controlled fields are set last so they always win over
+                    // anything supplied via rwsConfig (in particular, auth can never be
+                    // overridden here).
+                    endpoint: baseUrl,
                     logger: log,
-                    wsOptions
-                });
+                    protocols: [
+                        _constants.AUTH_SUBPROTOCOL,
+                        token
+                    ]
+                };
+                const rws = createConnection(rwsInit);
                 const connectionIndex = i;
-                const connectionEndpoint = url;
+                const connectionEndpoint = baseUrl;
                 // If a websocket client unexpectedly disconnects, ResilientWebSocket will reestablish
                 // the connection and call the onReconnect callback.
                 rws.onReconnect = ()=>{

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

@@ -4,7 +4,21 @@ 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";
+/** The subset of `ResilientWebSocket` the pool depends on. */
+export type PooledConnection = {
+    wsUserClosed: boolean;
+    onReconnect: () => void;
+    onTimeout: () => void;
+    onError: (error: ErrorEvent) => void;
+    onMessage: (data: WebSocket.Data) => void;
+    send(data: string | Buffer): void;
+    startWebSocket(): void;
+    isConnected(): boolean;
+    isReconnecting(): boolean;
+    closeWebSocket(): void;
+};
+/** Builds a pooled connection; overridable to inject a fake in tests. */
+export type ConnectionFactory = (config: ResilientWebSocketConfig) => PooledConnection;
 type WebSocketOnMessageCallback = (data: WebSocket.Data) => Promise<void>;
 export type WebSocketPoolConfig = {
     /**
@@ -32,9 +46,10 @@ export type WebSocketPoolConfig = {
      */
     onWebSocketPoolError?: (error: Error) => void;
     /**
-     * Additional websocket configuration
+     * Optional tuning for the underlying resilient WebSocket connections
+     * (heartbeat timeout, retry backoff, and retry-log cadence).
      */
-    rwsConfig?: Omit<ResilientWebSocketConfig, "logger" | "endpoint">;
+    rwsConfig?: Omit<ResilientWebSocketConfig, "endpoint" | "logger" | "protocols">;
     /**
      * Pyth URLs to use when creating a connection
      */
@@ -46,7 +61,7 @@ export type WebSocketPoolEvents = {
 };
 export declare class WebSocketPool extends IsomorphicEventEmitter<WebSocketPoolEvents> {
     private readonly logger;
-    rwsPool: ResilientWebSocket[];
+    rwsPool: PooledConnection[];
     private cache;
     private subscriptions;
     private messageListeners;
@@ -66,7 +81,9 @@ 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, abortSignal?: AbortSignal | null | undefined, logger?: Logger): Promise<WebSocketPool>;
+    static create(config: WebSocketPoolConfig, token: string, abortSignal?: AbortSignal | null | undefined, logger?: Logger, deps?: {
+        createConnection?: ConnectionFactory;
+    }): Promise<WebSocketPool>;
     private emitPoolError;
     /**
      * Checks for error responses in JSON messages and throws appropriate errors

package/dist/cjs/util/index.cjs

@@ -4,7 +4,6 @@ Object.defineProperty(exports, "__esModule", {
 });
 _export_star(require("./buffer-util.cjs"), exports);
 _export_star(require("./env-util.cjs"), exports);
-_export_star(require("./url-util.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/util/index.d.ts

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

package/dist/esm/constants.d.ts

@@ -2,5 +2,15 @@ export declare const SOLANA_LAZER_PROGRAM_ID = "pytd2yyk641x7ak7mkaasSJVXh6YYZnC
 export declare const SOLANA_LAZER_STORAGE_ID = "3rdJbqfnagQ4yx9HXJViD4zc4xpiSqmFsKpPuSCQVyQL";
 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";
+/**
+ * Default stream endpoints, round-robined across the pool's connections when
+ * the caller does not supply their own `urls`. These are redundant instances
+ * of the Lazer api-service stream.
+ */
+export declare const DEFAULT_STREAM_SERVICE_URLS: string[];
+/**
+ * WebSocket subprotocol marker that carries the auth token during the handshake
+ * (used in every environment): clients send
+ * `Sec-WebSocket-Protocol: pyth-lazer-auth, <token>`.
+ */
+export declare const AUTH_SUBPROTOCOL = "pyth-lazer-auth";

package/dist/esm/constants.mjs

@@ -2,5 +2,17 @@ export const SOLANA_LAZER_PROGRAM_ID = "pytd2yyk641x7ak7mkaasSJVXh6YYZnC7wTmtgAy
 export const SOLANA_LAZER_STORAGE_ID = "3rdJbqfnagQ4yx9HXJViD4zc4xpiSqmFsKpPuSCQVyQL";
 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";
+/**
+ * Default stream endpoints, round-robined across the pool's connections when
+ * the caller does not supply their own `urls`. These are redundant instances
+ * of the Lazer api-service stream.
+ */ export const DEFAULT_STREAM_SERVICE_URLS = [
+    "wss://pyth-0.dourolabs.app/v1/prices/stream",
+    "wss://pyth-1.dourolabs.app/v1/prices/stream",
+    "wss://pyth-2.dourolabs.app/v1/prices/stream"
+];
+/**
+ * WebSocket subprotocol marker that carries the auth token during the handshake
+ * (used in every environment): clients send
+ * `Sec-WebSocket-Protocol: pyth-lazer-auth, <token>`.
+ */ export const AUTH_SUBPROTOCOL = "pyth-lazer-auth";

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

@@ -1,10 +1,10 @@
-import type { ClientRequestArgs } from "node:http";
-import type { ClientOptions, ErrorEvent } from "isomorphic-ws";
+import type { ErrorEvent } from "isomorphic-ws";
 import WebSocket from "isomorphic-ws";
 import type { Logger } from "ts-log";
 export type ResilientWebSocketConfig = {
     endpoint: string;
-    wsOptions?: ClientOptions | ClientRequestArgs | undefined;
+    /** WebSocket subprotocols, used to carry the auth token. */
+    protocols?: string[] | undefined;
     logger?: Logger;
     heartbeatTimeoutDurationMs?: number;
     maxRetryDelayMs?: number;
@@ -25,7 +25,7 @@ export type ResilientWebSocketConfig = {
 type UnsafeWebSocket = Omit<WebSocket, "terminate"> & Partial<Pick<WebSocket, "terminate">>;
 export declare class ResilientWebSocket {
     private endpoint;
-    private wsOptions?;
+    private protocols?;
     private logger;
     private heartbeatTimeoutDurationMs;
     private maxRetryDelayMs;

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

@@ -1,13 +1,12 @@
 import WebSocket from "isomorphic-ws";
 import { dummyLogger } from "ts-log";
 import { CustomSocketClosureCodes } from "../protocol.mjs";
-import { envIsBrowserOrWorker } from "../util/env-util.mjs";
 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;
 export class ResilientWebSocket {
     endpoint;
-    wsOptions;
+    protocols;
     logger;
     heartbeatTimeoutDurationMs;
     maxRetryDelayMs;
@@ -33,7 +32,7 @@ export class ResilientWebSocket {
     onTimeout;
     constructor(config){
         this.endpoint = config.endpoint;
-        this.wsOptions = config.wsOptions;
+        this.protocols = config.protocols;
         this.logger = config.logger ?? dummyLogger;
         this.heartbeatTimeoutDurationMs = config.heartbeatTimeoutDurationMs ?? DEFAULT_HEARTBEAT_TIMEOUT_DURATION_MS;
         this.maxRetryDelayMs = config.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS;
@@ -82,10 +81,7 @@ export class ResilientWebSocket {
         // 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 = new WebSocket(this.endpoint, this.protocols);
             this.wsClient.addEventListener("open", ()=>{
                 this.logger.info("WebSocket connection established");
                 this.wsFailedAttempts = 0;

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

@@ -4,7 +4,21 @@ 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";
+/** The subset of `ResilientWebSocket` the pool depends on. */
+export type PooledConnection = {
+    wsUserClosed: boolean;
+    onReconnect: () => void;
+    onTimeout: () => void;
+    onError: (error: ErrorEvent) => void;
+    onMessage: (data: WebSocket.Data) => void;
+    send(data: string | Buffer): void;
+    startWebSocket(): void;
+    isConnected(): boolean;
+    isReconnecting(): boolean;
+    closeWebSocket(): void;
+};
+/** Builds a pooled connection; overridable to inject a fake in tests. */
+export type ConnectionFactory = (config: ResilientWebSocketConfig) => PooledConnection;
 type WebSocketOnMessageCallback = (data: WebSocket.Data) => Promise<void>;
 export type WebSocketPoolConfig = {
     /**
@@ -32,9 +46,10 @@ export type WebSocketPoolConfig = {
      */
     onWebSocketPoolError?: (error: Error) => void;
     /**
-     * Additional websocket configuration
+     * Optional tuning for the underlying resilient WebSocket connections
+     * (heartbeat timeout, retry backoff, and retry-log cadence).
      */
-    rwsConfig?: Omit<ResilientWebSocketConfig, "logger" | "endpoint">;
+    rwsConfig?: Omit<ResilientWebSocketConfig, "endpoint" | "logger" | "protocols">;
     /**
      * Pyth URLs to use when creating a connection
      */
@@ -46,7 +61,7 @@ export type WebSocketPoolEvents = {
 };
 export declare class WebSocketPool extends IsomorphicEventEmitter<WebSocketPoolEvents> {
     private readonly logger;
-    rwsPool: ResilientWebSocket[];
+    rwsPool: PooledConnection[];
     private cache;
     private subscriptions;
     private messageListeners;
@@ -66,7 +81,9 @@ 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, abortSignal?: AbortSignal | null | undefined, logger?: Logger): Promise<WebSocketPool>;
+    static create(config: WebSocketPoolConfig, token: string, abortSignal?: AbortSignal | null | undefined, logger?: Logger, deps?: {
+        createConnection?: ConnectionFactory;
+    }): Promise<WebSocketPool>;
     private emitPoolError;
     /**
      * Checks for error responses in JSON messages and throws appropriate errors

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

@@ -1,8 +1,8 @@
 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 { AUTH_SUBPROTOCOL, DEFAULT_STREAM_SERVICE_URLS } from "../constants.mjs";
 import { IsomorphicEventEmitter } from "../emitter/index.mjs";
-import { addAuthTokenToWebSocketUrl, bufferFromWebsocketData, envIsBrowserOrWorker } from "../util/index.mjs";
+import { bufferFromWebsocketData } from "../util/index.mjs";
 import { ResilientWebSocket } from "./resilient-websocket.mjs";
 const DEFAULT_NUM_CONNECTIONS = 4;
 export class WebSocketPool extends IsomorphicEventEmitter {
@@ -42,7 +42,7 @@ export class WebSocketPool extends 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, abortSignal, logger) {
+   */ static async create(config, token, abortSignal, logger, deps = {}) {
         // Helper to check if aborted and throw
         const throwIfAborted = ()=>{
             if (abortSignal?.aborted) {
@@ -51,11 +51,9 @@ export class WebSocketPool extends IsomorphicEventEmitter {
         };
         // Check before starting
         throwIfAborted();
-        const urls = config.urls ?? [
-            DEFAULT_STREAM_SERVICE_0_URL,
-            DEFAULT_STREAM_SERVICE_1_URL
-        ];
+        const urls = config.urls ?? DEFAULT_STREAM_SERVICE_URLS;
         const log = logger ?? dummyLogger;
+        const createConnection = deps.createConnection ?? ((rwsConfig)=>new ResilientWebSocket(rwsConfig));
         const pool = new WebSocketPool(log);
         try {
             const numConnections = config.numConnections ?? DEFAULT_NUM_CONNECTIONS;
@@ -70,25 +68,24 @@ export class WebSocketPool extends IsomorphicEventEmitter {
             }
             for(let i = 0; i < numConnections; i++){
                 const baseUrl = urls[i % urls.length];
-                const isBrowser = envIsBrowserOrWorker();
-                const url = isBrowser ? addAuthTokenToWebSocketUrl(baseUrl, token) : baseUrl;
-                if (!url) {
+                if (!baseUrl) {
                     throw new Error(`URLs must not be null or empty`);
                 }
-                const wsOptions = {
-                    ...config.rwsConfig?.wsOptions,
-                    headers: isBrowser ? undefined : {
-                        Authorization: `Bearer ${token}`
-                    }
-                };
-                const rws = new ResilientWebSocket({
+                const rwsInit = {
                     ...config.rwsConfig,
-                    endpoint: url,
+                    // Pool-controlled fields are set last so they always win over
+                    // anything supplied via rwsConfig (in particular, auth can never be
+                    // overridden here).
+                    endpoint: baseUrl,
                     logger: log,
-                    wsOptions
-                });
+                    protocols: [
+                        AUTH_SUBPROTOCOL,
+                        token
+                    ]
+                };
+                const rws = createConnection(rwsInit);
                 const connectionIndex = i;
-                const connectionEndpoint = url;
+                const connectionEndpoint = baseUrl;
                 // If a websocket client unexpectedly disconnects, ResilientWebSocket will reestablish
                 // the connection and call the onReconnect callback.
                 rws.onReconnect = ()=>{

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

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

package/dist/esm/util/index.mjs

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

package/package.json

@@ -120,16 +120,6 @@
         "default": "./dist/cjs/util/env-util.cjs",
         "types": "./dist/cjs/util/env-util.d.ts"
       }
-    },
-    "./util/url-util": {
-      "import": {
-        "default": "./dist/esm/util/url-util.mjs",
-        "types": "./dist/esm/util/url-util.d.ts"
-      },
-      "require": {
-        "default": "./dist/cjs/util/url-util.cjs",
-        "types": "./dist/cjs/util/url-util.d.ts"
-      }
     }
   },
   "files": [
@@ -164,5 +154,5 @@
   },
   "type": "module",
   "types": "./dist/cjs/index.d.ts",
-  "version": "6.2.4"
+  "version": "7.0.0"
 }

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

@@ -1,17 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-Object.defineProperty(exports, "addAuthTokenToWebSocketUrl", {
-    enumerable: true,
-    get: function() {
-        return addAuthTokenToWebSocketUrl;
-    }
-});
-const ACCESS_TOKEN_QUERY_PARAM_KEY = "ACCESS_TOKEN";
-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/cjs/util/url-util.d.ts

@@ -1,8 +0,0 @@
-/**
- * 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.d.ts

@@ -1,8 +0,0 @@
-/**
- * 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.mjs

@@ -1,13 +0,0 @@
-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();
-}