@huskly/ibkr-client 1.0.0 → 1.1.1

package/dist/ibkr/ibkrClient.js

@@ -259,10 +259,12 @@ export class IbkrClient {
     requestNow;
     secdefPrimingTail = Promise.resolve();
     onPriceHistoryTelemetry;
+    onOptionDiscoveryTelemetry;
     onRequestTelemetry;
     constructor(config, options = {}) {
         this.raw = new RawIbkrClientCtor(config);
         this.onPriceHistoryTelemetry = options.onPriceHistoryTelemetry ?? (() => undefined);
+        this.onOptionDiscoveryTelemetry = options.onOptionDiscoveryTelemetry ?? (() => undefined);
         this.onRequestTelemetry = options.onRequestTelemetry ?? (() => undefined);
         const schedulerOptions = options.requestScheduler;
         this.requestNow = schedulerOptions?.now ?? (() => this.now());
@@ -3283,8 +3285,8 @@ export class IbkrClient {
         const contracts = [];
         for (let index = 0; index < months.length; index += OPTION_DISCOVERY_MONTH_CONCURRENCY) {
             const batch = months.slice(index, index + OPTION_DISCOVERY_MONTH_CONCURRENCY);
-            const batchContracts = (await Promise.all(batch.map((month) => this.discoverOptions(normalized, month)))).flat();
-            contracts.push(...batchContracts);
+            const batchContracts = await Promise.all(batch.map((month) => this.discoverOptions(normalized, month, right)));
+            contracts.push(...batchContracts.flatMap((result) => result.contracts));
         }
         return [
             ...new Set(contracts
@@ -3293,17 +3295,38 @@ export class IbkrClient {
         ].sort();
     }
     /** Build one exact-expiry chain with canonical OSI symbols and required pricing/greeks. */
-    async getOptionChain(symbol, expiry) {
-        const contracts = (await this.discoverOptions(symbol, monthCode(expiry))).filter((contract) => contract.expiry === expiry);
+    async getOptionChain(symbol, expiry, right) {
+        const month = monthCode(expiry);
+        const normalized = symbol.trim().toUpperCase();
+        const discovery = await this.discoverOptions(normalized, month, right);
+        const contracts = discovery.contracts.filter((contract) => contract.expiry === expiry && (right === undefined || contract.right === right));
         if (!contracts.length) {
             throw new Error(`IBKR returned no option contracts for ${symbol} ${expiry}`);
         }
-        const quoted = await this.fetchOptionQuotes(contracts, { allowIncomplete: true });
+        const quoted = await this.fetchOptionQuotes(contracts, {
+            allowIncomplete: true,
+            telemetry: { symbol: normalized, month, right: right ?? null },
+        });
         if (!quoted.length) {
             throw new Error(`IBKR returned no usable option quotes for ${symbol} ${expiry}`);
         }
         return quoted;
     }
+    /** Return every qualified contract for one exact expiry and side without hiding sparse data. */
+    async getOptionChainSnapshot(symbol, expiry, right) {
+        const month = monthCode(expiry);
+        const normalized = symbol.trim().toUpperCase();
+        const discovery = await this.discoverOptions(normalized, month, right);
+        const contracts = discovery.contracts.filter((contract) => contract.expiry === expiry);
+        if (!contracts.length) {
+            throw new Error(`IBKR returned no ${right} option contracts for ${symbol} ${expiry}`);
+        }
+        return this.fetchOptionChainSnapshot(contracts, discovery.malformedDefinitionCount, {
+            symbol: normalized,
+            month,
+            right,
+        });
+    }
     /** Fetch one exact option quote; null means the contract is not listed. */
     async getOptionQuote(input) {
         const contract = await this.resolveOptionContract(input);
@@ -3556,14 +3579,21 @@ export class IbkrClient {
         }
         return result;
     }
-    discoverOptions(symbol, month) {
+    discoverOptions(symbol, month, right) {
         const normalized = symbol.trim().toUpperCase();
-        const key = `${normalized}:${month}`;
+        const key = `${normalized}:${month}:${right ?? "*"}`;
         let pending = this.optionDiscovery.get(key);
-        if (!pending) {
-            pending = this.loadOptionContracts(normalized, month);
-            this.optionDiscovery.set(key, pending);
+        if (!pending && right !== undefined) {
+            const complete = this.optionDiscovery.get(`${normalized}:${month}:*`);
+            if (complete !== undefined) {
+                pending = complete.then((result) => ({
+                    contracts: result.contracts.filter((contract) => contract.right === right),
+                    malformedDefinitionCount: result.malformedDefinitionCount,
+                }));
+            }
         }
+        pending ??= this.loadOptionContracts(normalized, month, right);
+        this.optionDiscovery.set(key, pending);
         return pending;
     }
     async loadOptionUnderlying(symbol) {
@@ -3611,97 +3641,211 @@ export class IbkrClient {
             throw new Error(`IBKR lost the selected underlying for ${symbol}`);
         return underlying;
     }
-    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 },
+    async loadOptionContracts(symbol, month, right) {
+        const { underlying, requests } = await this.withSecdefPriming(async () => {
+            const searchStarted = this.requestNow();
+            const selectedUnderlying = await this.loadOptionUnderlying(symbol);
+            this.emitOptionDiscoveryTelemetry({
+                phase: "SEARCH",
+                symbol,
+                month,
+                right: right ?? null,
+                durationMs: this.elapsedSince(searchStarted),
+                definitionRequestCount: 0,
+                snapshotBatchCount: 0,
+            });
+            const strikesStarted = this.requestNow();
+            const strikes = await this.req({
+                path: "iserver/secdef/strikes",
+                params: { conid: String(selectedUnderlying.conid), sectype: "OPT", month },
+            });
+            this.emitOptionDiscoveryTelemetry({
+                phase: "STRIKES",
+                symbol,
+                month,
+                right: right ?? null,
+                durationMs: this.elapsedSince(strikesStarted),
+                definitionRequestCount: 0,
+                snapshotBatchCount: 0,
+            });
+            const callStrikes = strikes.call ?? [];
+            const putStrikes = strikes.put ?? [];
+            if (callStrikes.length === 0 && putStrikes.length === 0) {
+                throw new Error(`IBKR returned empty option strikes for ${symbol} ${month} after secdef/search priming`);
+            }
+            const definitionRequests = [
+                ...(right === undefined || right === "C"
+                    ? callStrikes.map((strike) => ({ strike, right: "C" }))
+                    : []),
+                ...(right === undefined || right === "P"
+                    ? putStrikes.map((strike) => ({ strike, right: "P" }))
+                    : []),
+            ];
+            return { underlying: selectedUnderlying, requests: definitionRequests };
         });
-        const requests = [
-            ...(strikes.call ?? []).map((strike) => ({ strike, right: "C" })),
-            ...(strikes.put ?? []).map((strike) => ({ strike, right: "P" })),
-        ];
-        if (!requests.length) {
-            throw new Error(`IBKR returned empty option strikes for ${symbol} ${month} after secdef/search priming`);
-        }
+        const definitionsStarted = this.requestNow();
+        const responses = await Promise.all(requests.map(({ strike, right: requestRight }) => this.req({
+            path: "iserver/secdef/info",
+            params: {
+                conid: String(underlying.conid),
+                sectype: "OPT",
+                month,
+                strike,
+                right: requestRight,
+            },
+        })));
+        this.emitOptionDiscoveryTelemetry({
+            phase: "DEFINITIONS",
+            symbol,
+            month,
+            right: right ?? null,
+            durationMs: this.elapsedSince(definitionsStarted),
+            definitionRequestCount: requests.length,
+            snapshotBatchCount: 0,
+        });
+        if (requests.length === 0)
+            return { contracts: [], malformedDefinitionCount: 0 };
         const contracts = [];
-        for (const batch of chunks(requests, OPTION_SECDEF_INFO_BATCH_SIZE)) {
-            const responses = await Promise.all(batch.map(({ strike, right }) => this.req({
-                path: "iserver/secdef/info",
-                params: {
-                    conid: String(underlying.conid),
-                    sectype: "OPT",
-                    month,
-                    strike,
-                    right,
-                },
-            })));
-            for (const raw of responses.flat()) {
-                const contract = normalizeOptionContract({
-                    conid: raw.conid,
-                    symbol: raw.symbol ?? underlying.symbol,
-                    maturityDate: raw.maturityDate,
-                    right: raw.right,
-                    strike: raw.strike,
-                });
+        let malformedDefinitionCount = 0;
+        for (const response of responses) {
+            if (!Array.isArray(response)) {
+                throw new Error(`IBKR returned malformed option definitions for ${symbol} ${month}`);
+            }
+            for (const raw of response) {
+                if (!isUnknownRecord(raw)) {
+                    malformedDefinitionCount += 1;
+                    continue;
+                }
+                let contract;
+                try {
+                    contract = normalizeOptionContract({
+                        conid: typeof raw["conid"] === "number" ? raw["conid"] : undefined,
+                        symbol: typeof raw["symbol"] === "string" ? raw["symbol"] : underlying.symbol,
+                        maturityDate: typeof raw["maturityDate"] === "string" ? raw["maturityDate"] : undefined,
+                        right: typeof raw["right"] === "string" ? raw["right"] : undefined,
+                        strike: typeof raw["strike"] === "string" || typeof raw["strike"] === "number"
+                            ? raw["strike"]
+                            : undefined,
+                    });
+                }
+                catch {
+                    malformedDefinitionCount += 1;
+                    continue;
+                }
                 if (contract)
                     contracts.push(contract);
+                else
+                    malformedDefinitionCount += 1;
             }
         }
         const unique = [...new Map(contracts.map((contract) => [contract.conid, contract])).values()];
         if (!unique.length) {
-            throw new Error(`IBKR returned no usable option definitions for ${symbol} ${month}`);
+            throw new Error(`IBKR returned no usable option definitions for ${symbol} ${month} (${String(malformedDefinitionCount)} malformed)`);
+        }
+        return { contracts: unique, malformedDefinitionCount };
+    }
+    async fetchOptionChainSnapshot(contracts, malformedDefinitionCount, telemetry) {
+        const fields = [
+            "bid",
+            "ask",
+            "mid",
+            "delta",
+            "volume",
+            "openInterest",
+            "availability",
+            "timestamp",
+        ];
+        const missingFieldCounts = Object.fromEntries(fields.map((field) => [field, 0]));
+        const quotes = await this.fetchNullableOptionQuotes(contracts, telemetry);
+        for (const quote of quotes) {
+            for (const field of fields) {
+                if (quote[field] === null)
+                    missingFieldCounts[field] += 1;
+            }
         }
-        return unique;
+        const diagnostics = {
+            qualifiedCount: contracts.length,
+            returnedCount: quotes.length,
+            malformedDefinitionCount,
+            missingFieldCounts,
+        };
+        return { quotes, diagnostics };
     }
-    async fetchOptionQuotes(contracts, options = {}) {
-        const { allowIncomplete = false } = options;
-        const result = [];
-        const skipped = [];
-        for (const batch of chunks(contracts, OPTION_MARKETDATA_BATCH_SIZE)) {
+    async fetchNullableOptionQuotes(contracts, telemetry) {
+        const quotes = [];
+        const batches = chunks(contracts, OPTION_MARKETDATA_BATCH_SIZE);
+        const snapshotsStarted = this.requestNow();
+        for (const batch of batches) {
             const params = {
                 conids: batch.map((contract) => contract.conid).join(","),
                 fields: OPTION_QUOTE_FIELDS,
             };
             await this.req({ path: "iserver/marketdata/snapshot", params });
             await this.wait(2000);
-            const snapshots = await this.req({
+            const response = await this.req({
                 path: "iserver/marketdata/snapshot",
                 params,
             });
-            const byConid = new Map(snapshots
-                .filter((snapshot) => snapshot.conid !== undefined)
-                .map((snapshot) => [snapshot.conid, snapshot]));
+            if (!Array.isArray(response)) {
+                throw new Error("IBKR returned malformed option market-data snapshots");
+            }
+            const snapshots = response.filter((snapshot) => isUnknownRecord(snapshot) &&
+                typeof snapshot["conid"] === "number" &&
+                Number.isSafeInteger(snapshot["conid"]) &&
+                snapshot["conid"] > 0);
+            const byConid = new Map(snapshots.map((snapshot) => [snapshot.conid, snapshot]));
             for (const contract of batch) {
                 const snapshot = byConid.get(contract.conid);
-                const bid = snapshot ? this.snapshotNumber(snapshot, "84") : undefined;
-                const ask = snapshot ? this.snapshotNumber(snapshot, "86") : undefined;
-                const delta = snapshot ? this.snapshotNumber(snapshot, "7308") : undefined;
-                if (bid === undefined || ask === undefined || delta === undefined) {
-                    if (allowIncomplete) {
-                        skipped.push(contract.symbol);
-                        continue;
-                    }
-                    throw new Error(`IBKR returned incomplete option market data for ${contract.symbol} (bid/ask/delta required)`);
-                }
-                const volume = snapshot ? (this.snapshotVolume(snapshot) ?? null) : null;
-                const openInterest = snapshot ? (this.snapshotNumber(snapshot, "7638") ?? null) : null;
-                result.push({
+                const bid = snapshot ? (this.snapshotNumber(snapshot, "84") ?? null) : null;
+                const ask = snapshot ? (this.snapshotNumber(snapshot, "86") ?? null) : null;
+                const rawAvailability = snapshot?.["6509"];
+                quotes.push({
                     ...contract,
                     bid,
                     ask,
-                    mid: (bid + ask) / 2,
-                    delta,
-                    volume,
-                    openInterest,
-                    availability: normalizeDerivativeDataAvailability(snapshot?.["6509"]),
+                    mid: bid !== null && ask !== null ? (bid + ask) / 2 : null,
+                    delta: snapshot ? (this.snapshotNumber(snapshot, "7308") ?? null) : null,
+                    volume: snapshot ? (this.snapshotVolume(snapshot) ?? null) : null,
+                    openInterest: snapshot ? (this.snapshotNumber(snapshot, "7638") ?? null) : null,
+                    availability: typeof rawAvailability === "string" || typeof rawAvailability === "number"
+                        ? normalizeDerivativeDataAvailability(rawAvailability)
+                        : null,
                     timestamp: snapshot ? this.snapshotTimestamp(snapshot) : null,
                 });
             }
         }
+        if (telemetry !== undefined) {
+            this.emitOptionDiscoveryTelemetry({
+                phase: "SNAPSHOTS",
+                ...telemetry,
+                durationMs: this.elapsedSince(snapshotsStarted),
+                definitionRequestCount: 0,
+                snapshotBatchCount: batches.length,
+            });
+        }
+        return quotes;
+    }
+    async fetchOptionQuotes(contracts, options = {}) {
+        const { allowIncomplete = false, telemetry } = options;
+        const result = [];
+        const skipped = [];
+        for (const quote of await this.fetchNullableOptionQuotes(contracts, telemetry)) {
+            if (quote.bid === null || quote.ask === null || quote.delta === null) {
+                if (allowIncomplete) {
+                    skipped.push(quote.symbol);
+                    continue;
+                }
+                throw new Error(`IBKR returned incomplete option market data for ${quote.symbol} (bid/ask/delta required)`);
+            }
+            result.push({
+                ...quote,
+                bid: quote.bid,
+                ask: quote.ask,
+                mid: (quote.bid + quote.ask) / 2,
+                delta: quote.delta,
+                availability: quote.availability ?? "unavailable",
+            });
+        }
         if (allowIncomplete && skipped.length && skipped.length === contracts.length) {
             const symbol = contracts[0]?.underlying ?? "unknown";
             const expiry = contracts[0]?.expiry ?? "unknown";
@@ -3728,6 +3872,21 @@ export class IbkrClient {
         const endDay = this.utcDayStart(input.endDate);
         return { start, end: endDay + DAY_MS - 1, days: (endDay - start) / DAY_MS + 1 };
     }
+    elapsedSince(startedAt) {
+        return Math.max(0, this.requestNow() - startedAt);
+    }
+    emitOptionDiscoveryTelemetry(event) {
+        try {
+            const result = this.onOptionDiscoveryTelemetry({
+                event: "OPTION_DISCOVERY_PHASE",
+                ...event,
+            });
+            void Promise.resolve(result).catch(() => undefined);
+        }
+        catch {
+            // Telemetry observers cannot change discovery or quote settlement.
+        }
+    }
     async requestPriceHistory(contract, requestedSymbol, request) {
         this.onPriceHistoryTelemetry({
             event: "PRICE_HISTORY_REQUEST",
@@ -4370,6 +4529,7 @@ export class IbkrClient {
         return this.requestScheduler.schedule({
             endpoint: this.requestEndpoint(input.path),
             priority: this.requestPriority(input.path),
+            secdefInfo: input.path === "iserver/secdef/info",
             retryable: retryPolicy !== "SINGLE_ATTEMPT",
             retryServerErrors: retryPolicy === "PRICE_HISTORY",
         }, async () => {