@katanaperps/katana-perps-sdk 0.0.0-placeholder

package/dist/client/webSocket/index.js

@@ -0,0 +1,1048 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketClient = exports.WEBSOCKET_PING_TIMEOUT_MS = exports.transformWebsocketShortResponseMessage = void 0;
+const tslib_1 = require("tslib");
+const isomorphic_ws_1 = tslib_1.__importDefault(require("isomorphic-ws"));
+const uuid_1 = require("uuid");
+const _utils_1 = require("#utils");
+const authenticated_1 = require("#client/rest/authenticated");
+const guards = tslib_1.__importStar(require("#client/webSocket/guards"));
+const transform_1 = require("#client/webSocket/transform");
+Object.defineProperty(exports, "transformWebsocketShortResponseMessage", { enumerable: true, get: function () { return transform_1.transformWebsocketShortResponseMessage; } });
+const request_1 = require("#types/enums/request");
+tslib_1.__exportStar(require("#client/webSocket/guards"), exports);
+let autoId = 1;
+/**
+ * This is the doc comment for file1.ts
+ *
+ * Specify this is a module comment and rename it to my-module:
+ * @module my-module
+ */
+/**
+ * @internal
+ *
+ * How often to send `ping` messages to the server (in milliseconds).
+ */
+exports.WEBSOCKET_PING_TIMEOUT_MS = 30_000;
+/**
+ * ### WebSocket API client
+ *
+ * You must provide constructor options that match either:
+ *
+ * - If you only need {@link KatanaPerpsSubscribeTypePublic public subscriptions}, all options are optional.
+ * - If you want to make {@link KatanaPerpsSubscribeTypeAuthenticated authenticated subscriptions}:
+ *   - You must provide a valid {@link WebSocketClientOptions.auth auth}
+ *     property in the {@link WebSocketClientOptions constructor options} which includes:
+ *     - {@link katanaperps.WebSocketClientAuthOptions.apiKey apiKey}
+ *     - {@link katanaperps.WebSocketClientAuthOptions.apiSecret apiSecret}
+ *     - {@link katanaperps.WebSocketClientAuthOptions.wallet wallet}
+ *
+ * @example
+ * ```typescript
+ *   import {
+ *    WebSocketClient,
+ *    SubscriptionNameAuthenticated,
+ *    SubscriptionNamePublic
+ *   } from '@katanaperps/katana-perps-sdk';
+ *
+ *   const webSocketClientPublicOnly = new WebSocketClient();
+ *
+ *   // or ... to enable both public and authenticated subscriptions:
+ *
+ *   const client = new WebSocketClient({
+ *    // Edit the values before for your environment
+ *    auth: {
+ *      apiKey: '1f7c4f52-4af7-4e1b-aa94-94fac8d931aa',
+ *      apiSecret: 'axuh3ywgg854aq7m73oy6gnnpj5ar9a67szuw5lclbz77zqu0j',
+ *      wallet: '0x...',
+ *    }
+ *    // sandbox: true,
+ *    // logger: console.log
+ *  });
+ *
+ *  client.onConnect(() => {
+ *    // [see onConnect docs for full example and information]
+ *  })
+ *
+ *  client.onDisconnect((code, reason) => {
+ *    // [see onDisconnect docs for full example and information]
+ *  })
+ *
+ *  client.onError(errorEvent => {
+ *    // [see onError docs for full example and information]
+ *  })
+ *
+ *  client.onMessage(message => {
+ *   console.log('Receiving Message: ', message)
+ *   switch(message.type) {
+ *     case MessageEventType.subscriptions:
+ *       return handleSubscriptions(message.subscriptions);
+ *     case MessageEventType.error:
+ *      return handleAPIError(message.data);
+ *     case MessageEventType.candles:
+ *      return handleCandles(message.data);
+ *     default:
+ *        break;
+ *  })
+ *
+ *  await client.connect();
+ *
+ * // subscribe as needed!
+ *
+ *  await client
+ *    .subscribePublic([
+ *      {
+ *        name: SubscriptionNamePublic.tickers,
+ *        markets: ['ETH-USD']
+ *      },
+ *   ])
+ *   .subscribeAuthenticated([
+ *      { name: SubscriptionNameAuthenticated.positions },
+ *      { name: SubscriptionNameAuthenticated.orders },
+ *   ]);
+ * ```
+ *
+ * <br />
+ *
+ * ---
+ *
+ * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html)
+ *
+ * @category API Clients
+ * @category KatanaPerps - Get Candles
+ * @category KatanaPerps - Get Deposits
+ * @category KatanaPerps - Get Funding Payments
+ * @category KatanaPerps - Get Liquidations
+ * @category KatanaPerps - Get OrderBook
+ * @category KatanaPerps - Get Orders
+ * @category KatanaPerps - Get Positions
+ * @category KatanaPerps - Get Tickers
+ * @category KatanaPerps - Get Trades
+ * @category KatanaPerps - Get Withdrawals
+ */
+class WebSocketClient {
+    /**
+     * @internal
+     * @private
+     */
+    #state = {
+        /**
+         * Set to true when the reconnect logic should not be run.
+         * @private
+         */
+        doNotReconnect: false,
+        isReconnecting: false,
+        /**
+         * Used to track the number of reconnect attempts for exponential backoff
+         * @private
+         */
+        reconnectAttempt: 0,
+        /**
+         * When the ping timeout is scheduled, it saves its id to this property.  Since
+         * the type from Node & dom are not compatible, using it may require casting
+         *
+         * @example
+         * clearTimeout(this.#state.pingTimeoutId as number);
+         *
+         * @private
+         */
+        pingTimeoutId: undefined,
+        reconnectTimeoutId: undefined,
+        connectHandlers: new Set(),
+        disconnectHandlers: new Set(),
+        errorHandlers: new Set(),
+        messageHandlers: new Set(),
+    };
+    #websocketCustomAuthTokenFetcher = null;
+    #websocketAutoAuthTokenFetcher = null;
+    /**
+     * If `true`, this client will throw an error if it attempts to subscribe to
+     * an {@link KatanaPerpsSubscribeTypeAuthenticated authenticated subscription}.
+     *
+     * - This is determined by whether or not the {@link katanaperps.WebSocketClientOptions.auth auth}
+     *   property was provided during construction.
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html#isPublicOnly)
+     *
+     * @category Accessors
+     */
+    get isPublicOnly() {
+        return (!this.#websocketCustomAuthTokenFetcher &&
+            !this.#websocketAutoAuthTokenFetcher);
+    }
+    #options;
+    #terminated = false;
+    /**
+     * When a client is terminated, it will cease to function and a new WebSocketClient must be created
+     * to start a new connection.
+     */
+    get terminated() {
+        return this.#terminated;
+    }
+    #ws = null;
+    /**
+     * You can access the current {@link WebSocket}
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html#ws)
+     *
+     * @category Accessors
+     */
+    get ws() {
+        return this.#ws;
+    }
+    /**
+     * A boolean indicating whether the WebSocket client is currently connected to the Katana Perps WebSocket API.
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html#isConnected)
+     *
+     * @category Accessors
+     */
+    get isConnected() {
+        if (!this.ws) {
+            return false;
+        }
+        return this.ws.readyState === this.ws.OPEN;
+    }
+    /**
+     * ### WebSocket API client
+     *
+     * You must provide constructor options that match either:
+     *
+     * - If you only need {@link KatanaPerpsSubscribeTypePublic public subscriptions}, all options are optional.
+     * - If you want to make {@link KatanaPerpsSubscribeTypeAuthenticated authenticated subscriptions}:
+     *   - You must provide a valid {@link WebSocketClientOptions.auth auth}
+     *     property in the {@link WebSocketClientOptions constructor options} which includes:
+     *     - {@link katanaperps.WebSocketClientAuthOptions.apiKey apiKey}
+     *     - {@link katanaperps.WebSocketClientAuthOptions.apiSecret apiSecret}
+     *     - {@link katanaperps.WebSocketClientAuthOptions.wallet wallet}
+     *
+     * @example
+     * ```typescript
+     *   import {
+     *    WebSocketClient,
+     *    SubscriptionNameAuthenticated,
+     *    SubscriptionNamePublic
+     *   } from '@katanaperps/katana-perps-sdk';
+     *
+     *   const webSocketClientPublicOnly = new WebSocketClient();
+     *
+     *   // or ... to enable both public and authenticated subscriptions:
+     *
+     *   const client = new WebSocketClient({
+     *    // Edit the values before for your environment
+     *    auth: {
+     *      apiKey: '1f7c4f52-4af7-4e1b-aa94-94fac8d931aa',
+     *      apiSecret: 'axuh3ywgg854aq7m73oy6gnnpj5ar9a67szuw5lclbz77zqu0j',
+     *      wallet: '0x...',
+     *    }
+     *    // sandbox: true,
+     *    // logger: console.log
+     *  });
+     *
+     *  client.onConnect(() => {
+     *    // [see onConnect docs for full example and information]
+     *  })
+     *
+     *  client.onDisconnect((code, reason) => {
+     *    // [see onDisconnect docs for full example and information]
+     *  })
+     *
+     *  client.onError(errorEvent => {
+     *    // [see onError docs for full example and information]
+     *  })
+     *
+     *  client.onMessage(message => {
+     *   console.log('Receiving Message: ', message)
+     *   switch(message.type) {
+     *     case MessageEventType.subscriptions:
+     *       return handleSubscriptions(message.subscriptions);
+     *     case MessageEventType.error:
+     *      return handleAPIError(message.data);
+     *     case MessageEventType.candles:
+     *      return handleCandles(message.data);
+     *     default:
+     *        break;
+     *  })
+     *
+     *  await client.connect();
+     *
+     * // subscribe as needed!
+     *
+     *  await client
+     *    .subscribePublic([
+     *      {
+     *        name: SubscriptionNamePublic.tickers,
+     *        markets: ['ETH-USD']
+     *      },
+     *   ])
+     *   .subscribeAuthenticated([
+     *      { name: SubscriptionNameAuthenticated.positions },
+     *      { name: SubscriptionNameAuthenticated.orders },
+     *   ]);
+     * ```
+     *
+     * <br />
+     *
+     * ---
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html)
+     */
+    constructor(options = {}) {
+        const sandbox = options.sandbox ?? false;
+        const baseWebSocketURL = (0, _utils_1.deriveBaseURL)({
+            sandbox,
+            api: 'websocket',
+            baseRestApiURL: options.baseRestApiURL,
+            baseWebSocketURL: options.baseWebSocketURL,
+        });
+        const baseRestApiURL = (0, _utils_1.deriveBaseURL)({
+            sandbox,
+            api: 'rest',
+            baseWebSocketURL: options.baseWebSocketURL,
+            baseRestApiURL: options.baseRestApiURL,
+        });
+        const initializedOptions = {
+            sandbox,
+            baseWebSocketURL,
+            baseRestApiURL,
+            shouldReconnectAutomatically: options.shouldReconnectAutomatically ?? true,
+            // eslint-disable-next-line no-plusplus
+            clientId: options.clientId ?? `${autoId++}`,
+        };
+        this.#options = {
+            ...options,
+            ...initializedOptions,
+        };
+        // Options must exactly match one of the subsets of WebSocketClientOptionsBase
+        if (this.#options.websocketAuthTokenFetch) {
+            // WebSocketClientOptionsWithFetch
+            this.#websocketCustomAuthTokenFetcher =
+                this.#options.websocketAuthTokenFetch.bind(this);
+            this.#websocketAutoAuthTokenFetcher = null;
+        }
+        else if (guards.isWebSocketOptionsAutoFetch(this.#options)) {
+            // WebSocketClientOptionsWithAPIKey
+            this.#websocketCustomAuthTokenFetcher = null;
+            this.#websocketAutoAuthTokenFetcher = createDefaultWebSocketTokenFetcher(this.#options);
+        }
+        else if (guards.isWebSocketOptionsPublicOnly(this.#options)) {
+            // WebSocketClientOptionsPublicOnly
+            this.#websocketCustomAuthTokenFetcher = null;
+            this.#websocketAutoAuthTokenFetcher = null;
+        }
+        else {
+            throw new Error('Invalid configuration, must specify options for either public only, auto wsToken fetch, or custom wsToken fetch');
+        }
+    }
+    throwIfTerminated() {
+        if (this.terminated) {
+            throw new Error(`WebSocketClient ${this.#options.clientId} is terminated and cannot be used`);
+        }
+    }
+    /**
+     * Connect to the [Katana Perps WebSocket API](https://api-docs-v1-perps.katana.network/#websocket-api-interaction)
+     *
+     * ---
+     * @param awaitConnected
+     *  - If `true`, the promise will not resolve until the connection is established
+     * @returns
+     *  - `this` to allow chaining with other methods or requests.
+     * ---
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html#connect)
+     *
+     * @category Connection Management
+     */
+    async connect(awaitConnected = true) {
+        this.throwIfTerminated();
+        if (this.isConnected) {
+            return this;
+        }
+        this.log('info', `Connecting to WebSocket, awaiting connection? ${awaitConnected}`);
+        this.#state.doNotReconnect = false;
+        // connect and await connection to succeed
+        const connectionProm = this.createWebSocketIfNeeded(true).then(() => {
+            this.#state.connectHandlers.forEach((listener) => listener());
+        });
+        if (awaitConnected) {
+            await connectionProm;
+        }
+        return this;
+    }
+    /**
+     * Disconnect from the WebSocket if connected.
+     *
+     * - If `terminate` is `true`, the WebSocket will be disconnected immediately and this client will
+     *   cease to work or connect.
+     *   - All listeners will be cleared and all methods will throw errors once terminated.
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html#disconnect)
+     *
+     * @category Connection Management
+     */
+    disconnect(terminate) {
+        if (!terminate) {
+            this.throwIfTerminated();
+        }
+        else if (this.terminated) {
+            return this;
+        }
+        this.#state.doNotReconnect = true;
+        this.log('info', 'Disconnecting from WebSocket');
+        this.stopPinging();
+        this.cancelReconnect();
+        if (!this.#ws) {
+            if (terminate) {
+                this.#terminated = true;
+            }
+            return this; // Already disconnected
+        }
+        this.#state.doNotReconnect = true;
+        if (terminate) {
+            this.#options.shouldReconnectAutomatically = false;
+            this.#terminated = true;
+            // handlers are not called when terminating
+            this.#state.connectHandlers.clear();
+            this.#state.disconnectHandlers.clear();
+            this.#state.errorHandlers.clear();
+            this.#state.disconnectHandlers.clear();
+            this.#state.messageHandlers.clear();
+            if (typeof this.#ws.terminate === 'function') {
+                this.#ws.terminate();
+            }
+            else {
+                this.#ws.close();
+            }
+        }
+        else {
+            this.#ws.close();
+        }
+        this.#ws = null;
+        return this;
+    }
+    /**
+     * Subscribe a handler to all WebSocket disconnect events.
+     *
+     * - Calling multiple times will add multiple subscribers to the given event
+     *
+     * ---
+     * @param handler
+     *  - A handler function matching {@link WebSocketHandlerConnect} that will receive events.
+     * @param replaceAll
+     *  - Replaces all current handlers with the provided handler.
+     * @returns
+     *  - `this` to allow chaining with other methods or requests.
+     * ---
+     *
+     * @example
+     * ```typescript
+     *  websocketClient.onConnect(() => {
+     *   console.warn('WebSocket Connection Connects')
+     *  })
+     * ```
+     *
+     * <br />
+     *
+     * ---
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html#onConnect)
+     *
+     * @category Event Handling
+     */
+    onConnect(handler, replaceAll) {
+        this.throwIfTerminated();
+        if (replaceAll) {
+            this.#state.connectHandlers.clear();
+        }
+        this.#state.connectHandlers.add(handler);
+        return this;
+    }
+    /**
+     * Subscribe a handler to all WebSocket disconnect events.
+     *
+     * ---
+     * @param handler
+     *  - A handler function matching {@link WebSocketHandlerDisconnect} that will receive events.
+     * @param replaceAll
+     *  - Replaces all current handlers with the provided handler.
+     * @returns
+     *  - `this` to allow chaining with other methods or requests.
+     * ---
+     *
+     * @example
+     * ```typescript
+     *  websocketClient.onDisconnect((code, reason) => {
+     *   console.warn('WebSocket Connection Disconnects: ', code, reason)
+     *  })
+     * ```
+     *
+     * <br />
+     *
+     * ---
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html#onDisconnect)
+     *
+     * @category Event Handling
+     */
+    onDisconnect(handler, replaceAll) {
+        this.throwIfTerminated();
+        if (replaceAll) {
+            this.#state.disconnectHandlers.clear();
+        }
+        this.#state.disconnectHandlers.add(handler);
+        return this;
+    }
+    /**
+     * Subscribe a handler to all WebSocket connection errors that may occur during
+     * your requests.
+     *
+     * - **Note:** These errors will be coming from the `ws` library itself and provide
+     *   its {@link ErrorEvent} errors.
+     * - Errors coming from the Katana Perps WebSocket client will be present as a {@link katanaperps.KatanaPerpsErrorEvent KatanaPerpsErrorEvent}
+     *   message to the {@link onMessage} handler.
+     *
+     * ---
+     * @param handler
+     *  - A handler function matching {@link WebSocketHandlerError} that will receive events.
+     * @param replaceAll
+     *  - Replaces all current handlers with the provided handler.
+     * @returns
+     *  - `this` to allow chaining with other methods or requests.
+     * ---
+     *
+     * @example
+     * ```typescript
+     *  websocketClient.onError(errorEvent => {
+     *   console.error('Connection Error on WebSocket: ', errorEvent.error)
+     *  })
+     * ```
+     *
+     * <br />
+     *
+     * ---
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html#onError)
+     *
+     * @category Event Handling
+     */
+    onError(handler, replaceAll) {
+        this.throwIfTerminated();
+        if (replaceAll) {
+            this.#state.errorHandlers.clear();
+        }
+        this.#state.errorHandlers.add(handler);
+        return this;
+    }
+    /**
+     * Subscribe a handler to all subscription responses.
+     *
+     * - Your handler will receive updates when available matching the {@link KatanaPerpsMessageEvent}
+     *   interface.
+     * - Use the {@link katanaperps.MessageEventType MessageEventType} enum to get an enum
+     *   defining all possible `type` values that can be received on the WebSocket message (see example).
+     *
+     * ---
+     * @param handler
+     *  - A handler function matching {@link WebSocketHandlerMessage} that will receive events.
+     * @param replaceAll
+     *  - Replaces all current handlers with the provided handler.
+     * @returns
+     *  - `this` to allow chaining with other methods or requests.
+     * ---
+     *
+     * @example
+     * ```typescript
+     *  import { MessageEventType } from '@katanaperps/katana-perps-sdk';
+     *
+     *  // ... client setup
+     *
+     *  websocketClient.onMessage(message => {
+     *   console.log('Receiving Message: ', message)
+     *   switch(message.type) {
+     *     case MessageEventType.subscriptions:
+     *       return handleSubscriptions(message.subscriptions);
+     *     case MessageEventType.error:
+     *      return handleAPIError(message.data);
+     *     case MessageEventType.candles:
+     *      return handleCandles(message.data);
+     *     default:
+     *        break;
+     *   }
+     *  })
+     * ```
+     *
+     * <br />
+     *
+     * ---
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html#onMessage)
+     * @see enum     {@link katanaperps.MessageEventType MessageEventType}
+     * @see type     {@link KatanaPerpsMessageEvent}
+     *
+     * @category Event Handling
+     */
+    onMessage(handler, replaceAll) {
+        this.throwIfTerminated();
+        if (replaceAll) {
+            this.#state.messageHandlers.clear();
+        }
+        this.#state.messageHandlers.add(handler);
+        return this;
+    }
+    /**
+     * Creates new {@link KatanaPerpsSubscribeTypeAuthenticated authenticated subscriptions} based on the provided parameters.
+     *
+     * - Use the {@link katanaperps.SubscriptionNameAuthenticated SubscriptionNameAuthenticated} enum for IDE
+     *   inline documentation and auto completion (see example)
+     *
+     * ---
+     *
+     * **Subscription Update Events:**
+     *
+     * - Receives a {@link katanaperps.KatanaPerpsSubscriptionsListEvent KatanaPerpsSubscriptionsListEvent} WebSocket response via
+     *   the {@link katanaperps.WebSocketClient.onMessage WebSocketClient.onMessage} handler listing all active
+     *   subscriptions.
+     * - Begins receiving {@link katanaperps.KatanaPerpsSubscriptionEvent KatanaPerpsSubscriptionEvent}'s for all subscribed
+     *   subscriptions via the {@link katanaperps.WebSocketClient.onMessage WebSocketClient.onMessage} handler.
+     *
+     * ---
+     * @param subscriptions
+     *  - An array of {@link KatanaPerpsSubscribeTypeAuthenticated} subscription objects.
+     * @param cid
+     *  - Optionally provide a `cid` property which will be returned in the response
+     *    so that you can correlate the response to the request.
+     * @returns
+     *  - `this` to allow chaining with other methods or requests.
+     * ---
+     *
+     * @throws
+     * >  This method will **throw an error** if you did not provide the {@link katanaperps.WebSocketClientOptionsWithAPIKey.auth auth} option
+     *    to the constructor in order to handle authenticated subscriptions.
+     *
+     * ---
+     *
+     * @example
+     * ```typescript
+     *  import {
+     *    WebSocketClient,
+     *    SubscriptionNameAuthenticated,
+     *  } from '@katanaperps/katana-perps-sdk';
+     *
+     *  const client = new WebSocketClient({
+     *    auth: {
+     *      apiKey: '...',
+     *      apiSecret: '...',
+     *      wallet: '0x...'
+     *    }
+     *  })
+     *
+     *  client.onMessage(message => {
+     *    console.log('Received WebSocket Message: ', message)
+     *  })
+     *
+     *  await client.subscribeAuthenticated([
+     *    { name: SubscriptionNameAuthenticated.positions },
+     *    { name: SubscriptionNameAuthenticated.orders },
+     *  ])
+     * ```
+     *
+     * <br />
+     *
+     * ---
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html#subscribeAuthenticated)
+     * @see related  {@link subscribePublic client.subscribePublic}
+     *
+     * @category Subscription Management
+     */
+    subscribeAuthenticated(
+    /**
+     * An array of {@link KatanaPerpsSubscribeTypeAuthenticated} subscription
+     * objects.
+     */
+    subscriptions, 
+    /**
+     * Optionally provide a `cid` property which will be returned in the response
+     * so that you can correlate the response to the request.
+     */
+    cid) {
+        this.throwIfTerminated();
+        if (this.isPublicOnly) {
+            throw new Error('[subscribeAuthenticated] Cannot subscribe to authenticated subscriptions ' +
+                'without providing the apiKey, apiSecret, and wallet options during client construction');
+        }
+        this.subscribe(subscriptions, undefined, cid);
+        return this;
+    }
+    /**
+     * This method allows subscribing to Katana Perps's {@link KatanaPerpsSubscribeTypePublic public subscriptions}.
+     *
+     * - Use the {@link katanaperps.SubscriptionNamePublic SubscriptionNamePublic} enum for IDE
+     *   inline documentation and auto completion (see example)
+     *
+     * ---
+     *
+     * **Subscription Update Events:**
+     *
+     * - Receives a {@link katanaperps.KatanaPerpsSubscriptionsListEvent KatanaPerpsSubscriptionsListEvent} WebSocket response via
+     *   the {@link katanaperps.WebSocketClient.onMessage WebSocketClient.onMessage} handler listing all active
+     *   subscriptions.
+     * - Begins receiving {@link katanaperps.KatanaPerpsSubscriptionEvent KatanaPerpsSubscriptionEvent}'s for all subscribed
+     *   subscriptions via the {@link katanaperps.WebSocketClient.onMessage WebSocketClient.onMessage} handler.
+     *
+     * ---
+     * @param subscriptions
+     *  - An array of {@link KatanaPerpsSubscribeTypePublic} subscription objects.
+     * @param markets
+     *  - Optionally provide top-level markets.
+     *    - Any {@link subscriptions} that **require but do not define** their own `markets`
+     *    array will inherit this set of markets.
+     *    - If a subscription in your {@link subscriptions} array defines its own
+     *    {@link KatanaPerpsSubscribeType.markets markets} array, the top-level markets
+     *    **will not be inherited**
+     * @param cid
+     *  - Optionally provide a `cid` property which will be returned in the response
+     *    so that you can correlate the response to the request.
+     * @returns
+     *  - `this` to allow chaining with other methods or requests.
+     * ---
+     *
+     * @example
+     * ```typescript
+     *  import {
+     *    WebSocketClient,
+     *    SubscriptionNamePublic,
+     *    CandleInterval
+     *  } from '@katanaperps/katana-perps-sdk';
+     *
+     *  const client = new WebSocketClient();
+     *
+     *  await client.subscribePublic([
+     *    // will inherit markets from the markets array
+     *    { name: SubscriptionNamePublic.tickers },
+     *    // overrides the top level markets array with its own
+     *    {
+     *      name: SubscriptionNamePublic.candles,
+     *      interval: CandleInterval.ONE_MINUTE,
+     *      // replaces the top-level markets when provided
+     *      markets: ['ETH-USD', 'BTC-USD'],
+     *    },
+     *  ], ['ETH-USD'])
+     * ```
+     *
+     * <br />
+     *
+     * ---
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html#subscribePublic)
+     * @see related  {@link subscribeAuthenticated client.subscribeAuthenticated}
+     *
+     * @category Subscription Management
+     */
+    subscribePublic(subscriptions, markets, cid) {
+        this.throwIfTerminated();
+        this.subscribe(subscriptions, markets, cid);
+        return this;
+    }
+    /**
+     * Unsubscribes from a subscription or subscriptions
+     *
+     * ---
+     *
+     * **Subscription Update Events:**
+     *
+     * - Receives a {@link katanaperps.KatanaPerpsSubscriptionsListEvent KatanaPerpsSubscriptionsListEvent} WebSocket response via
+     *   the {@link katanaperps.WebSocketClient.onMessage WebSocketClient.onMessage} handler listing all active
+     *   subscriptions.
+     *
+     * ---
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html#unsubscribe)
+     * @see related {@link WebSocketRequestUnsubscribeSubscription}
+     *
+     * @category Subscription Management
+     */
+    unsubscribe(subscriptions, markets, cid) {
+        this.throwIfTerminated();
+        return this.sendMessage({
+            cid,
+            method: request_1.WebSocketRequestMethod.unsubscribe,
+            markets,
+            subscriptions,
+        });
+    }
+    /**
+     * List all active subscriptions
+     *
+     * ---
+     *
+     * **Subscription Update Events:**
+     *
+     * - Receives a {@link katanaperps.KatanaPerpsSubscriptionsListEvent KatanaPerpsSubscriptionsListEvent} WebSocket response via
+     *   the {@link katanaperps.WebSocketClient.onMessage WebSocketClient.onMessage} handler listing all active
+     *   subscriptions.
+     *
+     * ---
+     * @param cid
+     *  - Optionally provide a `cid` property which will be returned in the response
+     *    so that you can correlate the response to the request.
+     * @returns
+     *  - `this` to allow chaining with other methods or requests.
+     * ---
+     *
+     * @see typedoc  [Reference Documentation](https://sdk-js-docs-v1-perps.katana.network/classes/WebSocketClient.html#listSubscriptions)
+     *
+     * @category Subscription Management
+     */
+    listSubscriptions(cid) {
+        this.throwIfTerminated();
+        return this.sendMessage({
+            method: request_1.WebSocketRequestMethod.subscriptions,
+            cid,
+        });
+    }
+    /* Private / Protected */
+    /**
+     * @internal
+     */
+    subscribe(subscriptions, markets, cid) {
+        this.throwIfTerminated();
+        this.subscribeRequest(subscriptions, markets, cid).catch((error) => {
+            this.handleWebSocketError(error);
+        });
+        return this;
+    }
+    async subscribeRequest(subscriptions, markets, cid) {
+        const wallet = this.#options.auth?.wallet ?? this.#options.wallet;
+        // One of the two must be provided for authenticated subscriptions
+        const websocketAuthTokenFetch = this.#websocketCustomAuthTokenFetcher ??
+            this.#websocketAutoAuthTokenFetcher;
+        const walletAuthAvailable = !!websocketAuthTokenFetch && !!wallet;
+        const authSubscriptions = subscriptions.filter((subscription) => guards.isWebSocketAuthenticatedSubscription(subscription, walletAuthAvailable));
+        // Public subscriptions can be subscribed all at once
+        if (authSubscriptions.length === 0) {
+            return this.sendMessage({
+                cid,
+                method: request_1.WebSocketRequestMethod.subscribe,
+                markets,
+                subscriptions,
+            });
+        }
+        // For authenticated, we do require token manager
+        if (!websocketAuthTokenFetch) {
+            throw new Error('WebSocket: `websocketAuthTokenFetch` is required for authenticated subscriptions');
+        }
+        if (!wallet) {
+            throw new Error('WebSocket: Missing `wallet` for authenticated subscriptions');
+        }
+        // For single wallet, send all subscriptions at once (also unauthenticated)
+        return this.sendMessage({
+            cid,
+            method: request_1.WebSocketRequestMethod.subscribe,
+            markets,
+            subscriptions,
+            token: await websocketAuthTokenFetch.call(this, this.#options),
+        });
+    }
+    async createWebSocketIfNeeded(awaitConnect = false) {
+        try {
+            this.throwIfTerminated();
+            this.#state.doNotReconnect = false;
+            if (this.#ws) {
+                return this.#ws;
+            }
+            const ws = new isomorphic_ws_1.default(this.#options.baseWebSocketURL, _utils_1.isNode ?
+                {
+                    headers: { 'User-Agent': 'katana-perps-sdk-js' },
+                }
+                : undefined);
+            this.#ws = ws;
+            this.#ws.addEventListener('message', this.handleWebSocketMessage.bind(this));
+            this.#ws.addEventListener('close', this.handleWebSocketClose.bind(this));
+            this.#ws.addEventListener('error', this.handleWebSocketError.bind(this));
+            this.#ws.addEventListener('open', this.handleWebSocketConnect.bind(this));
+            if (awaitConnect) {
+                await this.resolveWhenConnected();
+            }
+            return this.#ws;
+        }
+        catch (err) {
+            if (this.terminated) {
+                return;
+            }
+            let handlerErr = err;
+            if (this.#options.shouldReconnectAutomatically &&
+                !this.#state.doNotReconnect) {
+                this.reconnect();
+                handlerErr = new Error(`Failed to connect: "${err.message}" - a reconnect attempt will be scheduled automatically`);
+            }
+            if (this.#state.errorHandlers.size) {
+                this.handleWebSocketError({
+                    error: handlerErr,
+                    type: 'connection_error',
+                    message: handlerErr.message,
+                    target: this.#ws,
+                });
+            }
+            else {
+                throw handlerErr;
+            }
+        }
+        return this.#ws;
+    }
+    /**
+     * Waits until the WebSocket is connected before returning
+     *
+     * @internal
+     */
+    async resolveWhenConnected(timeout = 5_000) {
+        const { ws } = this;
+        if (!ws) {
+            throw new Error('Can not wait for WebSocket to connect, no WebSocket was found');
+        }
+        if (ws.readyState === ws.OPEN) {
+            return;
+        }
+        if (ws.readyState !== ws.CONNECTING) {
+            throw new Error('Can not wait for WebSocket to connect that is not open or connecting');
+        }
+        await new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                if (this.terminated) {
+                    return;
+                }
+                if (this.#ws === ws) {
+                    this.disconnect();
+                    reject(new Error('timed out while waiting for WebSocket to connect'));
+                }
+            }, timeout);
+            const listener = () => {
+                clearTimeout(timeoutId);
+                ws.removeEventListener('open', listener);
+                resolve(true);
+            };
+            ws.addEventListener('open', listener);
+        });
+    }
+    handleWebSocketConnect() {
+        this.resetReconnectionState();
+        this.startPinging();
+    }
+    // we need to ping from the client side to detect client-side socket closures which would otherwise
+    // not generate any close notifications.  This also aids against idle timeouts being hit.
+    // we can only send a ping from node-based environments, on browsers we need to instead use
+    // a standard message to accomplish this.
+    //
+    // the server will always only reply to custom ping messages with native pong responses so the
+    // client will not recieve any events in the browser when they occur.
+    startPinging() {
+        this.stopPinging();
+        if (!this.isConnected || this.terminated) {
+            return;
+        }
+        try {
+            const { ws } = this;
+            if (!ws) {
+                return;
+            }
+            if (typeof ws.ping === 'function') {
+                ws.ping(JSON.stringify({ method: request_1.WebSocketRequestMethod.ping }));
+            }
+            else {
+                ws.send(JSON.stringify({ method: request_1.WebSocketRequestMethod.ping }));
+            }
+        }
+        finally {
+            if (this.isConnected) {
+                this.#state.pingTimeoutId = setTimeout(this.startPinging.bind(this), exports.WEBSOCKET_PING_TIMEOUT_MS);
+            }
+        }
+    }
+    stopPinging() {
+        clearTimeout(this.#state.pingTimeoutId);
+        this.#state.pingTimeoutId = undefined;
+    }
+    handleWebSocketClose(event) {
+        this.stopPinging();
+        this.#ws = null;
+        this.#state.disconnectHandlers.forEach((listener) => listener(event.code, event.reason));
+        if (!this.terminated &&
+            this.#options.shouldReconnectAutomatically &&
+            !this.#state.doNotReconnect) {
+            this.reconnect();
+        }
+    }
+    handleWebSocketError(event) {
+        this.#state.errorHandlers.forEach((listener) => listener(event));
+    }
+    handleWebSocketMessage(event) {
+        if (this.terminated) {
+            return;
+        }
+        if (!event || !event.data) {
+            throw new Error('Malformed response data'); // Shouldn't happen
+        }
+        const message = (0, transform_1.transformWebsocketShortResponseMessage)(JSON.parse(String(event.data)));
+        this.#state.messageHandlers.forEach((listener) => listener(message));
+    }
+    cancelReconnect() {
+        clearTimeout(this.#state.reconnectTimeoutId);
+        this.#state.isReconnecting = false;
+        this.#state.reconnectTimeoutId = undefined;
+    }
+    reconnect() {
+        // Reconnect with exponential backoff
+        if (!this.#state.isReconnecting &&
+            !this.#state.doNotReconnect &&
+            !this.terminated) {
+            this.disconnect();
+            this.#state.doNotReconnect = false;
+            this.#state.isReconnecting = true;
+            const backoffSeconds = 2 ** this.#state.reconnectAttempt;
+            this.#state.reconnectAttempt += 1;
+            this.log('info', `Reconnecting after ${backoffSeconds} seconds...`);
+            this.#state.reconnectTimeoutId = setTimeout(() => {
+                this.#state.reconnectTimeoutId = undefined;
+                this.connect(false);
+                this.#state.isReconnecting = false;
+            }, backoffSeconds * 1000);
+        }
+    }
+    log(level, ...args) {
+        if (this.#options.logger) {
+            this.#options.logger(`[WebSocketClient] | ${level.toUpperCase()} | clientId:${this.#options.clientId} | `, ...args);
+        }
+    }
+    resetReconnectionState() {
+        this.#state.reconnectAttempt = 0;
+    }
+    sendMessage(payload) {
+        const { ws } = this;
+        this.throwIfDisconnected(ws);
+        ws.send(JSON.stringify(payload));
+        return this;
+    }
+    throwIfDisconnected(_webSocket) {
+        if (!this.isConnected) {
+            throw new Error('Websocket not yet connected, await connect() method first');
+        }
+    }
+}
+exports.WebSocketClient = WebSocketClient;
+/**
+ * @internal
+ */
+function createDefaultWebSocketTokenFetcher({ auth, baseRestApiURL, sandbox, wallet, }) {
+    const client = new authenticated_1.RestAuthenticatedClient({
+        apiKey: auth.apiKey,
+        apiSecret: auth.apiSecret,
+        baseURL: baseRestApiURL,
+        sandbox,
+    });
+    return async function autoWebSocketTokenFetcher() {
+        return client.getWsToken({
+            nonce: (0, uuid_1.v1)(),
+            wallet: auth.wallet ?? wallet,
+        });
+    };
+}