@huskly/ibkr-client 0.28.0 → 1.0.0

package/dist/ibkr/ibkrClient.js

@@ -81,16 +81,17 @@ function extractOsiPositionSymbol(contractDescription) {
     return /\[([A-Z]+\s*\d{6}[CP]\d{8})\s+\d+\]\s*$/.exec(contractDescription)?.[1];
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-function parseRetryAfter(raw) {
+function parseRetryAfter(raw, now) {
     const asString = typeof raw === "string" ? raw.trim() : undefined;
     if (!asString)
         return undefined;
     const numeric = Number(asString);
-    if (Number.isFinite(numeric) && numeric > 0)
-        return Math.ceil(numeric * 1000);
+    const numericMs = Math.ceil(numeric * 1000);
+    if (Number.isSafeInteger(numericMs) && numericMs > 0)
+        return numericMs;
     const date = Date.parse(asString);
     if (!Number.isNaN(date)) {
-        const ms = Math.max(0, date - Date.now());
+        const ms = Math.max(0, date - now);
         if (ms > 0)
             return ms;
     }
@@ -99,6 +100,25 @@ function parseRetryAfter(raw) {
 function isUnknownRecord(input) {
     return typeof input === "object" && input !== null && !Array.isArray(input);
 }
+const PRICE_HISTORY_SECURITY_TYPES = new Set([
+    "STK",
+    "IND",
+    "OPT",
+    "FUT",
+    "FOP",
+    "CASH",
+    "CFD",
+    "WAR",
+    "FUND",
+    "BOND",
+    "CMDTY",
+]);
+function isPriceHistorySecurityType(value) {
+    return PRICE_HISTORY_SECURITY_TYPES.has(value);
+}
+function isFiniteHistoryBar(bar) {
+    return [bar.t, bar.o, bar.h, bar.l, bar.c, bar.v].every((value) => typeof value === "number" && Number.isFinite(value));
+}
 function isHeadersLike(input) {
     return (typeof input === "object" &&
         input !== null &&
@@ -168,6 +188,60 @@ function monthCodes(fromDate, toDate) {
     }
     return result;
 }
+/** A typed HTTP failure from the IBKR transport. */
+export class IbkrHttpError extends Error {
+    status;
+    response;
+    statusCode;
+    constructor(message, status, response, options) {
+        super(message, options);
+        this.status = status;
+        this.response = response;
+        this.name = "IbkrHttpError";
+        this.statusCode = status;
+    }
+}
+/**
+ * Typed broker rejection for documented IBKR error-object payloads outside order
+ * submission result envelopes. Callers can catch this class to read the retained
+ * {@link BrokerErrorDetail} without parsing free-form message text.
+ */
+export class IbkrBrokerResponseError extends Error {
+    detail;
+    constructor(message, detail, options) {
+        super(message, options);
+        this.detail = detail;
+        this.name = "IbkrBrokerResponseError";
+    }
+}
+/** Typed contract-resolution failure raised before a price-history broker request. */
+export class IbkrPriceHistoryContractError extends Error {
+    code;
+    candidates;
+    constructor(message, code, candidates = []) {
+        super(message);
+        this.code = code;
+        this.candidates = candidates;
+        this.name = "IbkrPriceHistoryContractError";
+    }
+}
+/** A daily history request for which IBKR did not return the full requested interval. */
+export class IbkrInsufficientHistoryError extends Error {
+    symbol;
+    requestedStart;
+    requestedEnd;
+    availableStart;
+    availableEnd;
+    constructor(symbol, requestedStart, requestedEnd, availableStart, availableEnd, options) {
+        super(`IBKR returned insufficient daily history for ${symbol}`, options);
+        this.symbol = symbol;
+        this.requestedStart = requestedStart;
+        this.requestedEnd = requestedEnd;
+        this.availableStart = availableStart;
+        this.availableEnd = availableEnd;
+        this.name = "IbkrInsufficientHistoryError";
+    }
+}
 /**
  * Typed IBKR Web API client implementing the broker-neutral {@link BrokerClient}.
  * Wraps the `ibkr-client` npm package, which performs the OAuth 1.0a
@@ -179,17 +253,24 @@ export class IbkrClient {
     initPromise;
     accountIdPromise;
     optionDiscovery = new Map();
-    optionUnderlyingDiscovery = new Map();
     optionContractResolution = new Map();
     derivativeDiscovery = new Map();
     requestScheduler;
+    requestNow;
+    secdefPrimingTail = Promise.resolve();
+    onPriceHistoryTelemetry;
+    onRequestTelemetry;
     constructor(config, options = {}) {
         this.raw = new RawIbkrClientCtor(config);
+        this.onPriceHistoryTelemetry = options.onPriceHistoryTelemetry ?? (() => undefined);
+        this.onRequestTelemetry = options.onRequestTelemetry ?? (() => undefined);
+        const schedulerOptions = options.requestScheduler;
+        this.requestNow = schedulerOptions?.now ?? (() => this.now());
         this.requestScheduler = new IbkrRequestScheduler({
-            ...options.requestScheduler,
-            now: () => this.now(),
-            sleep: (ms) => this.wait(ms),
-            random: () => this.random(),
+            ...schedulerOptions,
+            now: this.requestNow,
+            sleep: schedulerOptions?.sleep ?? ((ms) => this.wait(ms)),
+            random: schedulerOptions?.random ?? (() => this.random()),
             classifyError: (error) => this.classifyRequestError(error),
             ...(options.onRequestTelemetry === undefined
                 ? {}
@@ -199,7 +280,12 @@ export class IbkrClient {
     /** Obtain the live session token (idempotent — safe to await repeatedly). */
     init() {
         this.initPromise ??= (async () => {
-            await this.raw.init();
+            try {
+                await this.raw.init();
+            }
+            catch (error) {
+                throw this.normalizeHttpError(error);
+            }
             // IBKR is slow right after init; give the session a moment to settle.
             await this.wait(1000);
         })();
@@ -250,7 +336,7 @@ export class IbkrClient {
             path: "iserver/marketdata/snapshot",
             params: { conids, fields: "6509" },
         });
-        const response = await this.req({
+        const response = await this.singleAttemptRequest({
             path: `iserver/account/${request.accountId}/orders/whatif`,
             method: "POST",
             data: {
@@ -1336,7 +1422,7 @@ export class IbkrClient {
             openProfitLoss: toNumber(p.unrealizedPnl),
         };
     }
-    async getQuotes(requests) {
+    async getQuotes(requests, options = {}) {
         const unique = new Map();
         for (const request of requests) {
             if (!request.symbol.trim())
@@ -1363,9 +1449,9 @@ export class IbkrClient {
                 conid,
             };
         }));
-        return this.fetchQuotes(contracts.filter((contract) => contract !== undefined));
+        return this.fetchQuotes(contracts.filter((contract) => contract !== undefined), options.includeHistory ?? true);
     }
-    async fetchQuotes(contracts) {
+    async fetchQuotes(contracts, includeHistory) {
         if (!contracts.length)
             return {};
         const conids = contracts.map((contract) => contract.conid).join(",");
@@ -1379,7 +1465,9 @@ export class IbkrClient {
         const snapshotByConid = new Map(snapshots
             .filter((snapshot) => snapshot.conid !== undefined)
             .map((snapshot) => [snapshot.conid, snapshot]));
-        const histories = await Promise.all(contracts.map((contract) => this.fetchQuoteHistory(contract.conid)));
+        const histories = includeHistory
+            ? await Promise.all(contracts.map((contract) => this.fetchQuoteHistory(contract.conid)))
+            : contracts.map(() => undefined);
         const quotes = {};
         for (const [index, contract] of contracts.entries()) {
             const snapshot = snapshotByConid.get(contract.conid);
@@ -2248,7 +2336,7 @@ export class IbkrClient {
         }
         return "IBKR returned mixed or incomplete order evidence";
     }
-    normalizeBrokerError(error, response) {
+    normalizeBrokerError(error, response, defaultMessage = "IBKR rejected the order") {
         const nested = typeof error === "object" && error !== null ? error : undefined;
         const nestedMessage = nested ? nested.message : undefined;
         const responseMessage = response["message"];
@@ -2259,7 +2347,7 @@ export class IbkrClient {
             (typeof responseMessage === "string" && responseMessage.trim()) ||
             (typeof responseText === "string" && responseText.trim()) ||
             (typeof responseWarningMessage === "string" && responseWarningMessage.trim()) ||
-            "IBKR rejected the order";
+            defaultMessage;
         const nestedCode = nested ? nested.code : undefined;
         const responseCode = response["code"];
         const codeValue = nestedCode ?? responseCode;
@@ -2271,6 +2359,36 @@ export class IbkrClient {
             details: response,
         };
     }
+    /**
+     * Validate `iserver/secdef/search` at one shared boundary.
+     * Accept the documented success array, convert the documented error object into a typed
+     * broker error, and fail closed on any other shape. Never treat an error object as an empty
+     * successful search.
+     */
+    parseSecdefSearchResponse(response) {
+        if (Array.isArray(response)) {
+            return response;
+        }
+        if (isUnknownRecord(response) &&
+            response["error"] !== undefined &&
+            response["error"] !== null) {
+            // Any non-null `error` field is the documented IBKR error-object shape for this
+            // endpoint. Do not reclassify it as a malformed payload when the message is empty.
+            const detail = this.normalizeBrokerError(response["error"], response, "IBKR rejected the security-definition search");
+            throw new IbkrBrokerResponseError(detail.message, detail);
+        }
+        throw new Error("IBKR returned a malformed secdef/search response");
+    }
+    /** Serialize IBKR operations that mutate and then consume session security-definition state. */
+    withSecdefPriming(operation) {
+        const result = this.secdefPrimingTail.then(operation);
+        this.secdefPrimingTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    /** Run one state-mutating search outside a larger priming transaction. */
+    searchSecdef(params) {
+        return this.withSecdefPriming(async () => this.parseSecdefSearchResponse(await this.req({ path: "iserver/secdef/search", params })));
+    }
     isMeaningfulBrokerError(error, response) {
         const nested = typeof error === "object" && error !== null ? error : undefined;
         const nestedRecord = nested;
@@ -2834,7 +2952,7 @@ export class IbkrClient {
         if (brokerageAccounts.accounts && !brokerageAccounts.accounts.includes(accountId)) {
             throw new Error(`IBKR account ${accountId} is not available for trading/order queries.`);
         }
-        const switchedAccount = await this.req({
+        const switchedAccount = await this.singleAttemptRequest({
             path: "iserver/account",
             method: "POST",
             data: { acctId: accountId },
@@ -2900,10 +3018,7 @@ export class IbkrClient {
         }
         // `trsrv/stocks` is equity/ETF-only. Fall back to security-definition search so
         // non-stock roots (indexes like VIX, futures, etc.) still resolve to a conid.
-        const search = await this.req({
-            path: "iserver/secdef/search",
-            params: { symbol: symbol.trim().toUpperCase() },
-        });
+        const search = await this.searchSecdef({ symbol: symbol.trim().toUpperCase() });
         const candidate = search.find((item) => item.conid !== undefined &&
             item.sections?.some((section) => {
                 const secType = section.secType?.trim().toUpperCase();
@@ -2920,33 +3035,137 @@ export class IbkrClient {
             conid: fallbackConid,
         };
     }
-    /** Return normalized daily price history without consulting a vendor-owned clock. */
+    /** Return complete daily history with the exact validated IBKR request context. */
     async getPriceHistory(input) {
-        const contract = await this.resolveQuoteContract(input.symbol);
-        if (!contract)
-            throw new Error(`IBKR could not resolve market-data contract: ${input.symbol}`);
-        const days = this.historyDays(input);
-        const history = await this.fetchQuoteHistory(contract.conid, `${String(days)}d`, false);
-        const volumeFactor = history?.volumeFactor ?? 1;
-        return (history?.data ?? []).map((bar) => {
-            if (bar.t === undefined ||
-                bar.o === undefined ||
-                bar.h === undefined ||
-                bar.l === undefined ||
-                bar.c === undefined ||
-                bar.v === undefined) {
-                throw new Error(`IBKR returned an incomplete history bar for ${input.symbol}`);
+        const requestedSymbol = input.symbol.trim().toUpperCase();
+        if (!requestedSymbol) {
+            throw new IbkrPriceHistoryContractError("Price history requires a symbol", "CONTRACT_INVALID");
+        }
+        const interval = this.historyInterval(input);
+        const period = `${String(interval.days)}d`;
+        const contract = await this.resolvePriceHistoryContract(requestedSymbol, input.contract);
+        const request = {
+            period,
+            ...(input.endDate === undefined ? {} : { startTime: this.historyStartTime(interval.end) }),
+        };
+        let bars;
+        try {
+            const history = await this.requestPriceHistory(contract, requestedSymbol, request);
+            bars = this.normalizeHistoryResponse(requestedSymbol, history, interval);
+            this.assertHistoryCoverage(requestedSymbol, bars, interval);
+        }
+        catch (error) {
+            if (!this.isChartDataUnavailable(error))
+                throw error;
+            bars = await this.recoverDailyHistory(contract, requestedSymbol, interval, error);
+        }
+        return {
+            bars,
+            contract,
+            request: { requestedSymbol, period, barSize: "1d" },
+        };
+    }
+    async resolvePriceHistoryContract(requestedSymbol, selector) {
+        if (selector !== undefined) {
+            if (!Number.isSafeInteger(selector.conid) || selector.conid <= 0) {
+                throw new IbkrPriceHistoryContractError(`Invalid IBKR price-history conid: ${String(selector.conid)}`, "CONTRACT_INVALID");
             }
-            return {
-                datetime: bar.t,
-                open: bar.o,
-                high: bar.h,
-                low: bar.l,
-                close: bar.c,
-                volume: bar.v * volumeFactor,
-            };
+            const expectedSecurityType = selector.assetClass?.trim().toUpperCase();
+            if (expectedSecurityType !== undefined && !isPriceHistorySecurityType(expectedSecurityType)) {
+                throw new IbkrPriceHistoryContractError(`Invalid IBKR price-history asset class: ${expectedSecurityType}`, "CONTRACT_INVALID");
+            }
+            return this.validatePriceHistoryContract(requestedSymbol, selector.conid, {
+                ...(expectedSecurityType === undefined ? {} : { securityType: expectedSecurityType }),
+                ...(selector.exchange === undefined
+                    ? {}
+                    : { exchange: selector.exchange.trim().toUpperCase() }),
+            });
+        }
+        const search = await this.searchSecdef({ symbol: requestedSymbol });
+        const candidates = search.flatMap((item) => {
+            const symbol = item.symbol?.trim().toUpperCase();
+            const conid = Number(item.conid);
+            if (symbol !== requestedSymbol ||
+                !Number.isSafeInteger(conid) ||
+                conid <= 0 ||
+                !Array.isArray(item.sections)) {
+                return [];
+            }
+            return item.sections.flatMap((section) => {
+                const securityType = section.secType?.trim().toUpperCase();
+                if (securityType !== "STK" && securityType !== "IND")
+                    return [];
+                const exchange = section.exchange?.trim().toUpperCase();
+                return [
+                    {
+                        conid,
+                        symbol,
+                        securityType,
+                        ...(exchange ? { exchange } : {}),
+                    },
+                ];
+            });
+        });
+        const uniqueCandidates = [
+            ...new Map([...candidates]
+                .sort((left, right) => (left.exchange ?? "").localeCompare(right.exchange ?? ""))
+                .map((candidate) => [[candidate.conid, candidate.securityType].join(":"), candidate])).values(),
+        ];
+        if (uniqueCandidates.length === 0) {
+            throw new IbkrPriceHistoryContractError(`IBKR returned no STK or IND contract for ${requestedSymbol}`, "CONTRACT_NOT_FOUND");
+        }
+        if (uniqueCandidates.length !== 1) {
+            const safeCandidates = uniqueCandidates.map((candidate) => ({
+                conid: candidate.conid,
+                symbol: candidate.symbol,
+                securityType: candidate.securityType,
+                exchange: candidate.exchange ?? null,
+            }));
+            throw new IbkrPriceHistoryContractError(`IBKR price-history contract is ambiguous for ${requestedSymbol}; specify contract.conid`, "CONTRACT_AMBIGUOUS", safeCandidates);
+        }
+        const candidate = uniqueCandidates[0];
+        if (candidate === undefined) {
+            throw new Error("IBKR price-history resolution lost its selected contract");
+        }
+        return this.validatePriceHistoryContract(requestedSymbol, candidate.conid, {
+            securityType: candidate.securityType,
         });
     }
+    async validatePriceHistoryContract(requestedSymbol, conid, expected) {
+        const response = await this.req({
+            path: `iserver/contract/${String(conid)}/info`,
+        });
+        if (isUnknownRecord(response) &&
+            response["error"] !== undefined &&
+            response["error"] !== null) {
+            const detail = this.normalizeBrokerError(response["error"], response, "IBKR rejected the contract metadata request");
+            throw new IbkrBrokerResponseError(detail.message, detail);
+        }
+        if (!isUnknownRecord(response)) {
+            throw new IbkrPriceHistoryContractError(`IBKR returned malformed contract metadata for conid ${String(conid)}`, "CONTRACT_INVALID");
+        }
+        const info = response;
+        const returnedConid = Number(info.con_id);
+        const symbol = info.local_symbol?.trim().toUpperCase();
+        const securityType = info.instrument_type?.trim().toUpperCase();
+        const exchange = info.exchange?.trim().toUpperCase();
+        if (returnedConid !== conid ||
+            symbol === undefined ||
+            !symbol ||
+            securityType === undefined ||
+            !isPriceHistorySecurityType(securityType) ||
+            exchange === undefined ||
+            !exchange) {
+            throw new IbkrPriceHistoryContractError(`IBKR returned incomplete contract metadata for conid ${String(conid)}`, "CONTRACT_INVALID");
+        }
+        const contract = { conid, symbol, securityType, exchange };
+        if (symbol !== requestedSymbol ||
+            (expected.securityType !== undefined && expected.securityType !== securityType) ||
+            (expected.exchange !== undefined && expected.exchange !== exchange)) {
+            throw new IbkrPriceHistoryContractError(`IBKR contract ${String(conid)} does not match the requested price-history identity`, "CONTRACT_MISMATCH", [contract]);
+        }
+        return contract;
+    }
     /** Discover listed derivative series over an inclusive calendar range. */
     async getDerivativeExpiries(query) {
         const contracts = [];
@@ -3137,8 +3356,11 @@ export class IbkrClient {
         return pending;
     }
     /** Resolve one known option directly, without enumerating its month's complete chain. */
-    async loadExactOptionContract(input, month) {
-        const underlying = await this.discoverOptionUnderlying(input.symbol);
+    loadExactOptionContract(input, month) {
+        return this.withSecdefPriming(() => this.loadExactOptionContractPrimed(input, month));
+    }
+    async loadExactOptionContractPrimed(input, month) {
+        const underlying = await this.loadOptionUnderlying(input.symbol);
         const definitions = await this.req({
             path: "iserver/secdef/info",
             params: {
@@ -3220,13 +3442,16 @@ export class IbkrClient {
         }
         return pending;
     }
-    async loadDerivativeContracts(underlying, assetClass, month, requestedExchange, requestedRight, requestedStrike) {
+    loadDerivativeContracts(underlying, assetClass, month, requestedExchange, requestedRight, requestedStrike) {
+        return this.withSecdefPriming(() => this.loadDerivativeContractsPrimed(underlying, assetClass, month, requestedExchange, requestedRight, requestedStrike));
+    }
+    async loadDerivativeContractsPrimed(underlying, assetClass, month, requestedExchange, requestedRight, requestedStrike) {
         // IBKR keeps this priming state in the authenticated session. Strikes may be
         // empty when search has not run first, even with otherwise identical params.
-        const search = await this.req({
+        const search = this.parseSecdefSearchResponse(await this.req({
             path: "iserver/secdef/search",
             params: { symbol: underlying, ...(assetClass === "FOP" ? { secType: "FUT" } : {}) },
-        });
+        }));
         const candidates = search.filter((candidate) => candidate.conid !== undefined &&
             candidate.symbol?.trim().toUpperCase() === underlying &&
             candidate.sections?.some((section) => section.secType?.toUpperCase() === assetClass));
@@ -3341,29 +3566,13 @@ export class IbkrClient {
         }
         return pending;
     }
-    /** Search once per underlying because IBKR uses this call to prime option lookup state. */
-    discoverOptionUnderlying(symbol) {
-        const normalized = symbol.trim().toUpperCase();
-        let pending = this.optionUnderlyingDiscovery.get(normalized);
-        if (!pending) {
-            pending = this.loadOptionUnderlying(normalized).catch((error) => {
-                this.optionUnderlyingDiscovery.delete(normalized);
-                throw error;
-            });
-            this.optionUnderlyingDiscovery.set(normalized, pending);
-        }
-        return pending;
-    }
     async loadOptionUnderlying(symbol) {
         // This search is load-bearing: IBKR silently returns empty definitions unless the current
         // session has first searched the underlying.
-        const search = await this.req({
+        const search = this.parseSecdefSearchResponse(await this.req({
             path: "iserver/secdef/search",
             params: { symbol },
-        });
-        if (!Array.isArray(search)) {
-            throw new Error(`IBKR returned malformed option underlying results for ${symbol}`);
-        }
+        }));
         const candidates = search.flatMap((item) => {
             if (!isUnknownRecord(item))
                 return [];
@@ -3372,28 +3581,41 @@ export class IbkrClient {
                 return [];
             }
             const sections = item["sections"];
-            if (!Array.isArray(sections) ||
-                !sections.some((section) => isUnknownRecord(section) &&
-                    typeof section["secType"] === "string" &&
-                    section["secType"].trim().toUpperCase() === "OPT")) {
+            if (!Array.isArray(sections))
                 return [];
-            }
+            const optionSections = sections.flatMap((section) => {
+                if (!isUnknownRecord(section))
+                    return [];
+                const secType = section["secType"];
+                if (typeof secType !== "string" || secType.trim().toUpperCase() !== "OPT")
+                    return [];
+                const exchange = section["exchange"];
+                return [{ exchange: typeof exchange === "string" ? exchange : null }];
+            });
+            if (!optionSections.length)
+                return [];
+            const supportsSmart = optionSections.some(({ exchange }) => exchange?.split(";").some((name) => name.trim().toUpperCase() === "SMART") ?? false);
             const conid = Number(item["conid"]);
-            return Number.isSafeInteger(conid) && conid > 0 ? [{ conid, symbol }] : [];
+            return Number.isSafeInteger(conid) && conid > 0 ? [{ conid, symbol, supportsSmart }] : [];
         });
         const unique = [
             ...new Map(candidates.map((candidate) => [candidate.conid, candidate])).values(),
         ];
-        if (unique.length !== 1) {
-            throw new Error(`IBKR option underlying identity is ${unique.length ? "ambiguous" : "missing"} for ${symbol}`);
+        const smart = unique.filter((candidate) => candidate.supportsSmart);
+        const eligible = smart.length > 0 ? smart : unique;
+        if (eligible.length !== 1) {
+            throw new Error(`IBKR option underlying identity is ${eligible.length ? "ambiguous" : "missing"} for ${symbol}`);
         }
-        const [underlying] = unique;
+        const [underlying] = eligible;
         if (underlying === undefined)
             throw new Error(`IBKR lost the selected underlying for ${symbol}`);
         return underlying;
     }
-    async loadOptionContracts(symbol, month) {
-        const underlying = await this.discoverOptionUnderlying(symbol);
+    loadOptionContracts(symbol, month) {
+        return this.withSecdefPriming(() => this.loadOptionContractsPrimed(symbol, month));
+    }
+    async loadOptionContractsPrimed(symbol, month) {
+        const underlying = await this.loadOptionUnderlying(symbol);
         const strikes = await this.req({
             path: "iserver/secdef/strikes",
             params: { conid: String(underlying.conid), sectype: "OPT", month },
@@ -3487,32 +3709,273 @@ export class IbkrClient {
         }
         return result;
     }
-    historyDays(input) {
+    historyInterval(input) {
         if (input.days !== undefined) {
             if (!Number.isFinite(input.days) || input.days <= 0) {
                 throw new Error(`History days must be positive: ${String(input.days)}`);
             }
-            return Math.ceil(input.days);
+            const days = Math.ceil(input.days);
+            const endDay = this.utcDayStart(this.now());
+            return { start: endDay - (days - 1) * DAY_MS, end: endDay + DAY_MS - 1, days };
         }
-        if (input.startDate === undefined || input.endDate === undefined) {
-            throw new Error("Price history requires days or both startDate and endDate");
+        if (!Number.isFinite(input.startDate) || !Number.isFinite(input.endDate)) {
+            throw new Error("Price history boundaries must be finite epoch milliseconds");
         }
-        const duration = input.endDate - input.startDate;
-        if (duration < 0)
+        if (input.endDate < input.startDate) {
             throw new Error("Price history endDate must not precede startDate");
-        return Math.max(1, Math.ceil(duration / 86_400_000) + 1);
+        }
+        const start = this.utcDayStart(input.startDate);
+        const endDay = this.utcDayStart(input.endDate);
+        return { start, end: endDay + DAY_MS - 1, days: (endDay - start) / DAY_MS + 1 };
+    }
+    async requestPriceHistory(contract, requestedSymbol, request) {
+        this.onPriceHistoryTelemetry({
+            event: "PRICE_HISTORY_REQUEST",
+            requestedSymbol,
+            resolvedConid: contract.conid,
+            securityType: contract.securityType,
+            exchange: contract.exchange,
+            period: request.period,
+            barSize: "1d",
+        });
+        const history = await this.fetchQuoteHistory(contract.conid, request.period, false, contract.exchange, "1d", request.startTime);
+        if (history === undefined) {
+            throw new Error("IBKR price-history response was unexpectedly unavailable");
+        }
+        return history;
+    }
+    async recoverDailyHistory(contract, symbol, interval, initialCause) {
+        const observed = [];
+        let cause = initialCause;
+        if (interval.days <= 365) {
+            this.onRequestTelemetry({
+                event: "HISTORY_PERIOD_FALLBACK",
+                endpoint: "iserver/marketdata",
+                attempt: 1,
+                delayMs: 0,
+            });
+            let standardBars;
+            try {
+                const history = await this.requestPriceHistory(contract, symbol, {
+                    period: "1y",
+                    startTime: this.historyStartTime(interval.end),
+                });
+                standardBars = this.normalizeHistoryResponse(symbol, history, interval);
+                this.assertHistoryCoverage(symbol, standardBars, interval);
+                return standardBars;
+            }
+            catch (error) {
+                if (standardBars !== undefined)
+                    observed.push(standardBars);
+                if (!this.isChartDataUnavailable(error) &&
+                    !(error instanceof IbkrInsufficientHistoryError)) {
+                    throw error;
+                }
+                cause = error;
+            }
+        }
+        const windows = this.dailyHistoryWindows(symbol, interval, cause);
+        const completed = [];
+        for (const [index, window] of windows.entries()) {
+            this.onRequestTelemetry({
+                event: "HISTORY_WINDOW_FALLBACK",
+                endpoint: "iserver/marketdata",
+                attempt: index + 1,
+                delayMs: 0,
+            });
+            let bars;
+            try {
+                const history = await this.requestPriceHistory(contract, symbol, {
+                    period: `${String(window.days)}d`,
+                    startTime: this.historyStartTime(window.end),
+                });
+                bars = this.normalizeHistoryResponse(symbol, history, window);
+            }
+            catch (error) {
+                if (!this.isChartDataUnavailable(error))
+                    throw error;
+                this.throwInsufficientHistory(symbol, interval, [...observed, ...completed.map(({ bars }) => bars)], error);
+            }
+            try {
+                this.assertHistoryCoverage(symbol, bars, window);
+            }
+            catch (error) {
+                if (!(error instanceof IbkrInsufficientHistoryError))
+                    throw error;
+                this.throwInsufficientHistory(symbol, interval, [...observed, ...completed.map(({ bars: completedBars }) => completedBars), bars], error);
+            }
+            completed.push({ bars, start: window.start, end: window.end });
+        }
+        this.assertHistoryWindowContinuity(symbol, interval, completed);
+        const result = this.mergeHistoryBars(symbol, completed.map(({ bars }) => bars));
+        this.assertHistoryCoverage(symbol, result, interval);
+        return result;
+    }
+    dailyHistoryWindows(symbol, interval, cause) {
+        const maximumPeriodDays = 90;
+        const overlapDays = 7;
+        const windows = [];
+        let end = interval.end;
+        for (;;) {
+            const endDay = this.utcDayStart(end);
+            const start = Math.max(interval.start, endDay - (maximumPeriodDays - 1) * DAY_MS);
+            windows.push({ start, end, days: (endDay - start) / DAY_MS + 1 });
+            if (start === interval.start)
+                return windows;
+            if (windows.length >= 12) {
+                throw new IbkrInsufficientHistoryError(symbol, interval.start, interval.end, null, null, {
+                    cause,
+                });
+            }
+            end = start + overlapDays * DAY_MS - 1;
+        }
+    }
+    normalizeHistoryResponse(symbol, history, interval) {
+        const volumeFactor = history.volumeFactor ?? 1;
+        if (!Number.isFinite(volumeFactor)) {
+            throw new Error(`IBKR returned a non-finite history volume factor for ${symbol}`);
+        }
+        const bars = [];
+        for (const bar of history.data ?? []) {
+            if (!isFiniteHistoryBar(bar)) {
+                throw new Error(`IBKR returned an incomplete or non-finite history bar for ${symbol}`);
+            }
+            const normalized = {
+                datetime: bar.t,
+                open: bar.o,
+                high: bar.h,
+                low: bar.l,
+                close: bar.c,
+                volume: bar.v * volumeFactor,
+            };
+            if (!Number.isFinite(normalized.volume)) {
+                throw new Error(`IBKR returned a non-finite normalized history volume for ${symbol}`);
+            }
+            if (bar.t < interval.start || bar.t > interval.end)
+                continue;
+            bars.push(normalized);
+        }
+        return this.mergeHistoryBars(symbol, [bars]);
+    }
+    mergeHistoryBars(symbol, groups) {
+        const merged = new Map();
+        for (const bar of groups.flat()) {
+            const existing = merged.get(bar.datetime);
+            if (existing !== undefined) {
+                if (existing.open !== bar.open ||
+                    existing.high !== bar.high ||
+                    existing.low !== bar.low ||
+                    existing.close !== bar.close ||
+                    existing.volume !== bar.volume) {
+                    throw new Error(`IBKR returned conflicting history bars for ${symbol} at ${String(bar.datetime)}`);
+                }
+                continue;
+            }
+            merged.set(bar.datetime, bar);
+        }
+        return [...merged.values()].sort((left, right) => left.datetime - right.datetime);
+    }
+    assertHistoryCoverage(symbol, bars, interval) {
+        const availableStart = bars[0]?.datetime ?? null;
+        const availableEnd = bars[bars.length - 1]?.datetime ?? null;
+        const tolerance = Math.min(7 * DAY_MS, interval.end - interval.start);
+        if (availableStart === null ||
+            availableEnd === null ||
+            availableStart > interval.start + tolerance ||
+            availableEnd < interval.end - tolerance) {
+            throw new IbkrInsufficientHistoryError(symbol, interval.start, interval.end, availableStart, availableEnd);
+        }
+    }
+    assertHistoryWindowContinuity(symbol, interval, windows) {
+        const chronological = [...windows].sort((left, right) => left.start - right.start);
+        for (let index = 1; index < chronological.length; index += 1) {
+            const older = chronological[index - 1];
+            const newer = chronological[index];
+            if (older === undefined || newer === undefined)
+                continue;
+            const olderEnd = older.bars[older.bars.length - 1]?.datetime;
+            const newerStart = newer.bars[0]?.datetime;
+            if (olderEnd === undefined || newerStart === undefined || olderEnd < newerStart) {
+                this.throwInsufficientHistory(symbol, interval, chronological.map(({ bars }) => [...bars]), new Error("IBKR returned discontinuous daily history windows"));
+            }
+        }
+    }
+    throwInsufficientHistory(symbol, interval, groups, cause) {
+        const bars = this.mergeHistoryBars(symbol, groups);
+        throw new IbkrInsufficientHistoryError(symbol, interval.start, interval.end, bars[0]?.datetime ?? null, bars[bars.length - 1]?.datetime ?? null, { cause });
+    }
+    utcDayStart(epochMilliseconds) {
+        const date = new Date(epochMilliseconds);
+        return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+    }
+    historyStartTime(epochMilliseconds) {
+        const iso = new Date(epochMilliseconds).toISOString();
+        return `${iso.slice(0, 10).replaceAll("-", "")}-${iso.slice(11, 19)}`;
+    }
+    isChartDataUnavailable(error) {
+        const brokerDetail = error instanceof IbkrBrokerResponseError ? error.detail : undefined;
+        const status = brokerDetail?.statusCode ?? this.httpStatusFromError(error);
+        if (status !== 500)
+            return false;
+        const transportResponse = typeof error === "object" && error !== null
+            ? error.response
+            : undefined;
+        const responseData = typeof transportResponse === "object" && transportResponse !== null
+            ? transportResponse.data
+            : undefined;
+        // Normalized HTTP failures keep the raw payload under `response.body`.
+        const structuredBody = error instanceof IbkrHttpError ? error.response.body : undefined;
+        const body = typeof error === "object" && error !== null ? error.body : undefined;
+        const payload = brokerDetail?.details ?? responseData ?? structuredBody ?? body;
+        const decoded = (() => {
+            if (typeof payload !== "string")
+                return payload;
+            try {
+                return JSON.parse(payload);
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        if (!isUnknownRecord(decoded))
+            return false;
+        let serialized;
+        try {
+            serialized = JSON.stringify(decoded);
+        }
+        catch {
+            return false;
+        }
+        if (/auth|entitl|permission|subscription|invalid.{0,20}(?:contract|conid)|ambiguous.{0,20}contract|security definition/i.test(serialized)) {
+            return false;
+        }
+        const diagnosticValues = [decoded["error"], decoded["message"], decoded["text"]].filter((value) => typeof value === "string" && value.trim() !== "");
+        return (diagnosticValues.length > 0 &&
+            diagnosticValues.every((value) => value.trim().toLowerCase() === "chart data unavailable"));
     }
-    async fetchQuoteHistory(conid, period = "5d", suppressErrors = true) {
+    async fetchQuoteHistory(conid, period = "5d", suppressErrors = true, exchange, bar = "1d", startTime) {
         try {
-            return await this.req({
+            const response = await this.historyRequest({
                 path: "iserver/marketdata/history",
                 params: {
                     conid: String(conid),
+                    ...(exchange === undefined ? {} : { exchange }),
                     period,
-                    bar: "1d",
+                    bar,
                     outsideRth: true,
+                    ...(startTime === undefined ? {} : { startTime }),
                 },
             });
+            if (isUnknownRecord(response) &&
+                response["error"] !== undefined &&
+                response["error"] !== null) {
+                const detail = this.normalizeBrokerError(response["error"], response, "IBKR rejected the market-data history request");
+                throw new IbkrBrokerResponseError(detail.message, detail);
+            }
+            if (!isUnknownRecord(response) || !Array.isArray(response["data"])) {
+                throw new Error("IBKR returned a malformed market-data history response");
+            }
+            return response;
         }
         catch (error) {
             if (!suppressErrors)
@@ -3887,20 +4350,36 @@ export class IbkrClient {
     }
     /** Typed wrapper around the raw client's untyped `request()`. */
     async sendRequest(input) {
-        return (await this.raw.request(input));
+        try {
+            return (await this.raw.request(input));
+        }
+        catch (error) {
+            throw this.normalizeHttpError(error);
+        }
     }
     req(input) {
-        return this.scheduledRequest(input, true);
+        return this.scheduledRequest(input, "SAFE_READ");
+    }
+    historyRequest(input) {
+        return this.scheduledRequest(input, "PRICE_HISTORY");
     }
     singleAttemptRequest(input) {
-        return this.scheduledRequest(input, false);
+        return this.scheduledRequest(input, "SINGLE_ATTEMPT");
     }
-    scheduledRequest(input, retryable) {
+    scheduledRequest(input, retryPolicy) {
         return this.requestScheduler.schedule({
             endpoint: this.requestEndpoint(input.path),
             priority: this.requestPriority(input.path),
-            retryable,
-        }, () => this.sendRequest(input));
+            retryable: retryPolicy !== "SINGLE_ATTEMPT",
+            retryServerErrors: retryPolicy === "PRICE_HISTORY",
+        }, async () => {
+            try {
+                return await this.sendRequest(input);
+            }
+            catch (error) {
+                throw this.normalizeHttpError(error);
+            }
+        });
     }
     requestPriority(path) {
         if (path === "iserver/accounts" ||
@@ -3936,12 +4415,19 @@ export class IbkrClient {
         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 status = this.httpStatusFromError(error);
+        if (status === 429) {
             const retryAfterMs = this.retryAfterFromError(error);
             return retryAfterMs === undefined
                 ? { kind: "THROTTLED" }
                 : { kind: "THROTTLED", retryAfterMs };
         }
+        if (status !== undefined && status >= 500 && status <= 599) {
+            const retryAfterMs = this.retryAfterFromError(error);
+            return retryAfterMs === undefined
+                ? { kind: "SERVER_ERROR" }
+                : { kind: "SERVER_ERROR", retryAfterMs };
+        }
         return { kind: "OTHER" };
     }
     requestErrorText(error) {
@@ -3968,6 +4454,48 @@ export class IbkrClient {
         })
             .join(" ");
     }
+    normalizeHttpError(error) {
+        if (error instanceof IbkrHttpError)
+            return error;
+        const status = this.httpStatusFromError(error);
+        if (status === undefined)
+            return error;
+        const body = this.httpResponseBody(error);
+        const retryAfter = this.retryAfterHeaderFromError(error) ?? null;
+        const message = body !== ""
+            ? `IBKR HTTP ${String(status)}: ${body}`
+            : error instanceof Error
+                ? error.message.slice(0, 4_096)
+                : `IBKR HTTP ${String(status)}`;
+        return new IbkrHttpError(message, status, { status, body, retryAfter }, { cause: error });
+    }
+    httpResponseBody(error) {
+        if (typeof error !== "object" || error === null)
+            return "";
+        const response = error.response;
+        const responseData = typeof response === "object" && response !== null
+            ? (response.data ??
+                response.body)
+            : undefined;
+        const directBody = error.body;
+        const message = error.message;
+        const rawBody = responseData ?? directBody ?? this.bodyFromRawTransportMessage(message);
+        if (typeof rawBody === "string")
+            return rawBody.slice(0, 4_096);
+        if (rawBody === undefined)
+            return "";
+        try {
+            return JSON.stringify(rawBody).slice(0, 4_096);
+        }
+        catch {
+            return "";
+        }
+    }
+    bodyFromRawTransportMessage(message) {
+        if (typeof message !== "string")
+            return undefined;
+        return /^Response status \d{3}: ([\s\S]*)$/.exec(message)?.[1];
+    }
     httpStatusFromError(error) {
         if (typeof error !== "object" || error === null)
             return undefined;
@@ -3979,18 +4507,24 @@ export class IbkrClient {
         if (directStatusCode !== undefined)
             return directStatusCode;
         if (typeof response === "object" && response !== null) {
-            return this.numberFromUnknown(response.status ??
+            const responseStatus = this.numberFromUnknown(response.status ??
                 response.statusCode);
+            if (responseStatus !== undefined)
+                return responseStatus;
         }
         const message = error.message;
-        if (typeof message === "string") {
-            const match = /\b429\b/.exec(message);
-            if (match)
-                return 429;
-        }
-        return undefined;
+        if (typeof message !== "string")
+            return undefined;
+        const rawStatus = /^Response status (\d{3}):/.exec(message)?.[1];
+        return rawStatus === undefined ? undefined : this.numberFromUnknown(rawStatus);
     }
     retryAfterFromError(error) {
+        if (typeof error !== "object" || error === null)
+            return undefined;
+        const structuredRetryAfter = error instanceof IbkrHttpError ? (error.response.retryAfter ?? undefined) : undefined;
+        return parseRetryAfter(structuredRetryAfter ?? this.retryAfterHeaderFromError(error), this.requestNow());
+    }
+    retryAfterHeaderFromError(error) {
         if (typeof error !== "object" || error === null)
             return undefined;
         const response = error.response;
@@ -3998,9 +4532,8 @@ export class IbkrClient {
             ? response.headers
             : undefined;
         const directHeaders = error.headers;
-        const retryAfterRaw = this.headerValue(responseHeaders, "Retry-After") ??
-            this.headerValue(directHeaders, "Retry-After");
-        return parseRetryAfter(retryAfterRaw);
+        return (this.headerValue(responseHeaders, "Retry-After") ??
+            this.headerValue(directHeaders, "Retry-After"));
     }
     numberFromUnknown(value) {
         if (typeof value === "number")