@siebly/kraken-api 0.0.9

package/dist/cjs/lib/BaseWSClient.d.ts

@@ -0,0 +1,230 @@
+import { EventEmitter } from 'events';
+import WebSocket from 'isomorphic-ws';
+import { MessageEventLike } from '../types/websockets/ws-events.js';
+import { WebsocketClientOptions, WSClientConfigurableOptions } from '../types/websockets/ws-general.js';
+import { WSTopic } from '../types/websockets/ws-subscriptions.js';
+import { DefaultLogger } from './websocket/logger.js';
+import { WSOperation, WSTopicRequest, WSTopicRequestOrStringTopic } from './websocket/websocket-util.js';
+import { WsStore } from './websocket/WsStore.js';
+import { WSConnectedResult } from './websocket/WsStore.types.js';
+type UseTheExceptionEventInstead = never;
+interface WSClientEventMap<WsKey extends string> {
+    /** Connection opened. If this connection was previously opened and reconnected, expect the reconnected event instead */
+    open: (evt: {
+        wsKey: WsKey;
+        event: any;
+        wsUrl: string;
+        ws: WebSocket;
+    }) => void;
+    /** Reconnecting a dropped connection */
+    reconnecting: (evt: {
+        wsKey: WsKey;
+        event: any;
+    }) => void;
+    /** Successfully reconnected a connection that dropped */
+    reconnected: (evt: {
+        wsKey: WsKey;
+        event: any;
+        wsUrl: string;
+        ws: WebSocket;
+    }) => void;
+    /** Connection closed */
+    close: (evt: {
+        wsKey: WsKey;
+        event: any;
+    }) => void;
+    /** Received reply to websocket command (e.g. after subscribing to topics) */
+    response: (response: any & {
+        wsKey: WsKey;
+    }) => void;
+    /** Received data for topic */
+    message: (response: any & {
+        wsKey: WsKey;
+    }) => void;
+    /** Exception from ws client OR custom listeners (e.g. if you throw inside your event handler) */
+    exception: (response: any & {
+        wsKey: WsKey;
+    }) => void;
+    /**
+     * See for more information: https://github.com/tiagosiebler/bybit-api/issues/413
+     * @deprecated Use the 'exception' event instead. The 'error' event had the unintended consequence of throwing an unhandled promise rejection.
+     */
+    error: UseTheExceptionEventInstead;
+    /** Confirmation that a connection successfully authenticated */
+    authenticated: (event: {
+        wsKey: WsKey;
+        event: any;
+    }) => void;
+}
+export interface EmittableEvent<TEventType extends keyof WSClientEventMap<string> = keyof WSClientEventMap<string>> {
+    eventType: TEventType | 'pong' | 'connectionReady' | 'connectionReadyForAuth';
+    event: Parameters<WSClientEventMap<string>[TEventType]>[0];
+    isWSAPIResponse?: boolean;
+}
+export interface BaseWebsocketClient<TWSKey extends string, TWSRequestEvent extends object> {
+    on<U extends keyof WSClientEventMap<TWSKey>>(event: U, listener: WSClientEventMap<TWSKey>[U]): this;
+    emit<U extends keyof WSClientEventMap<TWSKey>>(event: U, ...args: Parameters<WSClientEventMap<TWSKey>[U]>): boolean;
+}
+/**
+ * A midflight WS request event (e.g. subscribe to these topics).
+ *
+ * - requestKey: unique identifier for this request, if available. Can be anything as a string.
+ * - requestEvent: the raw request, as an object, that will be sent on the ws connection. This may contain multiple topics/requests in one object, if the exchange supports it.
+ */
+export interface MidflightWsRequestEvent<TEvent = object> {
+    requestKey: string | number;
+    requestEvent: TEvent;
+}
+export declare abstract class BaseWebsocketClient<TWSKey extends string, TWSRequestEvent extends object> extends EventEmitter {
+    private wsStore;
+    protected logger: DefaultLogger;
+    protected options: WebsocketClientOptions;
+    private wsApiRequestId;
+    private timeOffsetMs;
+    private WS_LOGGER_CATEGORY;
+    constructor(options?: WSClientConfigurableOptions & {
+        wsLoggerCategory: string;
+    }, logger?: DefaultLogger);
+    /**
+     * Return true if this wsKey connection should automatically authenticate immediately after connecting
+     */
+    protected abstract isAuthOnConnectWsKey(wsKey: TWSKey): boolean;
+    protected abstract isCustomReconnectionNeeded(wsKey: TWSKey): boolean;
+    protected abstract triggerCustomReconnectionWorkflow(wsKey: TWSKey): Promise<void>;
+    protected abstract sendPingEvent(wsKey: TWSKey, ws: WebSocket): void;
+    protected abstract sendPongEvent(wsKey: TWSKey, ws: WebSocket): void;
+    protected abstract isWsPing(data: any): boolean;
+    protected abstract isWsPong(data: any): boolean;
+    protected abstract authPrivateConnectionsOnConnect(_wsKey: TWSKey): boolean;
+    /**
+     * Return the event sent to the server to trigger authentication. If the event requires waiting for another event first (e.g. a challenge), return 'waitForEvent' and the library will wait for that event before calling this method again.
+     *
+     * Usually only called once per connection, unless the connection drops/is reset.
+     */
+    protected abstract getWsAuthRequestEvent(wsKey: TWSKey, eventToAuth?: object): Promise<object | string | 'waitForEvent' | void>;
+    protected abstract isPrivateTopicRequest(request: WSTopicRequest<WSTopic>, wsKey: TWSKey): boolean;
+    /**
+     * Returns a list of string events that can be individually sent upstream to complete subscribing/unsubscribing/etc to these topics
+     */
+    protected abstract getPrivateWSKeys(): TWSKey[];
+    protected abstract getWsUrl(wsKey: TWSKey): Promise<string>;
+    protected abstract getMaxTopicsPerSubscribeEvent(wsKey: TWSKey): number | null;
+    /**
+     * @returns one or more correctly structured request events for performing a operations over WS. This can vary per exchange spec.
+     */
+    protected abstract getWsRequestEvents(wsKey: TWSKey, operation: WSOperation, requests: WSTopicRequest<WSTopic>[]): Promise<MidflightWsRequestEvent<TWSRequestEvent>[]>;
+    /**
+     * Abstraction called to sort ws events into emittable event types (response to a request, data update, etc)
+     */
+    protected abstract resolveEmittableEvents(wsKey: TWSKey, event: MessageEventLike): EmittableEvent[];
+    /**
+     * Request connection of all dependent (public & private) websockets, instead of waiting for automatic connection by library
+     */
+    protected abstract connectAll(): Promise<WSConnectedResult | undefined>[];
+    protected isPrivateWsKey(wsKey: TWSKey): boolean;
+    /** Returns auto-incrementing request ID, used to track promise references for async requests */
+    protected getNewRequestId(): number;
+    protected abstract sendWSAPIRequest(wsKey: TWSKey, operation: string, params?: any): Promise<unknown>;
+    protected abstract sendWSAPIRequest(wsKey: TWSKey, channel: string, params: any): Promise<unknown>;
+    getTimeOffsetMs(): number;
+    setTimeOffsetMs(newOffset: number): void;
+    /**
+     * Don't call directly! Use subscribe() instead!
+     *
+     * Subscribe to one or more topics on a WS connection (identified by WS Key).
+     *
+     * - Topics are automatically cached
+     * - Connections are automatically opened, if not yet connected
+     * - Authentication is automatically handled
+     * - Topics are automatically resubscribed to, if something happens to the connection, unless you call unsubsribeTopicsForWsKey(topics, key).
+     *
+     * @param wsTopicRequests array of topics to subscribe to
+     * @param wsKey ws key referring to the ws connection these topics should be subscribed on
+     */
+    protected subscribeTopicsForWsKey(wsTopicRequests: WSTopicRequestOrStringTopic<WSTopic>[], wsKey: TWSKey): Promise<boolean | void | WSConnectedResult>;
+    protected unsubscribeTopicsForWsKey(wsTopicRequests: WSTopicRequestOrStringTopic<WSTopic>[], wsKey: TWSKey): Promise<unknown>;
+    /**
+     * Splits topic requests into two groups, public & private topic requests
+     */
+    private sortTopicRequestsIntoPublicPrivate;
+    /** Get the WsStore that tracks websockets & topics */
+    getWsStore(): WsStore<TWSKey, WSTopicRequest<WSTopic>>;
+    close(wsKey: TWSKey, force?: boolean): void;
+    closeAll(force?: boolean): void;
+    isConnected(wsKey: TWSKey): boolean;
+    /**
+     * Request connection to a specific websocket, instead of waiting for automatic connection.
+     */
+    connect(wsKey: TWSKey, customUrl?: string | undefined, throwOnError?: boolean): Promise<WSConnectedResult | undefined>;
+    private connectToWsUrl;
+    private parseWsError;
+    /** Get a signature, build the auth request and send it */
+    private sendAuthRequest;
+    private reconnectWithDelay;
+    private ping;
+    /**
+     * Closes a connection, if it's even open. If open, this will trigger a reconnect asynchronously.
+     * If closed, trigger a reconnect immediately
+     */
+    protected executeReconnectableClose(wsKey: TWSKey, reason: string): void;
+    private clearTimers;
+    private clearPingTimer;
+    private clearPongTimer;
+    private clearReconnectTimer;
+    /**
+     * Returns a list of string events that can be individually sent upstream to complete subscribing/unsubscribing/etc to these topics
+     *
+     * If events are an object, these should be stringified (`return JSON.stringify(event);`)
+     * Each event returned by this will be sent one at a time
+     *
+     * Events are automatically split into smaller batches, by this method, if needed.
+     */
+    protected getWsOperationEventsForTopics(topics: WSTopicRequest<WSTopic>[], wsKey: TWSKey, operation: WSOperation): Promise<MidflightWsRequestEvent<TWSRequestEvent>[]>;
+    /**
+     * Simply builds and sends subscribe events for a list of topics for a ws key
+     *
+     * @private Use the `subscribe(topics)` or `subscribeTopicsForWsKey(topics, wsKey)` method to subscribe to topics. Send WS message to subscribe to topics.
+     */
+    private requestSubscribeTopics;
+    /**
+     * Simply builds and sends unsubscribe events for a list of topics for a ws key
+     *
+     * @private Use the `unsubscribe(topics)` method to unsubscribe from topics. Send WS message to unsubscribe from topics.
+     */
+    private requestUnsubscribeTopics;
+    /**
+     * Try sending a string event on a WS connection (identified by the WS Key)
+     */
+    tryWsSend(wsKey: TWSKey, wsMessage: string, throwExceptions?: boolean): void;
+    private onWsOpen;
+    private resolveConnectionInProgressPromise;
+    /**
+     * Called automatically once a connection is ready.
+     * - Some exchanges are ready immediately after the connections open.
+     * - Some exchanges send an event to confirm the connection is ready for us.
+     *
+     * This method is called to act when the connection is ready. Use `requireConnectionReadyConfirmation` to control how this is called.
+     */
+    private onWsReadyForEvents;
+    /**
+     * Handle subscription to private topics _after_ authentication successfully completes asynchronously.
+     *
+     * Only used for exchanges that require auth before sending private topic subscription requests
+     */
+    private onWsAuthenticated;
+    private onWsPing;
+    private onWsPong;
+    private onWsMessage;
+    private onWsClose;
+    private getWs;
+    private setWsState;
+    /**
+     * Promise-driven method to assert that a ws has successfully connected (will await until connection is open)
+     */
+    protected assertIsConnected(wsKey: TWSKey): Promise<unknown>;
+    /**
+     * Promise-driven method to assert that a ws has been successfully authenticated (will await until auth is confirmed)
+     */
+    assertIsAuthenticated(wsKey: TWSKey): Promise<unknown>;
+}
+export {};