okx-api 2.0.7 → 3.0.0-beta.0

package/{lib → dist/cjs}/util/typeGuards.js

@@ -9,6 +9,7 @@ exports.isWsSubscribeEvent = isWsSubscribeEvent;
 exports.isWsUnsubscribeEvent = isWsUnsubscribeEvent;
 exports.isConnCountEvent = isConnCountEvent;
 exports.neverGuard = neverGuard;
+exports.isWSAPIResponse = isWSAPIResponse;
 function isRawAPIResponse(response) {
     if (typeof response !== 'object' || !response) {
         return false;
@@ -60,4 +61,37 @@ function isConnCountEvent(evtData) {
 function neverGuard(x, msg) {
     return new Error(`Unhandled value exception "${x}", ${msg}`);
 }
+function isWSAPIResponse(msg) {
+    if (typeof msg !== 'object' || !msg) {
+        return false;
+    }
+    const response = msg;
+    /**
+     * Very simple type guard around this structure. Could also just check the "op" is a known WS API operation, but this might be slightly faster as the list of operations grows:
+      {
+        id: '2',
+        op: 'order',
+        code: '1',
+        msg: '',
+        data: [
+          {
+            tag: '159881cb7207BCDE',
+            ts: '1753783406701',
+            ordId: '',
+            clOrdId: '',
+            sCode: 'asdfasfsafdasf',
+            sMsg: 'adsfadsfasdf'
+          }
+        ],
+        inTime: '1753783406701275',
+        outTime: '1753783406702251',
+        wsKey: 'prodPrivate',
+        isWSAPIResponse: false
+      }
+     */
+    if (typeof response.id !== 'string' || typeof response.inTime !== 'string') {
+        return false;
+    }
+    return true;
+}
 //# sourceMappingURL=typeGuards.js.map

package/dist/cjs/util/typeGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typeGuards.js","sourceRoot":"","sources":["../../../src/util/typeGuards.ts"],"names":[],"mappings":";;AAQA,4CAYC;AAGD,8BAUC;AAED,sCASC;AAED,wCAEC;AAGD,wCAEC;AAGD,gDAEC;AAGD,oDAEC;AAGD,4CAEC;AAGD,gCAEC;AAED,0CAoCC;AAvGD,SAAgB,gBAAgB,CAC9B,QAAiB;IAEjB,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,MAAM,IAAI,QAAQ,IAAI,KAAK,IAAI,QAAQ,IAAI,MAAM,IAAI,QAAQ,EAAE,CAAC;QAClE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,4EAA4E;AAC5E,SAAgB,SAAS,CAAC,OAAgB;IACxC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAgB,aAAa,CAAC,OAAgB;IAC5C,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,IAAI,OAAO,IAAI,MAAM,IAAI,OAAO,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAgB,cAAc,CAAC,GAAY;IACzC,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,KAAK,KAAK,OAAO,CAAC;AACjD,CAAC;AAED,mDAAmD;AACnD,SAAgB,cAAc,CAAC,GAAY;IACzC,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,KAAK,KAAK,OAAO,CAAC;AACjD,CAAC;AAED,6CAA6C;AAC7C,SAAgB,kBAAkB,CAAC,OAAgB;IACjD,OAAO,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,KAAK,WAAW,CAAC;AAC7D,CAAC;AAED,iDAAiD;AACjD,SAAgB,oBAAoB,CAAC,OAAgB;IACnD,OAAO,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,KAAK,aAAa,CAAC;AAC/D,CAAC;AAED,wBAAwB;AACxB,SAAgB,gBAAgB,CAAC,OAAgB;IAC/C,OAAO,SAAS,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,KAAK,oBAAoB,CAAC;AACtE,CAAC;AAED,uGAAuG;AACvG,SAAgB,UAAU,CAAC,CAAQ,EAAE,GAAW;IAC9C,OAAO,IAAI,KAAK,CAAC,8BAA8B,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,SAAgB,eAAe,CAC7B,GAAY;IAEZ,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,GAAG,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,GAAoB,CAAC;IACtC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,IAAI,OAAO,QAAQ,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,QAAQ,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC3E,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/cjs/util/webCryptoAPI.d.ts

@@ -0,0 +1,15 @@
+export type SignEncodeMethod = 'hex' | 'base64';
+export type SignAlgorithm = 'SHA-256' | 'SHA-512';
+/**
+ * Similar to node crypto's `createHash()` function
+ */
+type KeyType = 'HMAC' | 'RSASSA-PKCS1-v1_5' | 'Ed25519';
+export declare function getSignKeyType(secret: string): KeyType;
+/**
+ * Sign a message, with a secret, using the Web Crypto API
+ *
+ * Ed25519 is stable as of v23.5.0, but also not available in all browsers
+ */
+export declare function signMessage(message: string, secret: string, method: SignEncodeMethod, algorithm: SignAlgorithm, _pemEncodeMethod?: SignEncodeMethod): Promise<string>;
+export declare function checkWebCryptoAPISupported(): void;
+export {};

package/dist/cjs/util/webCryptoAPI.js

@@ -0,0 +1,82 @@
+"use strict";
+/* eslint-disable @typescript-eslint/no-unused-vars */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSignKeyType = getSignKeyType;
+exports.signMessage = signMessage;
+exports.checkWebCryptoAPISupported = checkWebCryptoAPISupported;
+const typeGuards_js_1 = require("./typeGuards.js");
+function bufferToB64(buffer) {
+    let binary = '';
+    const bytes = new Uint8Array(buffer);
+    const len = bytes.byteLength;
+    for (let i = 0; i < len; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return globalThis.btoa(binary);
+}
+function getSignKeyType(secret) {
+    if (secret.includes('PRIVATE KEY')) {
+        // Sometimes, not always, RSA keys include "RSA" in the header. That's a definite RSA key.
+        if (secret.includes('RSA PRIVATE KEY')) {
+            return 'RSASSA-PKCS1-v1_5';
+        }
+        // RSA keys are significantly longer than Ed25519 keys. 150 accounts for length of header & footer
+        if (secret.length <= 150) {
+            return 'Ed25519';
+        }
+        return 'RSASSA-PKCS1-v1_5';
+    }
+    return 'HMAC';
+}
+async function importKey(pem, type, algorithm, encoder) {
+    switch (type) {
+        case 'Ed25519':
+        case 'RSASSA-PKCS1-v1_5': {
+            const base64Key = pem.replace(/(?:-----BEGIN RSA PRIVATE KEY-----|-----BEGIN PRIVATE KEY-----|-----END RSA PRIVATE KEY-----|-----END PRIVATE KEY-----|\s+)/g, '');
+            const binaryKey = Uint8Array.from(atob(base64Key), (c) => c.charCodeAt(0));
+            return globalThis.crypto.subtle.importKey('pkcs8', binaryKey.buffer, { name: type, hash: { name: algorithm } }, false, ['sign']);
+        }
+        case 'HMAC': {
+            return globalThis.crypto.subtle.importKey('raw', encoder.encode(pem), { name: type, hash: algorithm }, false, ['sign']);
+        }
+        default: {
+            throw (0, typeGuards_js_1.neverGuard)(type, `Unhandled key type: "${type}"`);
+        }
+    }
+}
+/**
+ * Sign a message, with a secret, using the Web Crypto API
+ *
+ * Ed25519 is stable as of v23.5.0, but also not available in all browsers
+ */
+async function signMessage(message, secret, method, algorithm, _pemEncodeMethod = method) {
+    const encoder = new TextEncoder();
+    const signKeyType = getSignKeyType(secret);
+    const key = await importKey(secret, signKeyType, algorithm, encoder);
+    const buffer = await globalThis.crypto.subtle.sign({ name: signKeyType }, key, encoder.encode(message));
+    switch (method) {
+        case 'hex': {
+            return Array.from(new Uint8Array(buffer))
+                .map((byte) => byte.toString(16).padStart(2, '0'))
+                .join('');
+        }
+        case 'base64': {
+            return bufferToB64(buffer);
+        }
+        default: {
+            throw (0, typeGuards_js_1.neverGuard)(method, `Unhandled sign method: "${method}"`);
+        }
+    }
+}
+function checkWebCryptoAPISupported() {
+    if (!globalThis.crypto) {
+        throw new Error(`Web Crypto API unavailable. Authentication will not work.
+
+      Are you using an old Node.js release? Refer to the current Node.js LTS version. Node.js v18 reached end of life in April 2025! You should be using Node LTS or newer (v22 or above)!
+
+      If you prefer to continue using an outdated Node.js version, check github for an example on using the node:crypto module for sign instead:
+      https://github.com/tiagosiebler/okx-api/blob/master/examples/fasterHmacSign.ts
+      `);
+    }
+}
+//# sourceMappingURL=webCryptoAPI.js.map

package/dist/cjs/util/webCryptoAPI.js.map

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

package/dist/cjs/util/websocket-util.d.ts

@@ -0,0 +1,142 @@
+import { APIMarket } from '../types/shared.js';
+import { WSAPIOperation, WSAPIRequestOKX } from '../types/websockets/ws-api.js';
+import { WebsocketClientOptions } from '../types/websockets/ws-general.js';
+import { WsChannel } from '../types/websockets/ws-request.js';
+import { DefaultLogger } from './logger.js';
+export declare const WS_LOGGER_CATEGORY: {
+    category: string;
+};
+export declare const WS_BASE_URL_MAP: Record<APIMarket, Record<'live' | 'demo', Record<'public' | 'private' | 'business', string>>>;
+export declare const WS_KEY_MAP: {
+    /**
+     * Public WS connection for OKX Global (www.okx.com), does not require auth.
+     */
+    readonly prodPublic: "prodPublic";
+    /**
+     * Private WS connection for OKX Global (www.okx.com), requires auth.
+     */
+    readonly prodPrivate: "prodPrivate";
+    /**
+     * Business WS connection for OKX Global (www.okx.com), sometimes requires auth.
+     */
+    readonly prodBusiness: "prodBusiness";
+    /**
+     * Public DEMO WS connection for OKX Global (www.okx.com), does not require auth.
+     */
+    readonly prodDemoPublic: "prodDemoPublic";
+    /**
+     * Private DEMO WS connection for OKX Global (www.okx.com), requires auth.
+     */
+    readonly prodDemoPrivate: "prodDemoPrivate";
+    /**
+     * Business DEMO WS connection for OKX Global (www.okx.com), sometimes requires auth.
+     */
+    readonly prodDemoBusiness: "prodDemoBusiness";
+    /**
+     * Public WS connection for OKX EEA (my.okx.com), does not require auth.
+     */
+    readonly eeaLivePublic: "eeaLivePublic";
+    /**
+     * Private WS connection for OKX EEA (my.okx.com), requires auth.
+     */
+    readonly eeaLivePrivate: "eeaLivePrivate";
+    /**
+     * Business WS connection for OKX EEA (my.okx.com), sometimes requires auth.
+     */
+    readonly eeaLiveBusiness: "eeaLiveBusiness";
+    /**
+     * Public DEMO WS connection for OKX EEA (my.okx.com), does not require auth.
+     */
+    readonly eeaDemoPublic: "eeaDemoPublic";
+    /**
+     * Private DEMO WS connection for OKX EEA (my.okx.com), requires auth.
+     */
+    readonly eeaDemoPrivate: "eeaDemoPrivate";
+    /**
+     * Business DEMO WS connection for OKX EEA (my.okx.com), sometimes requires auth.
+     */
+    readonly eeaDemoBusiness: "eeaDemoBusiness";
+    /**
+     * Public WS connection for OKX US (app.okx.com), does not require auth.
+     */
+    readonly usLivePublic: "usLivePublic";
+    /**
+     * Private WS connection for OKX US (app.okx.com), requires auth.
+     */
+    readonly usLivePrivate: "usLivePrivate";
+    /**
+     * Business WS connection for OKX US (app.okx.com), sometimes requires auth.
+     */
+    readonly usLiveBusiness: "usLiveBusiness";
+    readonly usDemoPublic: "usDemoPublic";
+    readonly usDemoPrivate: "usDemoPrivate";
+    readonly usDemoBusiness: "usDemoBusiness";
+};
+/** This is used to differentiate between each of the available websocket streams (as bybit has multiple websockets) */
+export type WsKey = (typeof WS_KEY_MAP)[keyof typeof WS_KEY_MAP];
+export declare const PRIVATE_WS_KEYS: WsKey[];
+export declare const PUBLIC_WS_KEYS: WsKey[];
+/**
+ * Returns the DEMO connection WsKey for the provided WsKey
+ */
+export declare function getDemoWsKey(wsKey: WsKey): WsKey;
+/** Determine which WsKey (ws connection) to route an event to */
+export declare function getWsKeyForTopicChannel(market: APIMarket, channel: WsChannel, isPrivate?: boolean): WsKey;
+/**
+ * Returns wsKey for product group. Demo resolution is handled in URL lookup function, separately.
+ */
+export declare function getWsKeyForMarket(market: APIMarket, isPrivate: boolean, isBusinessChannel: boolean): WsKey;
+export declare function requiresWSAPITag(operation: WSAPIOperation, wsKey: WsKey): boolean;
+export declare function validateWSAPITag(request: WSAPIRequestOKX<any>, wsKey: WsKey): void;
+/**
+ * Maps a WS key back to a WS URL. Resolves to demo wsKey automatically, if configured.
+ */
+export declare function getWsUrlForWsKey(wsKey: WsKey, wsClientOptions: WebsocketClientOptions, logger: typeof DefaultLogger): string;
+export declare function getMaxTopicsPerSubscribeEventForMarket(market: APIMarket): number | null;
+export declare function isWsPong(event: unknown): boolean;
+export declare const WS_EVENT_CODE_ENUM: {
+    OK: string;
+    LOGIN_FAILED: string;
+    LOGIN_PARTIALLY_FAILED: string;
+};
+/**
+ * #305: ws.terminate() is undefined in browsers.
+ * This only works in node.js, not in browsers.
+ * Does nothing if `ws` is undefined. Does nothing in browsers.
+ */
+export declare function safeTerminateWs(ws?: WebSocket | any, fallbackToClose?: boolean): boolean;
+/**
+ * Normalised internal format for a request (subscribe/unsubscribe/etc) on a topic, with optional parameters.
+ *
+ * - Topic: the topic this event is for
+ * - Payload: the parameters to include, optional. E.g. auth requires key + sign. Some topics allow configurable parameters.
+ */
+export interface WsTopicRequest<TWSTopic extends string = string, TWSPayload = unknown> {
+    topic: TWSTopic;
+    payload?: TWSPayload;
+}
+/**
+ * Conveniently allow users to request a topic either as string topics or objects (containing string topic + params)
+ */
+export type WsTopicRequestOrStringTopic<TWSTopic extends string, TWSPayload = unknown> = WsTopicRequest<TWSTopic, TWSPayload> | string;
+/**
+ * Users can conveniently pass topics as strings or objects (object has topic name + optional params).
+ *
+ * This method normalises topics into objects (object has topic name + optional params).
+ */
+export declare function getNormalisedTopicRequests(wsTopicRequests: WsTopicRequestOrStringTopic<string>[]): WsTopicRequest<string>[];
+/**
+ * WebSocket.ping() is not available in browsers. This is a simple check used to
+ * disable heartbeats in browers, for exchanges that use native WebSocket ping/pong frames.
+ */
+export declare function isWSPingFrameAvailable(): boolean;
+/**
+ * WebSocket.pong() is not available in browsers. This is a simple check used to
+ * disable heartbeats in browers, for exchanges that use native WebSocket ping/pong frames.
+ */
+export declare function isWSPongFrameAvailable(): boolean;
+/**
+ * WS API promises are stored using a primary key. This key is constructed using
+ * properties found in every request & reply.
+ */
+export declare function getPromiseRefForWSAPIRequest(requestEvent: WSAPIRequestOKX<unknown>): string;