@jsnw/kalshi-client 0.0.1

package/dist/index.mjs

@@ -0,0 +1,652 @@
+import { constants, createSign } from "node:crypto";
+import { z } from "zod";
+import { v4 } from "uuid";
+import { WebSocket } from "ws";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+//#region src/request-signer.ts
+var RequestSigner = class {
+	privkey;
+	/**
+	* @param {RequestSignerOptions} options
+	*/
+	constructor(options) {
+		this.privkey = options.privateKey;
+	}
+	/**
+	* @param {SignatureParameters} params
+	* @return {string}
+	*/
+	getSignature({ timestamp, httpMethod, path }) {
+		const text = `${(timestamp instanceof Date ? timestamp.getTime() : timestamp).toString()}${httpMethod.toUpperCase()}${path.split("?")[0].replace(/\/+$/, "")}`;
+		const sign = createSign("RSA-SHA256");
+		sign.update(text);
+		sign.end();
+		return sign.sign({
+			key: this.privkey,
+			padding: constants.RSA_PKCS1_PSS_PADDING,
+			saltLength: constants.RSA_PSS_SALTLEN_DIGEST
+		}).toString("base64");
+	}
+};
+//#endregion
+//#region src/credentials-provider.ts
+var InMemoryCredentialsProvider = class {
+	accessKey;
+	privateKey;
+	signer;
+	/**
+	* @param {InMemoryCredentialsProviderOptions} options
+	*/
+	constructor(options) {
+		this.accessKey = options.accessKey;
+		this.privateKey = options.privateKey;
+		this.signer = new RequestSigner({ privateKey: this.privateKey });
+	}
+	/**
+	* @param {string} accessKey
+	*/
+	setAccessKey(accessKey) {
+		if (this.accessKey === accessKey) return;
+		this.accessKey = accessKey;
+	}
+	/**
+	* @param {string} privateKey
+	*/
+	setPrivateKey(privateKey) {
+		if (this.privateKey === privateKey) return;
+		this.privateKey = privateKey;
+		this.signer = new RequestSigner({ privateKey });
+	}
+	/**
+	* @return {string}
+	*/
+	getAccessKey() {
+		return this.accessKey;
+	}
+	/**
+	* @param {SignatureParameters} options
+	* @return {string}
+	*/
+	getSignature(options) {
+		return this.signer.getSignature(options);
+	}
+};
+//#endregion
+//#region src/schemas/primitives.ts
+const primitives$fixedPointSchema = z.string().regex(/^\d{1,14}\.\d{2,8}$/);
+const primitives$orderSideSchema = z.enum(["yes", "no"]);
+const primitives$bookSideSchema = z.enum(["bid", "ask"]);
+const primitives$orderActionSchema = z.enum(["buy", "sell"]);
+//#endregion
+//#region src/schemas/orders.ts
+const orders$orderStatusSchema = z.enum([
+	"resting",
+	"canceled",
+	"executed"
+]);
+const orders$orderTypeSchema = z.enum(["limit", "market"]);
+const orders$selfTradePreventionTypeSchema = z.enum(["taker_at_cross", "maker"]);
+const orders$orderDetailedSchema = z.object({
+	order_id: z.uuid(),
+	user_id: z.uuid(),
+	subaccount_number: z.number().min(0).max(32).default(0),
+	order_group_id: z.uuid().nullable().optional(),
+	exchange_index: z.number().min(0).default(0),
+	client_order_id: z.string(),
+	ticker: z.string(),
+	outcome_side: primitives$orderSideSchema,
+	book_side: primitives$bookSideSchema,
+	type: orders$orderTypeSchema,
+	status: orders$orderStatusSchema,
+	yes_price_dollars: primitives$fixedPointSchema,
+	no_price_dollars: primitives$fixedPointSchema,
+	fill_count_fp: primitives$fixedPointSchema,
+	remaining_count_fp: primitives$fixedPointSchema,
+	initial_count_fp: primitives$fixedPointSchema,
+	taker_fill_cost_dollars: primitives$fixedPointSchema,
+	maker_fill_cost_dollars: primitives$fixedPointSchema,
+	taker_fees_dollars: primitives$fixedPointSchema,
+	maker_fees_dollars: primitives$fixedPointSchema,
+	self_trade_prevention_type: orders$selfTradePreventionTypeSchema.nullable().optional(),
+	cancel_order_on_pause: z.boolean(),
+	created_time: z.iso.datetime(),
+	expiration_time: z.iso.datetime().nullable().optional(),
+	last_update_time: z.iso.datetime().nullable().optional()
+});
+const orders$orderWsSchema = orders$orderDetailedSchema.omit({
+	exchange_index: true,
+	type: true,
+	no_price_dollars: true,
+	cancel_order_on_pause: true
+}).extend({
+	side: primitives$orderSideSchema,
+	created_ts_ms: z.number().positive(),
+	last_updated_ts_ms: z.number().positive().optional(),
+	expiration_ts_ms: z.number().positive().optional()
+});
+//#endregion
+//#region src/consts.ts
+const KALSHI_WS_URL = {
+	"development": "wss://external-api-ws.demo.kalshi.co",
+	"production": "wss://external-api-ws.kalshi.com"
+};
+//#endregion
+//#region src/typed-emitter.ts
+var TypedEmitter = class {
+	listeners = /* @__PURE__ */ new Map();
+	wrappers = /* @__PURE__ */ new WeakMap();
+	on(event, listener) {
+		if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
+		this.listeners.get(event).add(listener);
+	}
+	once(event, listener) {
+		const wrapper = (...args) => {
+			listener(...args);
+			this.off(event, listener);
+		};
+		this.wrappers.set(listener, wrapper);
+		this.on(event, wrapper);
+	}
+	off(event, listener) {
+		const originalFn = this.wrappers.get(listener) || listener;
+		this.listeners.get(event)?.delete(originalFn);
+		this.wrappers.delete(listener);
+	}
+	emit(event, ...args) {
+		this.listeners.get(event)?.forEach((fn) => fn(...args));
+	}
+	removeListeners(event) {
+		this.listeners.delete(event);
+	}
+	removeAllListeners() {
+		this.listeners.clear();
+	}
+	listenersCount(event) {
+		if (event !== void 0) return this.listeners.get(event)?.size || 0;
+		let acc = 0;
+		for (const set of this.listeners.values()) acc += set.size;
+		return acc;
+	}
+};
+//#endregion
+//#region src/defer.ts
+/**
+* @template T
+* @return {DeferredPromise<T>}
+*/
+function defer() {
+	let resolve, reject;
+	return {
+		promise: new Promise((res, rej) => {
+			resolve = res;
+			reject = rej;
+		}),
+		resolve,
+		reject
+	};
+}
+//#endregion
+//#region src/ws-wrapper/errors.ts
+var WsWrapperError = class extends Error {};
+var NotConnectedError = class extends WsWrapperError {};
+var InvalidStateError = class extends WsWrapperError {};
+//#endregion
+//#region src/random-int.ts
+/**
+* Generates a random integer between min (inclusive) and max (inclusive)
+* @param {number} min - The minimum value (inclusive)
+* @param {number} max - The maximum value (inclusive)
+* @returns {number} A random integer between min and max
+*/
+function randomInt(min, max) {
+	return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+//#endregion
+//#region src/ws-wrapper/ws-wrapper.ts
+var WsWrapper = class extends TypedEmitter {
+	wsAddress;
+	agent;
+	connectHeaders;
+	reconnectStrategy;
+	state = "idle";
+	openDefer = null;
+	closeDefer = null;
+	reconnectAbort = null;
+	ws = null;
+	closeRequested = false;
+	reconnectAttempt = 0;
+	lastError = null;
+	/**
+	* @param {WsWrapperOptions} options
+	*/
+	constructor(options) {
+		super();
+		this.wsAddress = options.address;
+		this.agent = options.agent;
+		this.connectHeaders = options.headers;
+		this.reconnectStrategy = options.reconnect;
+	}
+	/**
+	* @return {Promise<void>}
+	*/
+	open() {
+		switch (this.state) {
+			case "idle":
+				this.state = "connecting";
+				this.openDefer = defer();
+				this.createWs();
+				return this.openDefer.promise;
+			case "connecting":
+			case "reconnecting": return this.openDefer.promise;
+			case "connected": return Promise.resolve();
+			case "closing": return Promise.reject(/* @__PURE__ */ new Error("Cannot reopen WS connection while it's still closing"));
+			default:
+				const _exhaustive = this.state;
+				throw new Error(`Unreachable: ${_exhaustive}`);
+		}
+	}
+	/**
+	* @param {BufferLike} data
+	* @return {Promise<void>}
+	*/
+	send(data) {
+		return new Promise((resolve, reject) => {
+			if (this.state !== "connected") return reject(new NotConnectedError());
+			if (!this.ws) return reject(new InvalidStateError());
+			this.ws.send(data, (err) => {
+				if (err) return reject(err);
+				return resolve();
+			});
+		});
+	}
+	/**
+	* @return {Promise<void>}
+	*/
+	close() {
+		switch (this.state) {
+			case "idle": return Promise.resolve();
+			case "connected":
+			case "connecting":
+			case "reconnecting":
+				this.state = "closing";
+				this.closeRequested = true;
+				this.closeDefer = defer();
+				this.ws?.close();
+				this.reconnectAbort?.abort();
+				return this.closeDefer.promise;
+			case "closing": return this.closeDefer.promise;
+			default:
+				const _exhaustive = this.state;
+				throw new Error(`Unreachable: ${_exhaustive}`);
+		}
+	}
+	createWs() {
+		this.ws = new WebSocket(this.wsAddress, {
+			autoPong: true,
+			headers: this.getConnectHeaders(),
+			agent: this.agent
+		});
+		this.ws.on("open", this.handleOpen);
+		this.ws.on("message", this.handleMessage);
+		this.ws.on("error", this.handleError);
+		this.ws.on("close", this.handleClose);
+	}
+	/**
+	* @return {Record<string, string>}
+	* @private
+	*/
+	getConnectHeaders() {
+		if (!this.connectHeaders) return {};
+		if (typeof this.connectHeaders === "function") return this.connectHeaders();
+		return this.connectHeaders;
+	}
+	/**
+	* @return {number | false}
+	* @private
+	*/
+	getReconnectDelay() {
+		const attempt = this.reconnectAttempt;
+		if (this.closeRequested || !this.reconnectStrategy) return false;
+		if (typeof this.reconnectStrategy === "function") return this.reconnectStrategy(attempt);
+		if (typeof this.reconnectStrategy === "object") {
+			if (attempt > this.reconnectStrategy.maxAttempts) return false;
+			if (typeof this.reconnectStrategy.interval === "function") return this.reconnectStrategy.interval(attempt);
+			if (typeof this.reconnectStrategy.interval === "number") return this.reconnectStrategy.interval;
+			if (typeof this.reconnectStrategy.interval === "object" && !Array.isArray(this.reconnectStrategy.interval)) return randomInt(this.reconnectStrategy.interval.min, this.reconnectStrategy.interval.max);
+			if (Array.isArray(this.reconnectStrategy.interval)) {
+				if (this.reconnectStrategy.interval.length === 0) return 0;
+				else if (this.reconnectStrategy.interval.length === 1) return this.reconnectStrategy.interval[0];
+				else if (this.reconnectStrategy.interval.length > 1) return this.reconnectStrategy.interval[(attempt - 1) % this.reconnectStrategy.interval.length];
+			}
+		}
+		return false;
+	}
+	/**
+	* @private
+	*/
+	reset() {
+		this.state = "idle";
+		this.ws?.removeAllListeners();
+		this.openDefer?.reject(this.lastError ?? /* @__PURE__ */ new Error("WS connection closed"));
+		this.closeDefer?.resolve();
+		this.closeRequested = false;
+		this.openDefer = null;
+		this.closeDefer = null;
+		this.ws = null;
+		this.lastError = null;
+		this.reconnectAttempt = 0;
+	}
+	/**
+	*/
+	handleOpen = () => {
+		this.state = "connected";
+		this.openDefer?.resolve();
+		this.openDefer = null;
+		const attempt = this.reconnectAttempt;
+		this.reconnectAttempt = 0;
+		this.emit("ready", attempt > 0);
+	};
+	/**
+	* @param {WebSocket.RawData} data
+	* @param {boolean} isBinary
+	*/
+	handleMessage = (data, isBinary) => {
+		this.emit("message", data, isBinary);
+	};
+	/**
+	* @param {Error} err
+	*/
+	handleError = (err) => {
+		this.lastError = err;
+		this.emit("error", err);
+	};
+	/**
+	* @param {number} code
+	* @param {Buffer} reason
+	*/
+	handleClose = async (code, reason) => {
+		this.reconnectAttempt += 1;
+		const reconnectDelay = this.getReconnectDelay();
+		if (reconnectDelay !== false) {
+			this.state = "reconnecting";
+			this.reconnectAbort = new AbortController();
+			try {
+				await setTimeout$1(Math.max(1, reconnectDelay), void 0, { signal: this.reconnectAbort.signal });
+			} catch (e) {
+				this.reset();
+				this.emit("close");
+				return;
+			}
+			if (this.state !== "reconnecting") return;
+			this.ws?.removeAllListeners();
+			this.ws = null;
+			this.emit("reconnecting", this.reconnectAttempt);
+			this.createWs();
+		} else {
+			this.reset();
+			this.emit("close");
+		}
+	};
+};
+//#endregion
+//#region src/wait-registry/errors.ts
+var TimeoutError = class extends Error {
+	constructor(key) {
+		super(`Timed out waiting for key: ${key.toString()}`);
+		this.name = "TimeoutError";
+	}
+};
+var RegistryClearedError = class extends Error {
+	constructor() {
+		super("Registry cleared");
+		this.name = "RegistryClearedError";
+	}
+};
+//#endregion
+//#region src/wait-registry/wait-registry.ts
+var WaitRegistry = class {
+	storage = /* @__PURE__ */ new Map();
+	add(key, expiresInMs) {
+		if (this.storage.has(key)) throw new TypeError(`Key already exists: ${key.toString()}`);
+		const deferred = defer();
+		const timer = setTimeout(this.rejectOnTimeout.bind(this, key), expiresInMs);
+		timer.unref();
+		this.storage.set(key, {
+			deferred,
+			_timer: timer
+		});
+		return deferred.promise;
+	}
+	resolve(key, value) {
+		const awaiter = this.storage.get(key);
+		if (!awaiter) return;
+		clearTimeout(awaiter._timer);
+		this.storage.delete(key);
+		awaiter.deferred.resolve(value);
+	}
+	reject(key, error) {
+		const awaiter = this.storage.get(key);
+		if (!awaiter) return;
+		clearTimeout(awaiter._timer);
+		this.storage.delete(key);
+		awaiter.deferred.reject(error);
+	}
+	clear(passError) {
+		const error = passError ?? new RegistryClearedError();
+		for (const awaiter of this.storage.values()) {
+			clearTimeout(awaiter._timer);
+			awaiter.deferred.reject(error);
+		}
+		this.storage.clear();
+	}
+	rejectOnTimeout(key) {
+		const awaiter = this.storage.get(key);
+		if (!awaiter) return;
+		this.storage.delete(key);
+		clearTimeout(awaiter._timer);
+		awaiter.deferred.reject(new TimeoutError(key));
+	}
+};
+//#endregion
+//#region src/logging.ts
+const noopLogger = (level, message, context) => {};
+//#endregion
+//#region src/ws/messages.ts
+const wsOkMessageSchema = z.object({
+	id: z.number(),
+	sid: z.number(),
+	type: z.literal("ok"),
+	msg: z.any().optional()
+});
+const wsErrorMessageSchema = z.object({
+	id: z.number(),
+	type: z.literal("error"),
+	msg: z.object({
+		code: z.number(),
+		msg: z.string()
+	})
+});
+const wsSubscribedMessageSchema = z.object({
+	id: z.number(),
+	type: z.literal("subscribed"),
+	msg: z.object({
+		channel: z.string(),
+		sid: z.number()
+	})
+});
+const wsUserOrderMessageSchema = z.object({
+	sid: z.number().positive(),
+	type: z.literal("user_order"),
+	msg: orders$orderWsSchema
+});
+const wsAnyMessageSchema = z.discriminatedUnion("type", [
+	wsOkMessageSchema,
+	wsErrorMessageSchema,
+	wsSubscribedMessageSchema,
+	wsUserOrderMessageSchema
+]);
+//#endregion
+//#region src/ws/errors.ts
+var WsKalshiError = class extends Error {
+	id;
+	code;
+	/**
+	* @param {number} id
+	* @param {number} code
+	* @param {string} message
+	*/
+	constructor(id, code, message) {
+		super(message);
+		this.id = id;
+		this.code = code;
+	}
+};
+//#endregion
+//#region src/ws/ws-client.ts
+var WsClient = class extends TypedEmitter {
+	id;
+	baseURL;
+	credentialsProvider;
+	log;
+	ws;
+	lastMessageId = 0;
+	subscribeAwaiters = new WaitRegistry();
+	/**
+	* @param {WsClientOptions} options
+	*/
+	constructor(options) {
+		super();
+		this.id = options.id ?? v4();
+		this.baseURL = KALSHI_WS_URL[options.environment ?? "development"];
+		this.credentialsProvider = options.credentialsProvider;
+		this.log = options.log ?? noopLogger;
+		const path = "/trade-api/ws/v2", address = `${this.baseURL}${path}`;
+		this.ws = new WsWrapper({
+			...options.wsOptions,
+			address,
+			headers: () => {
+				const timestamp = Date.now();
+				const signature = this.credentialsProvider.getSignature({
+					timestamp,
+					httpMethod: "GET",
+					path
+				});
+				return {
+					"Content-Type": "application/json",
+					"KALSHI-ACCESS-KEY": this.credentialsProvider.getAccessKey(),
+					"KALSHI-ACCESS-SIGNATURE": signature,
+					"KALSHI-ACCESS-TIMESTAMP": timestamp.toString()
+				};
+			}
+		});
+		this.ws.on("ready", this.onReady);
+		this.ws.on("message", this.onMessage);
+		this.ws.on("error", this.onError);
+		this.ws.on("reconnecting", this.onReconnecting);
+		this.ws.on("close", this.onClose);
+	}
+	onReady = async (afterReconnect) => {
+		this.log("debug", "WebSocket connection ready", { afterReconnect });
+		this.emit("ready");
+	};
+	/**
+	* @param {WebSocket.RawData} data
+	* @param {boolean} isBinary
+	* @return {Promise<void>}
+	*/
+	onMessage = async (data, isBinary) => {
+		if (isBinary) {
+			this.log("warn", "invalid incoming message format (=binary)");
+			return;
+		}
+		let jsonData = null;
+		try {
+			jsonData = JSON.parse(data.toString());
+		} catch (e) {
+			this.log("warn", "failed to decode incoming message as JSON string");
+			return;
+		}
+		this.log("debug", "incoming message", { message: jsonData });
+		const { data: msg, error } = wsAnyMessageSchema.safeParse(jsonData);
+		if (error) {
+			this.log("warn", "failed to validate message", {
+				message: jsonData,
+				error
+			});
+			return;
+		}
+		this.processMessage(msg);
+	};
+	/**
+	* @param {number} attempt
+	*/
+	onReconnecting = (attempt) => {
+		this.log("debug", "reconnecting", { attempt });
+		this.emit("reconnect", attempt);
+	};
+	/**
+	* @param {Error} err
+	*/
+	onError = (err) => {
+		this.log("error", "WebSocket error", { err });
+	};
+	/**
+	*/
+	onClose = () => {
+		this.log("debug", "WebSocket connection closed");
+		this.emit("close");
+		this.subscribeAwaiters.clear();
+	};
+	/**
+	* @param {WsAnyMessage} msg
+	* @private
+	*/
+	processMessage(msg) {
+		switch (msg.type) {
+			case "ok":
+				this.subscribeAwaiters.resolve(msg.id, true);
+				break;
+			case "error":
+				this.subscribeAwaiters.reject(msg.id, new WsKalshiError(msg.id, msg.msg.code, msg.msg.msg));
+				break;
+			case "subscribed":
+				this.subscribeAwaiters.resolve(msg.id, true);
+				break;
+		}
+		this.emit("message", msg);
+	}
+};
+//#endregion
+//#region src/ws/common.ts
+const WS_KALSHI_ERRORS = {
+	UNABLE_TO_PROCESS: 1,
+	PARAMS_REQUIRED: 2,
+	CHANNELS_REQUIRED: 3,
+	SUBSCRIPTION_IDS_REQUIRED: 4,
+	UNKNOWN_COMMAND: 5,
+	ALREADY_SUBSCRIBED: 6,
+	UNKNOWN_SUBSCRIPTION_ID: 7,
+	UNKNOWN_CHANNEL_NAME: 8,
+	AUTHENTICATION_REQUIRED: 9,
+	CHANNEL_ERROR: 10,
+	INVALID_PARAMETER: 11,
+	EXACTLY_ONE_SUBSCRIPTION_ID_IS_REQUIRED: 12,
+	UNSUPPORTED_ACTION: 13,
+	MARKET_TICKER_REQUIRED: 14,
+	ACTION_REQUIRED: 15,
+	MARKET_NOT_FOUND: 16,
+	INTERNAL_ERROR: 17,
+	COMMAND_TIMEOUT: 18,
+	SHARD_FACTOR_MUST_BE_GT0: 19,
+	SHARD_FACTOR_IS_REQUIRED: 20,
+	INVALID_SHARD_KEY: 21,
+	SHARD_FACTOR_MUST_BE_LT100: 22,
+	SUBSCRIPTION_BUFFER_OVERFLOW: 25
+};
+const WS_KALSHI_SERVER_ERRORS = [
+	WS_KALSHI_ERRORS.CHANNEL_ERROR,
+	WS_KALSHI_ERRORS.INTERNAL_ERROR,
+	WS_KALSHI_ERRORS.COMMAND_TIMEOUT
+];
+//#endregion
+export { InMemoryCredentialsProvider, RequestSigner, WS_KALSHI_ERRORS, WS_KALSHI_SERVER_ERRORS, WsClient, WsKalshiError, orders$orderDetailedSchema, orders$orderStatusSchema, orders$orderTypeSchema, orders$orderWsSchema, orders$selfTradePreventionTypeSchema, primitives$bookSideSchema, primitives$fixedPointSchema, primitives$orderActionSchema, primitives$orderSideSchema, wsAnyMessageSchema, wsErrorMessageSchema, wsOkMessageSchema, wsSubscribedMessageSchema, wsUserOrderMessageSchema };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@jsnw/kalshi-client",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.0.1",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    "node": {
+      "import": {
+        "default": "./dist/index.mjs",
+        "types": "./dist/index.d.mts"
+      },
+      "require": {
+        "default": "./dist/index.cjs",
+        "types": "./dist/index.d.cts"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "uuid": "^14.0.0",
+    "ws": "^8.21.0",
+    "zod": "^4.4.3"
+  },
+  "optionalDependencies": {
+    "bufferutil": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.4",
+    "@types/ws": "^8.18.1",
+    "nodemon": "^3.1.14",
+    "rimraf": "^6.1.3",
+    "ts-node": "^10.9.2",
+    "tsdown": "^0.22.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "clean": "rimraf ./dist",
+    "build": "tsdown"
+  }
+}