@huskly/ibkr-client 2.4.3 → 2.7.1

package/dist/ibkr/ibkrClient.js

@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
 import { ASSET_CLASS_LABELS, toNullableNumber, toNumber } from "../helpers.js";
 import { normalizeOptionContract, parseOsiOptionSymbol } from "./optionContract.js";
+import { normalizeEquityContract } from "./equityContract.js";
 import { normalizeDerivativeContract, normalizeDerivativeDataAvailability, } from "./derivativeContract.js";
 import { IbkrRequestScheduler, } from "./requestScheduler.js";
 // `ibkr-client`'s published ESM build is broken: its `import` condition points
@@ -572,6 +573,39 @@ export class IbkrClient {
                 : [],
         };
     }
+    async previewEquityOrder(request) {
+        this.assertOpen();
+        this.validateEquityOrderFields(request);
+        return this.withTradingMutation(request.accountId, "IBKR brokerage session is not safely authenticated for What-If", async (diagnostics) => {
+            await this.req({
+                path: "iserver/marketdata/snapshot",
+                params: { conids: String(request.contract.conid), fields: "6509" },
+            });
+            const response = await this.singleAttemptRequest({
+                path: `iserver/account/${request.accountId}/orders/whatif`,
+                method: "POST",
+                data: { orders: [this.equityOrderTicket(request)] },
+            });
+            return this.normalizeComboPreview(request.accountId, diagnostics, response);
+        });
+    }
+    async submitEquityOrder(request) {
+        this.assertOpen();
+        this.validateEquityOrderFields(request);
+        if (!request.clientOrderId.trim() || request.clientOrderId.length > 64) {
+            throw new Error("Client order ID must contain 1 to 64 characters");
+        }
+        return this.withTradingMutation(request.accountId, "IBKR brokerage session is not safely authenticated for submission", async () => {
+            const response = await this.singleAttemptRequest({
+                path: `iserver/account/${request.accountId}/orders`,
+                method: "POST",
+                data: {
+                    orders: [{ ...this.equityOrderTicket(request), cOID: request.clientOrderId }],
+                },
+            });
+            return this.normalizeOrderSubmission(response, request.clientOrderId);
+        });
+    }
     async previewDerivativeCombo(request) {
         this.assertOpen();
         this.validateComboPreview(request);
@@ -1578,6 +1612,15 @@ export class IbkrClient {
             await this.wait(Math.min(pollMs, Math.max(0, deadline - this.now())));
         }
     }
+    getEquityOrderStatus(accountId, orderId) {
+        return this.getDerivativeOrderStatus(accountId, orderId);
+    }
+    findEquityOrder(input) {
+        return this.findDerivativeOrder(input);
+    }
+    cancelEquityOrder(input) {
+        return this.cancelDerivativeOrder({ ...input, assetClass: "STK" });
+    }
     async cancelDerivativeOrder(input) {
         this.assertOpen();
         if (!input.accountId.trim() || !input.orderId.trim()) {
@@ -1979,6 +2022,72 @@ export class IbkrClient {
         return quotes;
     }
     /** Resolve equity/ETF symbols to IBKR contracts via `trsrv/stocks`. */
+    /** Resolve one exact SMART-routed US stock or ETF contract. */
+    async resolveEquityContract(symbol) {
+        this.assertOpen();
+        const requestedSymbol = symbol.trim().toUpperCase();
+        if (!requestedSymbol || /[\r\n\t]/.test(symbol)) {
+            throw new Error("Equity contract resolution requires a usable symbol");
+        }
+        const response = await this.req({
+            path: "trsrv/stocks",
+            params: { symbols: requestedSymbol },
+        });
+        if (!isUnknownRecord(response)) {
+            throw new Error("IBKR returned incomplete exact US equity search evidence");
+        }
+        const rawListings = response[requestedSymbol];
+        if (!Array.isArray(rawListings)) {
+            throw new Error("IBKR returned no exact US equity listing evidence");
+        }
+        const byConid = new Map();
+        let conflicting = false;
+        for (const rawListing of rawListings) {
+            if (!isUnknownRecord(rawListing) || rawListing["assetClass"] !== "STK")
+                continue;
+            const contracts = rawListing["contracts"];
+            if (!Array.isArray(contracts))
+                continue;
+            for (const rawContract of contracts) {
+                if (!isUnknownRecord(rawContract) || rawContract["isUS"] !== true)
+                    continue;
+                const conid = rawContract["conid"];
+                const primaryExchange = this.trimmedString(rawContract["exchange"])?.toUpperCase();
+                if (!Number.isSafeInteger(conid) || conid <= 0 || !primaryExchange)
+                    continue;
+                const previous = byConid.get(conid);
+                if (previous !== undefined && previous !== primaryExchange)
+                    conflicting = true;
+                byConid.set(conid, primaryExchange);
+            }
+        }
+        if (conflicting || byConid.size !== 1) {
+            throw new Error("IBKR did not return one exact US equity listing");
+        }
+        const [candidate] = byConid;
+        if (candidate === undefined)
+            throw new Error("IBKR returned no exact US equity listing");
+        const [conid, primaryExchange] = candidate;
+        const evidence = this.contractReferenceEvidence(conid, await this.readContractReference(conid));
+        const validExchanges = evidence.validExchanges
+            ?.split(",")
+            .map((value) => value.trim().toUpperCase())
+            .filter(Boolean) ?? [];
+        const contract = normalizeEquityContract({
+            conid: evidence.conid,
+            assetClass: evidence.instrumentType?.toUpperCase(),
+            symbol: evidence.symbol,
+            exchange: evidence.exchange,
+            primaryExchange,
+            currency: evidence.currency,
+        });
+        if (contract?.conid !== conid ||
+            contract.symbol !== requestedSymbol ||
+            !validExchanges.includes("SMART")) {
+            throw new Error("IBKR equity contract details are incomplete or conflicting");
+        }
+        return contract;
+    }
     async searchInstruments(symbol, projection = "symbol-search") {
         this.assertOpen();
         if (projection !== "symbol-search" && projection !== "search") {
@@ -2439,6 +2548,44 @@ export class IbkrClient {
             return false;
         }
     }
+    validateEquityOrderFields(request) {
+        if (!request.accountId.trim())
+            throw new Error("An explicit IBKR account ID is required");
+        if (normalizeEquityContract(request.contract) === null) {
+            throw new Error("Equity order requires one exact US equity contract");
+        }
+        const fields = request;
+        if (fields["side"] !== "BUY" && fields["side"] !== "SELL") {
+            throw new Error("Equity order side must be BUY or SELL");
+        }
+        if (!Number.isSafeInteger(fields["quantity"]) || fields["quantity"] <= 0) {
+            throw new Error("Equity order quantity must be a positive integer");
+        }
+        if (fields["orderType"] !== "LMT" ||
+            typeof fields["limit"] !== "number" ||
+            !Number.isFinite(fields["limit"]) ||
+            fields["limit"] <= 0) {
+            throw new Error("Equity LIMIT order requires a positive limit price");
+        }
+        if (fields["tif"] !== "DAY" && fields["tif"] !== "GTC") {
+            throw new Error("Equity order TIF must be DAY or GTC");
+        }
+        if (fields["session"] !== "REGULAR" && fields["session"] !== "OVERNIGHT") {
+            throw new Error("Equity order session must be REGULAR or OVERNIGHT");
+        }
+    }
+    equityOrderTicket(request) {
+        return {
+            acctId: request.accountId,
+            conid: request.contract.conid,
+            orderType: "LMT",
+            side: request.side,
+            price: request.limit,
+            tif: request.tif,
+            quantity: request.quantity,
+            outsideRTH: request.session === "OVERNIGHT",
+        };
+    }
     validateSingleOrder(request) {
         this.validateSingleOrderFields(request);
         const identityFields = request;
@@ -2489,7 +2636,7 @@ export class IbkrClient {
         }
     }
     cmeOperatorMetadata(assetClass, input) {
-        if (assetClass === "OPT")
+        if (assetClass !== "FOP")
             return {};
         if (!input.extOperator?.trim() || input.manualIndicator === undefined) {
             throw new Error(`${assetClass} orders require exact CME operator metadata`);