@siebly/kraken-api 0.0.9

package/dist/mjs/WebsocketAPIClient.d.ts

@@ -0,0 +1,95 @@
+import { DefaultLogger } from './lib/websocket/logger.js';
+import { WSAPIAddSpotOrderParams, WSAPIAmendSpotOrderParams, WSAPIBatchAddSpotOrdersParams, WSAPIBatchCancelSpotOrdersParams, WSAPICancelAllSpotOrdersAfterParams, WSAPICancelSpotOrderParams, WSAPIEditSpotOrderParams } from './types/request/wsapi.types.js';
+import { WSAPIAddSpotOrderResult, WSAPIAmendSpotOrderResult, WSAPIBatchAddSpotOrdersResult, WSAPIBatchCancelSpotOrdersResult, WSAPICancelAllSpotOrdersAfterResult, WSAPICancelAllSpotOrdersResult, WSAPICancelSpotOrderResult, WSAPIEditSpotOrderResult } from './types/response/wsapi.types.js';
+import { WSAPISpotResponse, WSAPIWsKey } from './types/websockets/ws-api.js';
+import { WSClientConfigurableOptions } from './types/websockets/ws-general.js';
+import { WebsocketClient } from './WebsocketClient.js';
+/**
+ * Configurable options specific to only the REST-like WebsocketAPIClient
+ */
+export interface WSAPIClientConfigurableOptions {
+    /**
+     * Default: true
+     *
+     * Attach default event listeners, which will console log any high level
+     * events (opened/reconnecting/reconnected/etc).
+     *
+     * If you disable this, you should set your own event listeners
+     * on the embedded WS Client `wsApiClient.getWSClient().on(....)`.
+     */
+    attachEventListeners: boolean;
+}
+/**
+ * This is a minimal Websocket API wrapper around the WebsocketClient.
+ *
+ * Some methods support passing in a custom "wsKey". This is a reference to which WS connection should
+ * be used to transmit that message. This is only useful if you wish to use an alternative wss
+ * domain that is supported by the SDK. E.g. WS_API_KEY_MAP.spotBetaPrivateV2.
+ *
+ * Note: You can also directly use the sendWSAPIRequest() method to make WS API calls, but some
+ * may find the below methods slightly more intuitive.
+ *
+ * Refer to the WS API promises example for a more detailed example on using sendWSAPIRequest() directly:
+ * https://github.com/sieblyio/kraken-api/blob/main/examples/WebSockets/Spot/wsAPI.RAW.ts#L105
+ *
+ * Docs:
+ * - Spot WS API: https://docs.kraken.com/api/docs/websocket-v2/add_order/
+ */
+export declare class WebsocketAPIClient {
+    private wsClient;
+    private options;
+    constructor(options?: WSClientConfigurableOptions & Partial<WSAPIClientConfigurableOptions>, logger?: DefaultLogger);
+    getWSClient(): WebsocketClient;
+    /**
+     * Add a spot order
+     */
+    submitSpotOrder(params: Omit<WSAPIAddSpotOrderParams, 'token' | 'req_id'>, wsKey?: WSAPIWsKey): Promise<WSAPISpotResponse<WSAPIAddSpotOrderResult, 'add_order'>>;
+    /**
+     * Amend an existing order
+     */
+    amendSpotOrder(params: WSAPIAmendSpotOrderParams, wsKey?: WSAPIWsKey): Promise<WSAPISpotResponse<WSAPIAmendSpotOrderResult, 'amend_order'>>;
+    /**
+     * Cancel one or more orders
+     */
+    cancelSpotOrder(params: WSAPICancelSpotOrderParams, wsKey?: WSAPIWsKey): Promise<WSAPISpotResponse<WSAPICancelSpotOrderResult, 'cancel_order'>>;
+    /**
+     * Cancel all open orders
+     */
+    cancelAllSpotOrders(wsKey?: WSAPIWsKey): Promise<WSAPISpotResponse<WSAPICancelAllSpotOrdersResult, 'cancel_all'>>;
+    /**
+     * Cancel all orders after a timeout (Dead Man's Switch)
+     */
+    cancelAllSpotOrdersAfter(params: WSAPICancelAllSpotOrdersAfterParams, wsKey?: WSAPIWsKey): Promise<WSAPISpotResponse<WSAPICancelAllSpotOrdersAfterResult, 'cancel_all_orders_after'>>;
+    /**
+     * Add multiple orders in a single batch (2-15 orders)
+     */
+    batchSubmitSpotOrders(params: WSAPIBatchAddSpotOrdersParams, wsKey?: WSAPIWsKey): Promise<WSAPISpotResponse<WSAPIBatchAddSpotOrdersResult[], 'batch_add'>>;
+    /**
+     * Cancel multiple orders in a single batch (2-50 orders)
+     */
+    batchCancelSpotOrders(params: WSAPIBatchCancelSpotOrdersParams, wsKey?: WSAPIWsKey): Promise<WSAPISpotResponse<WSAPIBatchCancelSpotOrdersResult, 'batch_cancel'>>;
+    /**
+     * Edit an existing order (legacy method, use amendSpotOrder instead)
+     * @deprecated Use amendSpotOrder for better performance and features
+     */
+    editSpotOrder(params: WSAPIEditSpotOrderParams, wsKey?: WSAPIWsKey): Promise<WSAPISpotResponse<WSAPIEditSpotOrderResult, 'edit_order'>>;
+    /**
+     *
+     *
+     *
+     *
+     *
+     *
+     *
+     * Private methods for handling some of the convenience/automation provided by the WS API Client
+     *
+     *
+     *
+     *
+     *
+     *
+     *
+     */
+    connectWSAPI(wsKey: WSAPIWsKey): Promise<unknown>;
+    private setupDefaultEventListeners;
+}

package/dist/mjs/WebsocketAPIClient.js

@@ -0,0 +1,132 @@
+import { WS_KEY_MAP } from './lib/websocket/websocket-util.js';
+import { WebsocketClient } from './WebsocketClient.js';
+/**
+ * This is a minimal Websocket API wrapper around the WebsocketClient.
+ *
+ * Some methods support passing in a custom "wsKey". This is a reference to which WS connection should
+ * be used to transmit that message. This is only useful if you wish to use an alternative wss
+ * domain that is supported by the SDK. E.g. WS_API_KEY_MAP.spotBetaPrivateV2.
+ *
+ * Note: You can also directly use the sendWSAPIRequest() method to make WS API calls, but some
+ * may find the below methods slightly more intuitive.
+ *
+ * Refer to the WS API promises example for a more detailed example on using sendWSAPIRequest() directly:
+ * https://github.com/sieblyio/kraken-api/blob/main/examples/WebSockets/Spot/wsAPI.RAW.ts#L105
+ *
+ * Docs:
+ * - Spot WS API: https://docs.kraken.com/api/docs/websocket-v2/add_order/
+ */
+export class WebsocketAPIClient {
+    wsClient;
+    options;
+    constructor(options, logger) {
+        this.wsClient = new WebsocketClient(options, logger);
+        this.options = {
+            attachEventListeners: true,
+            ...options,
+        };
+        this.setupDefaultEventListeners();
+    }
+    getWSClient() {
+        return this.wsClient;
+    }
+    /**
+     * Add a spot order
+     */
+    submitSpotOrder(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || WS_KEY_MAP.spotPrivateV2, 'add_order', params);
+    }
+    /**
+     * Amend an existing order
+     */
+    amendSpotOrder(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || WS_KEY_MAP.spotPrivateV2, 'amend_order', params);
+    }
+    /**
+     * Cancel one or more orders
+     */
+    cancelSpotOrder(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || WS_KEY_MAP.spotPrivateV2, 'cancel_order', params);
+    }
+    /**
+     * Cancel all open orders
+     */
+    cancelAllSpotOrders(wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || WS_KEY_MAP.spotPrivateV2, 'cancel_all');
+    }
+    /**
+     * Cancel all orders after a timeout (Dead Man's Switch)
+     */
+    cancelAllSpotOrdersAfter(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || WS_KEY_MAP.spotPrivateV2, 'cancel_all_orders_after', params);
+    }
+    /**
+     * Add multiple orders in a single batch (2-15 orders)
+     */
+    batchSubmitSpotOrders(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || WS_KEY_MAP.spotPrivateV2, 'batch_add', params);
+    }
+    /**
+     * Cancel multiple orders in a single batch (2-50 orders)
+     */
+    batchCancelSpotOrders(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || WS_KEY_MAP.spotPrivateV2, 'batch_cancel', params);
+    }
+    /**
+     * Edit an existing order (legacy method, use amendSpotOrder instead)
+     * @deprecated Use amendSpotOrder for better performance and features
+     */
+    editSpotOrder(params, wsKey) {
+        return this.wsClient.sendWSAPIRequest(wsKey || WS_KEY_MAP.spotPrivateV2, 'edit_order', params);
+    }
+    /**
+     *
+     *
+     *
+     *
+     *
+     *
+     *
+     * Private methods for handling some of the convenience/automation provided by the WS API Client
+     *
+     *
+     *
+     *
+     *
+     *
+     *
+     */
+    connectWSAPI(wsKey) {
+        return this.getWSClient().assertIsAuthenticated(wsKey);
+    }
+    setupDefaultEventListeners() {
+        if (this.options.attachEventListeners) {
+            /**
+             * General event handlers for monitoring the WebsocketClient
+             */
+            this.wsClient
+                .on('open', (data) => {
+                console.log(new Date(), 'ws connected', data.wsKey);
+            })
+                .on('reconnecting', ({ wsKey }) => {
+                console.log(new Date(), 'ws automatically reconnecting.... ', wsKey);
+            })
+                .on('reconnected', (data) => {
+                console.log(new Date(), 'ws has reconnected ', data?.wsKey);
+            })
+                .on('authenticated', (data) => {
+                console.info(new Date(), 'ws has authenticated ', data?.wsKey);
+            })
+                .on('exception', (data) => {
+                try {
+                    // Blind JSON.stringify can fail on circular references
+                    console.error(new Date(), 'ws exception: ', JSON.stringify(data));
+                }
+                catch {
+                    console.error(new Date(), 'ws exception: ', data);
+                }
+            });
+        }
+    }
+}
+//# sourceMappingURL=WebsocketAPIClient.js.map

package/dist/mjs/WebsocketAPIClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebsocketAPIClient.js","sourceRoot":"","sources":["../../src/WebsocketAPIClient.ts"],"names":[],"mappings":"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"}

package/dist/mjs/WebsocketClient.d.ts

@@ -0,0 +1,120 @@
+import { BaseWebsocketClient, EmittableEvent, MidflightWsRequestEvent } from './lib/BaseWSClient.js';
+import { DefaultLogger } from './lib/websocket/logger.js';
+import { WsKey, WSOperation, WSRequestOperationKraken, WSTopicRequest } from './lib/websocket/websocket-util.js';
+import { WSConnectedResult } from './lib/websocket/WsStore.types.js';
+import { Exact, WSAPIAuthenticationRequestFromServer, WSAPITopicRequestParamMap, WSAPITopicResponseMap, WSAPIWsKey, WSAPIWsKeyTopicMap } from './types/websockets/ws-api.js';
+import { MessageEventLike } from './types/websockets/ws-events.js';
+import { WSClientConfigurableOptions, WsMarket } from './types/websockets/ws-general.js';
+import { WSTopic } from './types/websockets/ws-subscriptions.js';
+export interface WSAPIRequestFlags {
+    /** If true, will skip auth requirement for WS API connection */
+    authIsOptional?: boolean | undefined;
+}
+export declare class WebsocketClient extends BaseWebsocketClient<WsKey, any> {
+    private restClientCache;
+    private wsChallengeCache;
+    constructor(options?: WSClientConfigurableOptions, logger?: DefaultLogger);
+    /**
+     * Request connection of all dependent (public & private) websockets, instead of waiting for automatic connection by library.
+     *
+     * Returns array of promises that individually resolve when each connection is successfully opened.
+     */
+    connectAll(): Promise<WSConnectedResult | undefined>[];
+    /**
+     * Ensures the WS API connection is active and ready.
+     *
+     * You do not need to call this, but if you call this before making any WS API requests,
+     * it can accelerate the first request (by preparing the connection in advance).
+     */
+    connectWSAPI(wsKey: WSAPIWsKey, skipAuth?: boolean): Promise<unknown>;
+    /**
+     * Request subscription to one or more topics. Pass topics as either an array of strings, or array of objects (if the topic has parameters).
+     * Objects should be formatted as {topic: string, params: object}.
+     *
+     * - Subscriptions are automatically routed to the correct websocket connection.
+     * - Authentication/connection is automatic.
+     * - Resubscribe after network issues is automatic.
+     *
+     * Call `unsubscribe(topics)` to remove topics
+     */
+    subscribe(requests: (WSTopicRequest<WSTopic> | WSTopic) | (WSTopicRequest<WSTopic> | WSTopic)[], wsKey: WsKey): void;
+    /**
+     * Unsubscribe from one or more topics. Similar to subscribe() but in reverse.
+     *
+     * - Requests are automatically routed to the correct websocket connection.
+     * - These topics will be removed from the topic cache, so they won't be subscribed to again.
+     */
+    unsubscribe(requests: (WSTopicRequest<WSTopic> | WSTopic) | (WSTopicRequest<WSTopic> | WSTopic)[], wsKey: WsKey): void;
+    /**
+     * WS API Methods - similar to the REST API, but via WebSockets
+     */
+    /**
+     * Send a Websocket API event on a connection. Returns a promise that resolves on reply.
+     *
+     * Returned promise is rejected if an exception is detected in the reply OR the connection disconnects for any reason (even if automatic reconnect will happen).
+     *
+     * After a fresh connection, you should always send a login request first.
+     *
+     * If you authenticated once and you're reconnected later (e.g. connection temporarily lost), the SDK will by default automatically:
+     * - Detect you were authenticated to the WS API before
+     * - Try to re-authenticate (up to 5 times, in case something (bad timestamp) goes wrong)
+     * - If it succeeds, it will emit the 'authenticated' event.
+     * - If it fails and gives up, it will emit an 'exception' event (type: 'wsapi.auth', reason: detailed text).
+     *
+     * You can turn off the automatic re-auth WS API logic using `reauthWSAPIOnReconnect: false` in the WSClient config.
+     *
+     * @param wsKey - The connection this event is for (e.g. "spotV4" | "perpFuturesUSDTV4" | "perpFuturesBTCV4" | "deliveryFuturesUSDTV4" | "deliveryFuturesBTCV4" | "optionsV4")
+     * @param channel - The channel this event is for (e.g. "spot.login" to authenticate)
+     * @param params - Any request parameters for the payload (contents of req_param in the docs). Signature generation is automatic, only send parameters such as order ID as per the docs.
+     * @returns Promise - tries to resolve with async WS API response. Rejects if disconnected or exception is seen in async WS API response
+     */
+    sendWSAPIRequest<TWSKey extends keyof WSAPIWsKeyTopicMap, TWSOperation extends WSAPIWsKeyTopicMap[TWSKey], TWSParams extends Exact<WSAPITopicRequestParamMap[TWSOperation]>, TWSAPIResponse extends WSAPITopicResponseMap[TWSOperation] | object = WSAPITopicResponseMap[TWSOperation]>(wsKey: TWSKey, operation: TWSOperation, params?: TWSParams extends void | never ? undefined : TWSParams, requestFlags?: WSAPIRequestFlags): Promise<TWSAPIResponse>;
+    /**
+     *
+     * Internal methods - not intended for public use
+     *
+     */
+    private getRestClientOptions;
+    /**
+     * Note: implementing this method will wipe the WsStore state for this WsKey, once this method returns
+     */
+    protected isCustomReconnectionNeeded(): boolean;
+    protected triggerCustomReconnectionWorkflow(): Promise<void>;
+    protected getWsUrl(wsKey: WsKey): Promise<string>;
+    protected sendPingEvent(wsKey: WsKey): void;
+    protected sendPongEvent(wsKey: WsKey): void;
+    protected isWsPing(_msg: any): boolean;
+    protected isWsPong(msg: any): boolean;
+    /**
+     * Parse incoming events into categories, before emitting to the user
+     */
+    protected resolveEmittableEvents(wsKey: WsKey, event: MessageEventLike): EmittableEvent[];
+    /**
+     * Determines if a topic is for a private channel, using a hardcoded list of strings
+     */
+    protected isPrivateTopicRequest(request: WSTopicRequest<any>): boolean;
+    /**
+     * Not in use for Kraken
+     */
+    protected getWsMarketForWsKey(_wsKey: WsKey): WsMarket;
+    /**
+     * Whether key represents a private connection. Feeds into automatic auth on connect.
+     */
+    protected getPrivateWSKeys(): WsKey[];
+    protected isAuthOnConnectWsKey(wsKey: WsKey): boolean;
+    /** Force subscription requests to be sent in smaller batches, if a number is returned */
+    protected getMaxTopicsPerSubscribeEvent(_wsKey: WsKey): number | null;
+    protected authPrivateConnectionsOnConnect(wsKey: WsKey): boolean;
+    /**
+     * @returns one or more correctly structured request events for performing a operations over WS. This can vary per exchange spec.
+     */
+    protected getWsRequestEvents(wsKey: WsKey, operation: WSOperation, requests: WSTopicRequest<WSTopic>[]): Promise<MidflightWsRequestEvent<WSRequestOperationKraken<string>>[]>;
+    private signMessage;
+    protected getWsAuthRequestEvent(wsKey: WsKey, eventToAuth?: WSAPIAuthenticationRequestFromServer): Promise<object | string | 'waitForEvent' | void>;
+    /**
+     *
+     * @param requestEvent
+     * @returns A signed updated WS API request object, ready to be sent
+     */
+    private signWSAPIRequest;
+}