@huskly/ibkr-client 0.11.0 → 0.13.0

package/dist/ibkr/ibkrClient.js

@@ -2,6 +2,7 @@ import { createRequire } from "node:module";
 import { ASSET_CLASS_LABELS, toNumber } from "../helpers.js";
 import { normalizeOptionContract, parseOsiOptionSymbol } from "./optionContract.js";
 import { normalizeDerivativeContract, normalizeDerivativeDataAvailability, } from "./derivativeContract.js";
+import { IbkrRequestScheduler, } from "./requestScheduler.js";
 // `ibkr-client`'s published ESM build is broken: its `import` condition points
 // at files that use extensionless relative imports, which Node's strict ESM
 // resolver rejects. Its CJS build is fine, so we deliberately load that via
@@ -56,9 +57,6 @@ const QUOTE_FIELDS = [
 const OPTION_DISCOVERY_MONTH_CONCURRENCY = 1;
 const OPTION_SECDEF_INFO_BATCH_SIZE = 8;
 const OPTION_MARKETDATA_BATCH_SIZE = 100;
-const READ_ONLY_REQUEST_MAX_RETRIES = 3;
-const REQUEST_RETRY_BASE_DELAY_MS = 250;
-const REQUEST_RETRY_MAX_DELAY_MS = 5_000;
 const DAY_MS = 24 * 60 * 60 * 1000;
 const IBKR_STATUS_FILTERS = {
     CANCELED: "cancelled",
@@ -167,8 +165,19 @@ export class IbkrClient {
     accountIdPromise;
     optionDiscovery = new Map();
     derivativeDiscovery = new Map();
-    constructor(config) {
+    requestScheduler;
+    constructor(config, options = {}) {
         this.raw = new RawIbkrClientCtor(config);
+        this.requestScheduler = new IbkrRequestScheduler({
+            ...options.requestScheduler,
+            now: () => this.now(),
+            sleep: (ms) => this.wait(ms),
+            random: () => this.random(),
+            classifyError: (error) => this.classifyRequestError(error),
+            ...(options.onRequestTelemetry === undefined
+                ? {}
+                : { onTelemetry: options.onRequestTelemetry }),
+        });
     }
     /** Obtain the live session token (idempotent — safe to await repeatedly). */
     init() {
@@ -238,14 +247,13 @@ export class IbkrClient {
         if (!request.clientOrderId.trim() || request.clientOrderId.length > 64) {
             throw new Error("Client order ID must contain 1 to 64 characters");
         }
-        if (!request.extOperator.trim())
-            throw new Error("External operator is required");
+        const cmeOperatorMetadata = this.cmeOperatorMetadata(request.legs[0].contract.assetClass, request);
         const diagnostics = await this.getTradingDiagnostics(request.accountId);
         if (!diagnostics.authenticated || diagnostics.competingSession) {
             throw new Error("IBKR brokerage session is not safely authenticated for submission");
         }
         await this.prepareBrokerageAccount(request.accountId);
-        const response = await this.sendRequest({
+        const response = await this.singleAttemptRequest({
             path: `iserver/account/${request.accountId}/orders`,
             method: "POST",
             data: {
@@ -253,54 +261,226 @@ export class IbkrClient {
                     {
                         ...this.comboOrderTicket(request),
                         cOID: request.clientOrderId,
-                        extOperator: request.extOperator,
-                        manualIndicator: request.manualIndicator,
+                        ...cmeOperatorMetadata,
                     },
                 ],
             },
         });
         return this.normalizeOrderSubmission(response, request.clientOrderId);
     }
+    async submitDerivativeSingleOrder(request) {
+        this.validateSingleOrder(request);
+        const cmeOperatorMetadata = this.cmeOperatorMetadata(request.contract.assetClass, request);
+        const diagnostics = await this.getTradingDiagnostics(request.accountId);
+        if (!diagnostics.authenticated || diagnostics.competingSession) {
+            throw new Error("IBKR brokerage session is not safely authenticated for submission");
+        }
+        await this.prepareBrokerageAccount(request.accountId);
+        const response = await this.singleAttemptRequest({
+            path: `iserver/account/${request.accountId}/orders`,
+            method: "POST",
+            data: {
+                orders: [
+                    {
+                        ...this.singleOrderTicket(request),
+                        ...(request.clientOrderId !== undefined ? { cOID: request.clientOrderId } : {}),
+                        ...(request.parentId !== undefined ? { parentId: request.parentId } : {}),
+                        ...cmeOperatorMetadata,
+                    },
+                ],
+            },
+        });
+        return this.normalizeOrderSubmission(response, request.clientOrderId ?? null);
+    }
+    async submitDerivativeContingentOrders(request) {
+        const { accountId, parent, child } = request;
+        if (!accountId.trim())
+            throw new Error("An explicit IBKR account ID is required");
+        if (parent.accountId !== accountId || child.accountId !== accountId) {
+            throw new Error("Contingent parent and child orders must target the exact same account");
+        }
+        this.validateSingleOrderFields(parent);
+        this.validateSingleOrderFields(child);
+        if (typeof parent.clientOrderId !== "string" ||
+            !parent.clientOrderId.trim() ||
+            parent.clientOrderId.length > 64) {
+            throw new Error("Parent client order ID must contain 1 to 64 characters");
+        }
+        if ("clientOrderId" in child || "parentId" in child) {
+            throw new Error("Contingent child identity is derived from the parent order");
+        }
+        const parentMetadata = this.cmeOperatorMetadata(parent.contract.assetClass, parent);
+        const childMetadata = this.cmeOperatorMetadata(child.contract.assetClass, child);
+        const diagnostics = await this.getTradingDiagnostics(accountId);
+        if (!diagnostics.authenticated || diagnostics.competingSession) {
+            throw new Error("IBKR brokerage session is not safely authenticated for submission");
+        }
+        await this.prepareBrokerageAccount(accountId);
+        const response = await this.singleAttemptRequest({
+            path: `iserver/account/${accountId}/orders`,
+            method: "POST",
+            data: {
+                orders: [
+                    {
+                        ...this.singleOrderTicket(parent),
+                        cOID: parent.clientOrderId,
+                        ...parentMetadata,
+                    },
+                    {
+                        ...this.singleOrderTicket(child),
+                        parentId: parent.clientOrderId,
+                        ...childMetadata,
+                    },
+                ],
+            },
+        });
+        return this.normalizeMultiOrderSubmission(response, parent.clientOrderId);
+    }
     async acknowledgeOrderWarning(input) {
         if (!input.replyId.trim())
             throw new Error("An exact warning reply ID is required");
-        const response = await this.sendRequest({
+        const response = await this.singleAttemptRequest({
             path: `iserver/reply/${encodeURIComponent(input.replyId)}`,
             method: "POST",
             data: { confirmed: true },
         });
         return this.normalizeOrderSubmission(response, null);
     }
+    async acknowledgeContingentOrderWarning(input) {
+        const confirmed = input.confirmed;
+        if (confirmed !== true) {
+            throw new Error("Order warning confirmation must be true");
+        }
+        if (!input.continuation.replyId.trim()) {
+            throw new Error("An exact warning reply ID is required");
+        }
+        if (!input.continuation.parentClientOrderId.trim()) {
+            throw new Error("An exact parent client order ID is required");
+        }
+        const response = await this.singleAttemptRequest({
+            path: `iserver/reply/${encodeURIComponent(input.continuation.replyId)}`,
+            method: "POST",
+            data: { confirmed: true },
+        });
+        return this.normalizeMultiOrderSubmission(response, input.continuation.parentClientOrderId);
+    }
     async getDerivativeOrderStatus(accountId, orderId) {
         if (!accountId.trim() || !orderId.trim()) {
             throw new Error("Exact account and order IDs are required");
         }
         await this.prepareBrokerageAccount(accountId);
+        const order = await this.req({
+            path: `iserver/account/order/status/${encodeURIComponent(orderId)}`,
+        });
+        if (String(order.order_id ?? order.orderId ?? "") !== orderId) {
+            throw new Error(`IBKR response does not match the requested order ${orderId}`);
+        }
+        if ((order.account ?? order.acct) !== accountId) {
+            throw new Error(`IBKR order ${orderId} does not belong to the requested account`);
+        }
+        const lifecycle = this.normalizeDerivativeOrderLifecycle(accountId, orderId, order);
+        if (lifecycle.status === "UNKNOWN") {
+            throw new Error(`IBKR order ${orderId} returned an unrecognized status`);
+        }
+        return lifecycle;
+    }
+    async findDerivativeOrder(input) {
+        if (!input.accountId.trim())
+            throw new Error("An exact account ID is required");
+        const identity = input.orderId ?? input.clientOrderId;
+        if (!identity.trim())
+            throw new Error("An exact broker or client order ID is required");
+        if (input.orderId !== undefined) {
+            return this.getDerivativeOrderStatus(input.accountId, input.orderId);
+        }
+        await this.prepareBrokerageAccount(input.accountId);
         const response = await this.req({
             path: "iserver/account/orders",
-            params: { force: true, accountId },
+            params: { force: true, accountId: input.accountId },
+        });
+        const order = response.orders?.find((candidate) => {
+            if (!this.orderBelongsToAccount(candidate, input.accountId))
+                return false;
+            return (candidate.cOID ?? candidate.order_ref) === input.clientOrderId;
         });
-        const order = response.orders?.find((candidate) => String(candidate.order_id ?? candidate.orderId) === orderId);
         if (order === undefined)
-            throw new Error(`IBKR order ${orderId} was not found`);
-        if (!this.orderBelongsToAccount(order, accountId)) {
-            throw new Error(`IBKR order ${orderId} does not belong to the requested account`);
+            throw new Error(`IBKR order ${identity} was not found`);
+        const orderId = order.order_id ?? order.orderId;
+        if (orderId === undefined) {
+            throw new Error(`IBKR order ${identity} did not include a broker order ID`);
+        }
+        return this.getDerivativeOrderStatus(input.accountId, String(orderId));
+    }
+    async getDerivativeExecutions(input) {
+        if (!input.accountId.trim())
+            throw new Error("An exact account ID is required");
+        if (input.days !== undefined &&
+            (!Number.isSafeInteger(input.days) || input.days < 1 || input.days > 7)) {
+            throw new Error("Execution history days must be an integer from 1 through 7");
+        }
+        if (input.orderId !== undefined && !input.orderId.trim()) {
+            throw new Error("Broker order ID cannot be empty");
+        }
+        if (input.clientOrderId !== undefined && !input.clientOrderId.trim()) {
+            throw new Error("Client order ID cannot be empty");
+        }
+        await this.prepareBrokerageAccount(input.accountId);
+        const response = await this.req({
+            path: "iserver/account/trades",
+            ...(input.days === undefined ? {} : { params: { days: input.days } }),
+        });
+        return response
+            .filter((trade) => (trade.account ?? trade.accountCode) === input.accountId)
+            .filter((trade) => input.orderId === undefined || String(trade.order_id) === input.orderId)
+            .filter((trade) => input.clientOrderId === undefined || trade.order_ref === input.clientOrderId)
+            .flatMap((trade) => {
+            const execution = this.normalizeDerivativeExecution(input.accountId, trade);
+            return execution === undefined ? [] : [execution];
+        });
+    }
+    async reconcileDerivativeComboExecution(request) {
+        this.validateReconciliationRequest(request);
+        const lifecycle = await this.getDerivativeOrderStatus(request.accountId, request.orderId);
+        const deadline = this.now() + (request.timeoutMs ?? 30_000);
+        const pollMs = request.pollMs ?? 1_000;
+        for (;;) {
+            const executions = await this.getDerivativeExecutions({
+                accountId: request.accountId,
+                clientOrderId: request.clientOrderId,
+                days: 1,
+            });
+            const result = this.evaluateDerivativeReconciliation(request, lifecycle, executions);
+            if (result.state !== "PENDING")
+                return result;
+            if (!this.isTerminalDerivativeStatus(lifecycle.status))
+                return result;
+            if (this.now() >= deadline) {
+                return {
+                    ...result,
+                    state: "RECOVERY_REQUIRED",
+                    reason: result.reason ?? "Terminal order is missing expected execution evidence",
+                };
+            }
+            await this.wait(Math.min(pollMs, Math.max(0, deadline - this.now())));
         }
-        return this.normalizeDerivativeOrderLifecycle(accountId, orderId, order);
     }
     async cancelDerivativeOrder(input) {
-        if (!input.accountId.trim() || !input.orderId.trim() || !input.extOperator.trim()) {
-            throw new Error("Exact account, order, and external operator are required");
+        if (!input.accountId.trim() || !input.orderId.trim()) {
+            throw new Error("Exact account and order IDs are required");
         }
+        const cmeOperatorMetadata = this.cmeOperatorMetadata(input.assetClass, input);
         await this.prepareBrokerageAccount(input.accountId);
-        await this.sendRequest({
+        const response = await this.singleAttemptRequest({
             path: `iserver/account/${input.accountId}/order/${encodeURIComponent(input.orderId)}`,
             method: "DELETE",
-            params: {
-                extOperator: input.extOperator,
-                manualIndicator: input.manualIndicator,
-            },
+            ...(Object.keys(cmeOperatorMetadata).length > 0 ? { params: cmeOperatorMetadata } : {}),
         });
+        return {
+            state: "requested",
+            accountId: input.accountId,
+            orderId: input.orderId,
+            message: this.trimmedString(response.msg),
+        };
     }
     async getAccountId() {
         this.accountIdPromise ??= (async () => {
@@ -522,6 +702,66 @@ export class IbkrClient {
             }
         }
     }
+    validateSingleOrder(request) {
+        this.validateSingleOrderFields(request);
+        const identityFields = request;
+        const hasClientOrderId = "clientOrderId" in identityFields;
+        const hasParentId = "parentId" in identityFields;
+        if (hasClientOrderId && typeof identityFields.clientOrderId !== "string") {
+            throw new Error("Client order ID must be a string");
+        }
+        if (hasParentId && typeof identityFields.parentId !== "string") {
+            throw new Error("Parent order ID must be a string");
+        }
+        const clientOrderId = hasClientOrderId ? identityFields.clientOrderId : undefined;
+        const parentId = hasParentId ? identityFields.parentId : undefined;
+        if (clientOrderId !== undefined && parentId !== undefined) {
+            throw new Error("Attached child orders must not include a client order ID");
+        }
+        const identity = clientOrderId ?? parentId;
+        if (!identity?.trim() || identity.length > 64) {
+            throw new Error(parentId === undefined
+                ? "Client order ID must contain 1 to 64 characters"
+                : "Parent order ID must contain 1 to 64 characters");
+        }
+    }
+    validateSingleOrderFields(request) {
+        if (!request.accountId.trim())
+            throw new Error("An explicit IBKR account ID is required");
+        const orderType = request.orderType;
+        if (orderType !== "LMT" && orderType !== "STP") {
+            throw new Error("Order type must be LMT or STP");
+        }
+        if (!Number.isSafeInteger(request.quantity) || request.quantity <= 0) {
+            throw new Error("Order quantity must be a positive integer");
+        }
+        if (!Number.isSafeInteger(request.contract.conid) || request.contract.conid <= 0) {
+            throw new Error("Order contract has an invalid IBKR conid");
+        }
+        if (request.orderType === "LMT") {
+            const limit = request.limit;
+            if (typeof limit !== "number" || !Number.isFinite(limit) || limit <= 0) {
+                throw new Error("LIMIT order requires a positive limit price");
+            }
+        }
+        if (request.orderType === "STP") {
+            const stopPrice = request.stopPrice;
+            if (typeof stopPrice !== "number" || !Number.isFinite(stopPrice) || stopPrice <= 0) {
+                throw new Error("STOP order requires a positive stop price");
+            }
+        }
+    }
+    cmeOperatorMetadata(assetClass, input) {
+        if (assetClass === "OPT")
+            return {};
+        if (!input.extOperator?.trim() || input.manualIndicator === undefined) {
+            throw new Error(`${assetClass} orders require exact CME operator metadata`);
+        }
+        return {
+            extOperator: input.extOperator,
+            manualIndicator: input.manualIndicator,
+        };
+    }
     comboOrderTicket(request) {
         const exchange = request.legs[0].contract.exchange;
         const spreadConid = exchange === "SMART" ? "28812380" : `28812380@${exchange}`;
@@ -538,61 +778,304 @@ export class IbkrClient {
             outsideRTH: request.session === "OVERNIGHT",
         };
     }
+    singleOrderTicket(request) {
+        return {
+            acctId: request.accountId,
+            conid: request.contract.conid,
+            orderType: request.orderType,
+            side: request.side,
+            price: request.orderType === "LMT" ? request.limit : request.stopPrice,
+            tif: request.tif,
+            quantity: request.quantity,
+            outsideRTH: request.session === "OVERNIGHT",
+        };
+    }
     normalizeOrderSubmission(response, clientOrderId) {
-        const items = Array.isArray(response) ? response : [response];
-        const warnings = items.flatMap((item) => {
-            if (!("id" in item) || typeof item.id !== "string")
-                return [];
-            const messageIds = item.messageIds?.filter((value) => typeof value === "string") ?? [];
-            return [
-                {
-                    replyId: item.id,
-                    messages: item.message?.filter((value) => typeof value === "string") ?? [],
-                    messageIds,
-                    known: messageIds.length > 0 && messageIds.every((id) => KNOWN_ORDER_WARNING_IDS.has(id)),
-                },
-            ];
-        });
-        if (warnings.length > 0)
-            return { state: "warning", warnings };
-        const reasons = items.flatMap((item) => "error" in item && typeof item.error === "string" && item.error.trim()
-            ? [item.error.trim()]
-            : []);
-        if (reasons.length > 0)
-            return { state: "rejected", reasons };
-        const accepted = items.find((item) => "order_id" in item || "orderId" in item);
-        if (accepted !== undefined) {
-            const orderId = ("order_id" in accepted ? accepted.order_id : undefined) ??
-                ("orderId" in accepted ? accepted.orderId : undefined);
-            if (orderId !== undefined) {
+        const decoded = this.decodeOrderSubmission(response);
+        const correlatedClientOrderId = decoded.orders.length === 1 ? clientOrderId : null;
+        const orders = decoded.orders.map((order) => ({
+            ...order,
+            clientOrderId: correlatedClientOrderId,
+        }));
+        const hasWarnings = decoded.warnings.length > 0;
+        const hasErrors = decoded.errors.length > 0;
+        const hasUnknown = decoded.unrecognizedResponses.length > 0;
+        const hasPendingCancel = decoded.pendingCancelOrderIds.length > 0;
+        if (decoded.warnings.length === 1 && !hasErrors && orders.length === 0 && !hasUnknown) {
+            return { state: "warning", warnings: decoded.warnings };
+        }
+        if (hasErrors &&
+            !decoded.responseIsArray &&
+            !hasWarnings &&
+            orders.length === 0 &&
+            !hasUnknown) {
+            return {
+                state: "rejected",
+                reasons: decoded.errors.map(({ message }) => message),
+                errors: decoded.errors,
+            };
+        }
+        if (!hasWarnings && !hasErrors && !hasUnknown && !hasPendingCancel && orders.length === 1) {
+            const order = orders[0];
+            if (order === undefined)
+                throw new Error("Single-order normalization lost order evidence");
+            if (order.status === "REJECTED" || order.status === "CANCELED") {
                 return {
-                    state: "accepted",
-                    orderId: String(orderId),
-                    status: this.normalizeDerivativeOrderStatus(("order_status" in accepted ? accepted.order_status : undefined) ??
-                        ("orderStatus" in accepted ? accepted.orderStatus : undefined), 0, 0),
-                    clientOrderId,
-                    warnings: [],
+                    state: "rejected",
+                    reasons: [`Order ${order.orderId} returned terminal status ${order.status}`],
+                    errors: [],
+                    orders,
                 };
             }
+            if (order.status !== "UNKNOWN") {
+                return { state: "accepted", ...order, warnings: [] };
+            }
+        }
+        return this.singleOrderRecoveryResult(decoded, orders);
+    }
+    normalizeMultiOrderSubmission(response, parentClientOrderId) {
+        const decoded = this.decodeOrderSubmission(response);
+        const hasDistinctBrokerOrderIds = decoded.orders.length === 2 &&
+            new Set(decoded.orders.map(({ orderId }) => orderId)).size === 2;
+        const rolesArePositionallyComplete = decoded.orders.length === 2 &&
+            hasDistinctBrokerOrderIds &&
+            decoded.warnings.length === 0 &&
+            decoded.errors.length === 0 &&
+            decoded.unrecognizedResponses.length === 0;
+        const orders = decoded.orders.map((order, index) => ({
+            ...order,
+            clientOrderId: rolesArePositionallyComplete && index === 0 ? parentClientOrderId : null,
+            role: rolesArePositionallyComplete && index === 0
+                ? "parent"
+                : rolesArePositionallyComplete && index === 1
+                    ? "child"
+                    : "unknown",
+        }));
+        const hasWarnings = decoded.warnings.length > 0;
+        const hasErrors = decoded.errors.length > 0;
+        const hasUnknown = decoded.unrecognizedResponses.length > 0;
+        if (decoded.warnings.length === 1 && !hasErrors && orders.length === 0 && !hasUnknown) {
+            const warning = decoded.warnings[0];
+            if (warning === undefined)
+                throw new Error("Contingent warning evidence was lost");
+            return {
+                state: "warning",
+                warnings: decoded.warnings,
+                continuation: { replyId: warning.replyId, parentClientOrderId },
+            };
+        }
+        if (hasErrors &&
+            !decoded.responseIsArray &&
+            !hasWarnings &&
+            orders.length === 0 &&
+            !hasUnknown) {
+            return {
+                state: "rejected",
+                parentClientOrderId,
+                reasons: decoded.errors.map(({ message }) => message),
+                errors: decoded.errors,
+            };
+        }
+        if (!hasWarnings &&
+            !hasErrors &&
+            !hasUnknown &&
+            decoded.pendingCancelOrderIds.length === 0 &&
+            orders.length === 2 &&
+            hasDistinctBrokerOrderIds) {
+            const [parent, child] = orders;
+            if (parent !== undefined && child !== undefined) {
+                const terminalFailure = orders.find(({ status }) => status === "REJECTED" || status === "CANCELED");
+                const unknownStatus = orders.find(({ status }) => status === "UNKNOWN");
+                if (terminalFailure === undefined && unknownStatus === undefined) {
+                    return { state: "accepted", orders: [parent, child], warnings: [] };
+                }
+            }
+        }
+        return this.contingentRecoveryResult(decoded, orders, parentClientOrderId);
+    }
+    decodeOrderSubmission(response) {
+        const items = Array.isArray(response) ? response : [response];
+        const decoded = {
+            responseIsArray: Array.isArray(response),
+            orders: [],
+            pendingCancelOrderIds: [],
+            warnings: [],
+            errors: [],
+            unrecognizedResponses: [],
+        };
+        for (const item of items) {
+            if (typeof item !== "object" || item === null || Array.isArray(item)) {
+                decoded.unrecognizedResponses.push(item);
+                continue;
+            }
+            const record = item;
+            let recognized = false;
+            const rawWarningId = record["id"];
+            if (typeof rawWarningId === "string" && rawWarningId.trim()) {
+                const rawMessageIds = record["messageIds"];
+                const messageIds = Array.isArray(rawMessageIds)
+                    ? rawMessageIds.filter((value) => typeof value === "string")
+                    : [];
+                decoded.warnings.push({
+                    replyId: rawWarningId.trim(),
+                    messages: Array.isArray(record["message"])
+                        ? record["message"].filter((value) => typeof value === "string")
+                        : [],
+                    messageIds,
+                    known: Array.isArray(rawMessageIds) &&
+                        rawMessageIds.length > 0 &&
+                        rawMessageIds.every((id) => typeof id === "string" && KNOWN_ORDER_WARNING_IDS.has(id)),
+                });
+                recognized = true;
+            }
+            else if ("id" in record) {
+                decoded.unrecognizedResponses.push({ ...record });
+                recognized = true;
+            }
+            if (record["error"] !== undefined && record["error"] !== null) {
+                if (this.isMeaningfulBrokerError(record["error"], record)) {
+                    decoded.errors.push(this.normalizeBrokerError(record["error"], record));
+                }
+                else {
+                    decoded.unrecognizedResponses.push({ ...record });
+                }
+                recognized = true;
+            }
+            const hasOrderId = "order_id" in record || "orderId" in record;
+            const rawOrderId = record["order_id"] ?? record["orderId"];
+            const orderId = typeof rawOrderId === "string" && rawOrderId.trim()
+                ? rawOrderId.trim()
+                : typeof rawOrderId === "number" && Number.isSafeInteger(rawOrderId) && rawOrderId > 0
+                    ? String(rawOrderId)
+                    : null;
+            if (orderId !== null) {
+                const orderStatus = record["order_status"] ?? record["orderStatus"];
+                if (typeof orderStatus === "string" &&
+                    this.canonicalIbkrOrderStatus(orderStatus) === "PENDING_CANCEL") {
+                    decoded.pendingCancelOrderIds.push(orderId);
+                }
+                decoded.orders.push({
+                    orderId,
+                    status: this.normalizeDerivativeOrderStatus(typeof orderStatus === "string" ? orderStatus : undefined, 0, 0),
+                    clientOrderId: null,
+                });
+                recognized = true;
+            }
+            else if (hasOrderId) {
+                decoded.unrecognizedResponses.push({ ...record });
+                recognized = true;
+            }
+            if (!recognized)
+                decoded.unrecognizedResponses.push({ ...record });
         }
-        return { state: "rejected", reasons: ["IBKR returned an unknown order response"] };
+        if (items.length === 0)
+            decoded.unrecognizedResponses.push({});
+        return decoded;
+    }
+    singleOrderRecoveryResult(decoded, orders) {
+        return {
+            state: "recovery_required",
+            reasons: [this.submissionRecoveryReason(decoded, orders.length, 1)],
+            orders,
+            warnings: decoded.warnings,
+            errors: decoded.errors,
+            unrecognizedResponses: decoded.unrecognizedResponses,
+        };
+    }
+    contingentRecoveryResult(decoded, orders, parentClientOrderId) {
+        return {
+            state: "recovery_required",
+            parentClientOrderId,
+            reasons: [this.submissionRecoveryReason(decoded, orders.length, 2)],
+            orders,
+            warnings: decoded.warnings,
+            errors: decoded.errors,
+            unrecognizedResponses: decoded.unrecognizedResponses,
+        };
+    }
+    submissionRecoveryReason(decoded, orderCount, expectedOrderCount) {
+        const pendingCancelOrderId = decoded.pendingCancelOrderIds[0];
+        if (pendingCancelOrderId !== undefined) {
+            return `Order ${pendingCancelOrderId} has a pending cancellation`;
+        }
+        const terminal = decoded.orders.find(({ status }) => status === "REJECTED" || status === "CANCELED");
+        if (terminal !== undefined) {
+            return `Order ${terminal.orderId} returned terminal status ${terminal.status}`;
+        }
+        if (decoded.orders.some(({ status }) => status === "UNKNOWN")) {
+            return "IBKR returned an order ID with an unknown status";
+        }
+        if (new Set(decoded.orders.map(({ orderId }) => orderId)).size < decoded.orders.length) {
+            return "IBKR returned duplicate broker order IDs";
+        }
+        if (decoded.errors.length > 0 && decoded.warnings.length > 0) {
+            return "IBKR returned both warnings and rejections for one submission";
+        }
+        if (decoded.warnings.length > 1) {
+            return "IBKR returned multiple warning continuations for one submission";
+        }
+        if (orderCount !== expectedOrderCount) {
+            return `IBKR returned ${String(orderCount)} of ${String(expectedOrderCount)} expected order acknowledgements`;
+        }
+        if (decoded.unrecognizedResponses.length > 0) {
+            return "IBKR returned one or more unrecognized order responses";
+        }
+        return "IBKR returned mixed or incomplete order evidence";
+    }
+    normalizeBrokerError(error, response) {
+        const nested = typeof error === "object" && error !== null ? error : undefined;
+        const nestedMessage = nested ? nested.message : undefined;
+        const responseMessage = response["message"];
+        const message = (typeof nestedMessage === "string" && nestedMessage.trim()) ||
+            (typeof error === "string" && error.trim()) ||
+            (typeof responseMessage === "string" && responseMessage.trim()) ||
+            "IBKR rejected the order";
+        const nestedCode = nested ? nested.code : undefined;
+        const responseCode = response["code"];
+        const codeValue = nestedCode ?? responseCode;
+        const statusValue = response["statusCode"];
+        return {
+            message,
+            code: typeof codeValue === "string" || typeof codeValue === "number" ? String(codeValue) : null,
+            statusCode: typeof statusValue === "number" && Number.isFinite(statusValue) ? statusValue : null,
+            details: response,
+        };
+    }
+    isMeaningfulBrokerError(error, response) {
+        const nested = typeof error === "object" && error !== null ? error : undefined;
+        const nestedRecord = nested;
+        const messages = [error, nestedRecord?.["message"], response["message"]];
+        if (messages.some((value) => typeof value === "string" && value.trim()))
+            return true;
+        const code = nestedRecord?.["code"] ?? response["code"];
+        if ((typeof code === "string" && code.trim()) ||
+            (typeof code === "number" && Number.isFinite(code))) {
+            return true;
+        }
+        const status = nestedRecord?.["statusCode"] ?? nestedRecord?.["status"] ?? response["statusCode"];
+        return typeof status === "number" && Number.isFinite(status) && status >= 400;
     }
     normalizeDerivativeOrderLifecycle(accountId, orderId, order) {
-        const quantity = this.firstPositiveNumber(order.total_size, order.totalSize, order.size) ?? 0;
-        const filledQuantity = this.firstNumber(order.cum_fill, order.cumFill, order.filledQuantity) ?? 0;
-        const remainingQuantity = order.remainingQuantity === undefined
-            ? Math.max(0, quantity - filledQuantity)
-            : toNumber(order.remainingQuantity);
+        const quantity = this.firstPositiveNumber(order.total_size, order.totalSize, order.size);
+        const filledQuantity = this.firstNumber(order.cum_fill, order.cumFill, order.filledQuantity, order.filled);
+        const remainingQuantity = this.firstNumber(order.remainingQuantity, order.remaining_size, order.remaining);
+        if (quantity === undefined ||
+            filledQuantity === undefined ||
+            filledQuantity < 0 ||
+            remainingQuantity === undefined ||
+            remainingQuantity < 0) {
+            throw new Error(`IBKR order ${orderId} returned incomplete fill quantities`);
+        }
         return {
             accountId,
             orderId,
-            clientOrderId: order.cOID ?? null,
+            clientOrderId: order.cOID ?? order.order_ref ?? null,
             status: this.normalizeDerivativeOrderStatus(order.order_status ?? order.orderStatus ?? order.status, filledQuantity, remainingQuantity),
             quantity,
             filledQuantity,
             remainingQuantity,
-            averagePrice: this.firstNumber(order.avgPrice, order.average_price, order.averagePrice) ?? null,
-            limitPrice: this.firstNumber(order.limitPrice, order.price) ?? null,
+            averagePrice: this.firstNumber(order.avgPrice, order.avg_price, order.average_price, order.averagePrice) ?? null,
+            limitPrice: this.firstNumber(order.limitPrice, order.limit_price, order.price) ?? null,
             commissionAndFees: typeof order.commissionAndFees === "number"
                 ? order.commissionAndFees
                 : this.whatIfNumber(order.commissionAndFees),
@@ -600,6 +1083,204 @@ export class IbkrClient {
             updatedAt: this.parseOrderTime(order)?.toISOString() ?? null,
         };
     }
+    normalizeDerivativeExecution(accountId, trade) {
+        if (!trade.execution_id || !Number.isSafeInteger(trade.conid) || Number(trade.conid) <= 0) {
+            return undefined;
+        }
+        const commission = typeof trade.commission === "number" ? trade.commission : this.whatIfNumber(trade.commission);
+        const commissionCurrency = typeof trade.commission === "string"
+            ? (/\b(?<currency>[A-Z]{3})\s*$/.exec(trade.commission.trim())?.groups?.["currency"] ??
+                null)
+            : null;
+        const side = trade.side?.trim().toUpperCase();
+        return {
+            accountId,
+            executionId: trade.execution_id,
+            orderId: trade.order_id === undefined ? null : String(trade.order_id),
+            clientOrderId: this.trimmedString(trade.order_ref),
+            conid: Number(trade.conid),
+            symbol: this.trimmedString(trade.contract_description_1) ?? this.trimmedString(trade.symbol),
+            side: side === "B" || side === "BUY" || side === "BOT"
+                ? "BUY"
+                : side === "S" || side === "SELL" || side === "SLD"
+                    ? "SELL"
+                    : "UNKNOWN",
+            quantity: this.firstNumber(trade.size) ?? 0,
+            price: this.firstNumber(trade.price) ?? null,
+            commission,
+            commissionCurrency,
+            netAmount: this.firstNumber(trade.net_amount) ?? null,
+            exchange: this.trimmedString(trade.exchange),
+            executedAt: this.parseTradeTime(trade),
+        };
+    }
+    parseTradeTime(trade) {
+        if (trade.trade_time_r !== undefined) {
+            const epoch = new Date(trade.trade_time_r);
+            if (!Number.isNaN(epoch.getTime()))
+                return epoch.toISOString();
+        }
+        const value = trade.trade_time;
+        const match = value ? /^(\d{4})(\d{2})(\d{2})-(\d{2}):(\d{2}):(\d{2})$/.exec(value) : null;
+        if (!match)
+            return null;
+        const [, year, month, day, hour, minute, second] = match;
+        if (!year || !month || !day || !hour || !minute || !second)
+            return null;
+        const parsed = new Date(`${year}-${month}-${day}T${hour}:${minute}:${second}Z`);
+        return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+    }
+    trimmedString(value) {
+        if (value === undefined)
+            return null;
+        const trimmed = value.trim();
+        return trimmed.length === 0 ? null : trimmed;
+    }
+    validateReconciliationRequest(request) {
+        if (!request.accountId.trim() || !request.orderId.trim() || !request.clientOrderId.trim()) {
+            throw new Error("Exact account, order, and client order IDs are required for reconciliation");
+        }
+        if (!Number.isSafeInteger(request.quantity) || request.quantity <= 0) {
+            throw new Error("Reconciliation quantity must be a positive integer");
+        }
+        if (!Number.isFinite(request.multiplier) || request.multiplier <= 0) {
+            throw new Error("Reconciliation multiplier must be positive");
+        }
+        if (request.legs.some(({ conid, ratio }) => !Number.isSafeInteger(conid) || conid <= 0 || !Number.isSafeInteger(ratio) || ratio === 0) ||
+            request.legs[0].conid === request.legs[1].conid) {
+            throw new Error("Reconciliation legs require distinct conids and non-zero integer ratios");
+        }
+        if ((request.timeoutMs ?? 30_000) < 0 || (request.pollMs ?? 1_000) <= 0) {
+            throw new Error("Reconciliation timing must use a non-negative timeout and positive poll");
+        }
+    }
+    evaluateDerivativeReconciliation(request, lifecycle, trades) {
+        const base = {
+            aggregateStatus: lifecycle.status,
+            filledQuantity: lifecycle.filledQuantity,
+            remainingQuantity: lifecycle.remainingQuantity,
+            multiplier: request.multiplier,
+        };
+        const recovery = (reason) => ({
+            ...base,
+            state: "RECOVERY_REQUIRED",
+            reason,
+            legs: [],
+            grossPoints: null,
+            grossAmount: null,
+            commission: null,
+            netAmount: null,
+        });
+        if (lifecycle.quantity !== request.quantity) {
+            return recovery("Aggregate order quantity does not match the reviewed combo");
+        }
+        if (lifecycle.clientOrderId !== null && lifecycle.clientOrderId !== request.clientOrderId) {
+            return recovery("Aggregate client order reference does not match the reviewed combo");
+        }
+        const expectedLegs = request.legs.map(({ conid, ratio }) => ({ conid, ratio }));
+        if (JSON.stringify(lifecycle.legs) !== JSON.stringify(expectedLegs)) {
+            return recovery("Aggregate combo legs do not match the reviewed combo");
+        }
+        const matching = trades.filter(({ clientOrderId }) => clientOrderId === request.clientOrderId);
+        const executionIds = new Set();
+        for (const trade of matching) {
+            if (executionIds.has(trade.executionId)) {
+                return recovery("Duplicate execution ID requires manual recovery");
+            }
+            executionIds.add(trade.executionId);
+            if (trade.orderId !== null && trade.orderId !== request.orderId) {
+                return recovery("Execution order ID does not match the reviewed combo");
+            }
+            const expected = request.legs.find(({ conid }) => conid === trade.conid);
+            if (expected === undefined) {
+                return recovery("Execution contains an unexpected combo leg");
+            }
+            if (trade.side !== this.sideForRatio(expected.ratio)) {
+                return recovery("Execution side does not match the reviewed combo ratio");
+            }
+            if (trade.quantity <= 0 ||
+                trade.price === null ||
+                trade.price < 0 ||
+                trade.commission === null ||
+                trade.commission < 0 ||
+                trade.executedAt === null) {
+                return recovery("Execution contains incomplete economics or timing evidence");
+            }
+        }
+        const completeExecutions = matching.flatMap((trade) => trade.side !== "UNKNOWN" &&
+            trade.price !== null &&
+            trade.commission !== null &&
+            trade.executedAt !== null
+            ? [
+                {
+                    ...trade,
+                    side: trade.side,
+                    price: trade.price,
+                    commission: trade.commission,
+                    executedAt: trade.executedAt,
+                },
+            ]
+            : []);
+        const summaries = [];
+        for (const expected of request.legs) {
+            const executions = completeExecutions.filter(({ conid }) => conid === expected.conid);
+            const quantity = executions.reduce((sum, trade) => sum + trade.quantity, 0);
+            const expectedQuantity = lifecycle.filledQuantity * Math.abs(expected.ratio);
+            if (quantity > expectedQuantity) {
+                return recovery("Execution quantity exceeds the aggregate fill");
+            }
+            if (quantity < expectedQuantity) {
+                return {
+                    ...base,
+                    state: "PENDING",
+                    reason: "Terminal order is missing expected execution evidence",
+                    legs: summaries,
+                    grossPoints: null,
+                    grossAmount: null,
+                    commission: null,
+                    netAmount: null,
+                };
+            }
+            if (quantity > 0) {
+                summaries.push({
+                    conid: expected.conid,
+                    side: this.sideForRatio(expected.ratio),
+                    quantity,
+                    averagePrice: this.round(executions.reduce((sum, trade) => sum + trade.price * trade.quantity, 0) / quantity, 8),
+                    commission: this.round(executions.reduce((sum, trade) => sum + trade.commission, 0), 2),
+                    executionCount: executions.length,
+                });
+            }
+        }
+        const cashFlowPoints = completeExecutions.reduce((sum, trade) => sum + (trade.side === "SELL" ? 1 : -1) * trade.price * trade.quantity, 0);
+        const grossPoints = lifecycle.filledQuantity > 0 ? this.round(cashFlowPoints / lifecycle.filledQuantity, 8) : 0;
+        const grossAmount = this.round(cashFlowPoints * request.multiplier, 2);
+        const commission = this.round(completeExecutions.reduce((sum, trade) => sum + trade.commission, 0), 2);
+        const result = {
+            ...base,
+            state: this.isTerminalDerivativeStatus(lifecycle.status) ? "VERIFIED" : "PENDING",
+            reason: null,
+            legs: summaries,
+            grossPoints,
+            grossAmount,
+            commission,
+            netAmount: this.round(grossAmount - commission, 2),
+        };
+        if (lifecycle.status === "FILLED" && lifecycle.filledQuantity !== request.quantity) {
+            return recovery("Filled aggregate quantity does not match the reviewed combo");
+        }
+        return result;
+    }
+    sideForRatio(ratio) {
+        return ratio > 0 ? "BUY" : "SELL";
+    }
+    isTerminalDerivativeStatus(status) {
+        return status === "FILLED" || status === "CANCELED" || status === "REJECTED";
+    }
+    round(value, decimalPlaces) {
+        const factor = 10 ** decimalPlaces;
+        return Math.round((value + Number.EPSILON) * factor) / factor;
+    }
     parseComboLegs(conidex) {
         const encoded = conidex?.split(";;;")[1];
         if (!encoded)
@@ -614,10 +1295,7 @@ export class IbkrClient {
         });
     }
     normalizeDerivativeOrderStatus(value, filledQuantity, remainingQuantity) {
-        const status = value
-            ?.replace(/([a-z])([A-Z])/g, "$1_$2")
-            .replace(/\s+/g, "_")
-            .toUpperCase();
+        const status = this.canonicalIbkrOrderStatus(value);
         if (filledQuantity > 0 && remainingQuantity > 0)
             return "PARTIALLY_FILLED";
         if (status === "FILLED")
@@ -632,6 +1310,12 @@ export class IbkrClient {
             return "WORKING";
         return "UNKNOWN";
     }
+    canonicalIbkrOrderStatus(value) {
+        return value
+            ?.replace(/([a-z])([A-Z])/g, "$1_$2")
+            .replace(/\s+/g, "_")
+            .toUpperCase();
+    }
     normalizeComboPreview(accountId, diagnostics, response) {
         const commission = this.whatIfNumber(response.amount?.commission);
         const initialMargin = this.whatIfMargin(response.initial);
@@ -772,7 +1456,10 @@ export class IbkrClient {
     }
     /** Discover listed derivative series over an inclusive calendar range. */
     async getDerivativeExpiries(query) {
-        const contracts = (await Promise.all(monthCodes(query.from, query.to).map((month) => this.discoverDerivativeMonth(query.underlying, query.assetClass, month, query.exchange, query.right)))).flat();
+        const contracts = [];
+        for (const month of monthCodes(query.from, query.to)) {
+            contracts.push(...(await this.discoverDerivativeMonth(query.underlying, query.assetClass, month, query.exchange, query.right)));
+        }
         const filtered = contracts.filter((contract) => contract.expiration >= query.from &&
             contract.expiration <= query.to &&
             (query.right === undefined || contract.right === query.right) &&
@@ -1450,6 +2137,14 @@ export class IbkrClient {
     wait(ms) {
         return sleep(ms);
     }
+    /** Overridable monotonic-enough wall clock for bounded polling tests. */
+    now() {
+        return Date.now();
+    }
+    /** Overridable entropy source for deterministic scheduler jitter tests. */
+    random() {
+        return Math.random();
+    }
     normalizeQuote(contract, snapshot, history) {
         const symbol = this.snapshotString(snapshot, "55") ?? contract.symbol;
         const description = this.snapshotString(snapshot, "58") ?? history?.text ?? contract.description;
@@ -1571,23 +2266,84 @@ export class IbkrClient {
     async sendRequest(input) {
         return (await this.raw.request(input));
     }
-    async req(input) {
-        let retries = 0;
-        for (;;) {
+    req(input) {
+        return this.scheduledRequest(input, true);
+    }
+    singleAttemptRequest(input) {
+        return this.scheduledRequest(input, false);
+    }
+    scheduledRequest(input, retryable) {
+        return this.requestScheduler.schedule({
+            endpoint: this.requestEndpoint(input.path),
+            priority: this.requestPriority(input.path),
+            retryable,
+        }, () => this.sendRequest(input));
+    }
+    requestPriority(path) {
+        if (path === "iserver/accounts" ||
+            path === "iserver/auth/status" ||
+            path.includes("/orders") ||
+            path.includes("/order/status/") ||
+            path === "iserver/account/trades" ||
+            path.startsWith("iserver/reply/")) {
+            return "EXECUTION";
+        }
+        if (path.includes("secdef"))
+            return "DISCOVERY";
+        return "STANDARD";
+    }
+    requestEndpoint(path) {
+        if (path.includes("secdef/"))
+            return path.slice(path.indexOf("secdef/"));
+        if (path.includes("/order/status/"))
+            return "account/order/status";
+        if (path.includes("/orders/whatif"))
+            return "account/orders/whatif";
+        if (path.endsWith("/orders"))
+            return "account/orders";
+        if (path.includes("/order/"))
+            return "account/order";
+        if (path.startsWith("iserver/reply/"))
+            return "reply";
+        if (path === "iserver/account/trades")
+            return "account/trades";
+        return path.split("/").slice(0, 2).join("/");
+    }
+    classifyRequestError(error) {
+        if (/temporar(?:ily|y).*(?:block|ban)|(?:ip|access).*(?:temporar(?:ily|y) )?blocked/i.test(this.requestErrorText(error))) {
+            return { kind: "TEMPORARILY_BLOCKED" };
+        }
+        if (this.httpStatusFromError(error) === 429) {
+            const retryAfterMs = this.retryAfterFromError(error);
+            return retryAfterMs === undefined
+                ? { kind: "THROTTLED" }
+                : { kind: "THROTTLED", retryAfterMs };
+        }
+        return { kind: "OTHER" };
+    }
+    requestErrorText(error) {
+        if (typeof error !== "object" || error === null)
+            return String(error);
+        const message = error.message;
+        const response = error.response;
+        const responseData = typeof response === "object" && response !== null && "data" in response
+            ? response.data
+            : undefined;
+        const body = error.body;
+        return [message, responseData, body]
+            .flatMap((value) => {
+            if (typeof value === "string")
+                return [value];
+            if (value === undefined)
+                return [];
             try {
-                return await this.sendRequest(input);
+                return [JSON.stringify(value)];
             }
-            catch (error) {
-                const status = this.httpStatusFromError(error);
-                if (status !== 429 || retries >= READ_ONLY_REQUEST_MAX_RETRIES) {
-                    throw error;
-                }
-                const retryAfter = this.retryAfterFromError(error);
-                const delayMs = this.computeBackoffDelayMs(retries, retryAfter);
-                retries += 1;
-                await this.wait(delayMs);
+            catch {
+                return [];
             }
-        }
+        })
+            .join(" ");
     }
     httpStatusFromError(error) {
         if (typeof error !== "object" || error === null)
@@ -1623,11 +2379,6 @@ export class IbkrClient {
             this.headerValue(directHeaders, "Retry-After");
         return parseRetryAfter(retryAfterRaw);
     }
-    computeBackoffDelayMs(retry, retryAfterMs) {
-        if (retryAfterMs !== undefined)
-            return Math.min(retryAfterMs, REQUEST_RETRY_MAX_DELAY_MS);
-        return Math.min(REQUEST_RETRY_BASE_DELAY_MS * 2 ** retry, REQUEST_RETRY_MAX_DELAY_MS);
-    }
     numberFromUnknown(value) {
         if (typeof value === "number")
             return Number.isFinite(value) ? value : undefined;