@huskly/ibkr-client 1.3.0 → 1.4.0

package/dist/ibkr/ibkrClient.js

@@ -99,6 +99,77 @@ function parseRetryAfter(raw, now) {
 function isUnknownRecord(input) {
     return typeof input === "object" && input !== null && !Array.isArray(input);
 }
+/**
+ * Every distinct listing of an exact symbol that carries a section of one asset class (#671).
+ *
+ * Duplicate conids collapse: IBKR repeats a listing across sections, and the same contract twice
+ * is one candidate, not an ambiguity. A symbol that does not match exactly is never a candidate,
+ * because a foreign listing under a different ticker is a different instrument.
+ */
+function secdefListings(search, symbol, assetClass) {
+    const requested = symbol.trim().toUpperCase();
+    const wanted = assetClass.trim().toUpperCase();
+    const listings = search.flatMap((item) => {
+        if (item.symbol?.trim().toUpperCase() !== requested)
+            return [];
+        const conid = Number(item.conid);
+        if (!Number.isSafeInteger(conid) || conid <= 0)
+            return [];
+        const sections = Array.isArray(item.sections) ? item.sections : [];
+        const matched = sections.filter((section) => section.secType?.trim().toUpperCase() === wanted);
+        if (matched.length === 0)
+            return [];
+        const exchanges = [
+            ...new Set(matched.flatMap((section) => (section.exchange ?? "")
+                .split(";")
+                .map((name) => name.trim().toUpperCase())
+                .filter(Boolean))),
+        ];
+        // An empty label is no label, so it falls through to the next source rather than becoming
+        // an empty description in an operator message.
+        const labels = [item.companyHeader?.trim(), item.description?.trim()];
+        const description = labels.find((label) => label !== undefined && label !== "") ?? null;
+        return [
+            {
+                conid,
+                symbol: requested,
+                supportsSmartOptions: supportsSmartOptions(sections),
+                exchanges,
+                description,
+            },
+        ];
+    });
+    return [...new Map(listings.map((listing) => [listing.conid, listing])).values()];
+}
+/** The listings that route options on SMART, which is the US listing a caller means. */
+function smartOptionListings(listings) {
+    return listings.filter((listing) => listing.supportsSmartOptions);
+}
+/**
+ * Narrow listings to the SMART-routed one, keeping them all when none routes SMART (#671).
+ *
+ * The fallback matters: futures options and other non-SMART series never advertise SMART, and
+ * dropping every candidate there would refuse a symbol that is not ambiguous at all.
+ */
+function preferSmartOptionListings(listings) {
+    const smart = smartOptionListings(listings);
+    return smart.length > 0 ? smart : [...listings];
+}
+/**
+ * Name the competing listings so an operator can pass an explicit `tradingClass` or conid (#671).
+ *
+ * It reports the conid, IBKR's description, and the exchanges of each listing. It carries no
+ * account identity, no order identity, and no credentials.
+ */
+function describeSecdefListings(listings) {
+    return listings
+        .map((listing) => {
+        const venue = listing.exchanges.length > 0 ? listing.exchanges.join("/") : "no exchange";
+        const description = listing.description === null ? "" : ` ${listing.description}`;
+        return `conid ${String(listing.conid)}${description} (${venue})`;
+    })
+        .join("; ");
+}
 function supportsSmartOptions(sections) {
     if (!Array.isArray(sections))
         return false;
@@ -201,6 +272,59 @@ function monthCodes(fromDate, toDate) {
     }
     return result;
 }
+/** Refuse a band that is not made of finite numbers, or that can never select a strike. */
+function normalizeStrikeRange(range) {
+    if (range === undefined)
+        return undefined;
+    const { min, max } = range;
+    if (min !== undefined && !Number.isFinite(min)) {
+        throw new TypeError("Option strike range min must be a finite number");
+    }
+    if (max !== undefined && !Number.isFinite(max)) {
+        throw new TypeError("Option strike range max must be a finite number");
+    }
+    if (min !== undefined && max !== undefined && min > max) {
+        throw new TypeError(`Option strike range min ${String(min)} is above max ${String(max)}`);
+    }
+    if (min === undefined && max === undefined)
+        return undefined;
+    return range;
+}
+/** One stable memo token for a band, so a narrowed result cannot answer a wider request. */
+function strikeRangeKey(range) {
+    if (range === undefined)
+        return "*";
+    return `${String(range.min ?? "-inf")}..${String(range.max ?? "+inf")}`;
+}
+/** A strike that IBKR does not report as a finite number is never selected. */
+function strikeInRange(strike, range) {
+    if (!Number.isFinite(strike))
+        return false;
+    if (range === undefined)
+        return true;
+    if (range.min !== undefined && strike < range.min)
+        return false;
+    if (range.max !== undefined && strike > range.max)
+        return false;
+    return true;
+}
+/** A cached record is used only when it is a whole contract and it answers the key it is filed under. */
+function isCachedOptionContract(value, key) {
+    if (!isUnknownRecord(value))
+        return false;
+    const { conid, symbol, underlying, expiry, strike, right } = value;
+    return (typeof conid === "number" &&
+        Number.isFinite(conid) &&
+        typeof symbol === "string" &&
+        symbol.length > 0 &&
+        typeof underlying === "string" &&
+        underlying.length > 0 &&
+        typeof expiry === "string" &&
+        expiry.length > 0 &&
+        typeof strike === "number" &&
+        strike === key.strike &&
+        right === key.right);
+}
 /** A typed HTTP failure from the IBKR transport. */
 export class IbkrHttpError extends Error {
     status;
@@ -266,6 +390,7 @@ export class IbkrClient {
     initPromise;
     accountIdPromise;
     optionDiscovery = new Map();
+    optionDefinitionCache;
     optionContractResolution = new Map();
     priceHistoryContractResolution = new Map();
     derivativeDiscovery = new Map();
@@ -279,6 +404,7 @@ export class IbkrClient {
         this.raw = new RawIbkrClientCtor(config);
         this.onPriceHistoryTelemetry = options.onPriceHistoryTelemetry ?? (() => undefined);
         this.onOptionDiscoveryTelemetry = options.onOptionDiscoveryTelemetry ?? (() => undefined);
+        this.optionDefinitionCache = options.optionDefinitionCache;
         this.onRequestTelemetry = options.onRequestTelemetry ?? (() => undefined);
         const schedulerOptions = options.requestScheduler;
         this.requestNow = schedulerOptions?.now ?? (() => this.now());
@@ -3036,12 +3162,12 @@ export class IbkrClient {
         if (!requestedSymbol)
             return undefined;
         const search = await this.searchSecdef({ symbol: requestedSymbol });
-        const optionable = this.quoteContractConids(requestedSymbol, search, (item) => supportsSmartOptions(item.sections));
+        const optionable = smartOptionListings(secdefListings(search, requestedSymbol, "OPT"));
         if (optionable.length > 1)
             return undefined;
-        const [optionableConid] = optionable;
-        if (optionableConid !== undefined) {
-            return { requestedSymbol: symbol, symbol: requestedSymbol, conid: optionableConid };
+        const [optionableListing] = optionable;
+        if (optionableListing !== undefined) {
+            return { requestedSymbol: symbol, symbol: requestedSymbol, conid: optionableListing.conid };
         }
         // `trsrv/stocks` is equity/ETF-only, so a symbol with no SMART options can still be a plain
         // stock or ETF that the security-definition search does not describe as optionable.
@@ -3160,16 +3286,7 @@ export class IbkrClient {
             });
         }
         const search = await this.searchSecdef({ symbol: requestedSymbol });
-        const smartOptionConids = new Set(search.flatMap((item) => {
-            const symbol = item.symbol?.trim().toUpperCase();
-            const conid = Number(item.conid);
-            return symbol === requestedSymbol &&
-                Number.isSafeInteger(conid) &&
-                conid > 0 &&
-                supportsSmartOptions(item.sections)
-                ? [conid]
-                : [];
-        }));
+        const smartOptionConids = new Set(smartOptionListings(secdefListings(search, requestedSymbol, "OPT")).map((listing) => listing.conid));
         const candidates = search.flatMap((item) => {
             const symbol = item.symbol?.trim().toUpperCase();
             const conid = Number(item.conid);
@@ -3560,24 +3677,20 @@ export class IbkrClient {
             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));
+        // Order placement resolves its legs through here, so it narrows the search exactly as option
+        // discovery does. Without it a ticker that also names a Canadian Depositary Receipt, such as
+        // `UNH` or `NFLX`, refuses every order for a listing it does not trade (#671).
+        const listings = secdefListings(search, underlying, assetClass);
+        const candidates = preferSmartOptionListings(listings);
         if (candidates.length !== 1) {
-            throw new Error(`IBKR ${assetClass} underlying identity is ${candidates.length ? "ambiguous" : "missing"} for ${underlying}`);
+            const detail = candidates.length > 1 ? `; competing listings: ${describeSecdefListings(candidates)}` : "";
+            throw new Error(`IBKR ${assetClass} underlying identity is ${candidates.length ? "ambiguous" : "missing"} for ${underlying}${detail}`);
         }
         const candidate = candidates[0];
         if (!candidate)
             throw new Error(`IBKR lost the selected underlying for ${underlying}`);
-        const conid = Number(candidate.conid);
-        if (!Number.isSafeInteger(conid) || conid <= 0) {
-            throw new Error(`IBKR returned an invalid underlying contract id for ${underlying}`);
-        }
-        const section = candidate.sections?.find((item) => item.secType?.toUpperCase() === assetClass);
-        const exchanges = (section?.exchange ?? "")
-            .split(";")
-            .map((value) => value.trim().toUpperCase())
-            .filter(Boolean);
+        const conid = candidate.conid;
+        const exchanges = candidate.exchanges;
         if (requestedExchange && !exchanges.includes(requestedExchange)) {
             throw new Error(`IBKR does not list ${underlying} ${assetClass} discovery on ${requestedExchange}`);
         }
@@ -3666,16 +3779,24 @@ export class IbkrClient {
     }
     discoverOptions(symbol, month, right, options = {}) {
         const normalized = symbol.trim().toUpperCase();
+        const strikeRange = normalizeStrikeRange(options.strikeRange);
+        const discoveryOptions = {
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(strikeRange === undefined ? {} : { strikeRange }),
+        };
         if (options.signal !== undefined) {
-            return this.loadOptionContracts(normalized, month, right, options.signal);
+            return this.loadOptionContracts(normalized, month, right, discoveryOptions);
         }
-        const key = `${normalized}:${month}:${right ?? "*"}`;
+        // The band belongs in the memo key. A narrowed result holds only part of the month, so it must
+        // never answer a later request for a different band.
+        const bandKey = strikeRangeKey(strikeRange);
+        const key = `${normalized}:${month}:${right ?? "*"}:${bandKey}`;
         const cached = this.optionDiscovery.get(key);
         if (cached !== undefined)
             return cached;
         let discovery;
         if (right !== undefined) {
-            const complete = this.optionDiscovery.get(`${normalized}:${month}:*`);
+            const complete = this.optionDiscovery.get(`${normalized}:${month}:*:${bandKey}`);
             if (complete !== undefined) {
                 discovery = complete.then((result) => ({
                     contracts: result.contracts.filter((contract) => contract.right === right),
@@ -3683,7 +3804,7 @@ export class IbkrClient {
                 }));
             }
         }
-        discovery ??= this.loadOptionContracts(normalized, month, right);
+        discovery ??= this.loadOptionContracts(normalized, month, right, discoveryOptions);
         const pending = discovery.catch((error) => {
             if (this.optionDiscovery.get(key) === pending)
                 this.optionDiscovery.delete(key);
@@ -3699,39 +3820,19 @@ export class IbkrClient {
             path: "iserver/secdef/search",
             params: { symbol },
         }, signal));
-        const candidates = search.flatMap((item) => {
-            if (!isUnknownRecord(item))
-                return [];
-            const candidateSymbol = item["symbol"];
-            if (typeof candidateSymbol !== "string" || candidateSymbol.trim().toUpperCase() !== symbol) {
-                return [];
-            }
-            const sections = item["sections"];
-            if (!Array.isArray(sections))
-                return [];
-            const hasOptions = sections.some((section) => isUnknownRecord(section) &&
-                typeof section["secType"] === "string" &&
-                section["secType"].trim().toUpperCase() === "OPT");
-            if (!hasOptions)
-                return [];
-            const supportsSmart = supportsSmartOptions(sections);
-            const conid = Number(item["conid"]);
-            return Number.isSafeInteger(conid) && conid > 0 ? [{ conid, symbol, supportsSmart }] : [];
-        });
-        const unique = [
-            ...new Map(candidates.map((candidate) => [candidate.conid, candidate])).values(),
-        ];
-        const smart = unique.filter((candidate) => candidate.supportsSmart);
-        const eligible = smart.length > 0 ? smart : unique;
+        const eligible = preferSmartOptionListings(secdefListings(search, symbol, "OPT"));
         if (eligible.length !== 1) {
-            throw new Error(`IBKR option underlying identity is ${eligible.length ? "ambiguous" : "missing"} for ${symbol}`);
+            const detail = eligible.length > 1 ? `; competing listings: ${describeSecdefListings(eligible)}` : "";
+            throw new Error(`IBKR option underlying identity is ${eligible.length ? "ambiguous" : "missing"} for ${symbol}${detail}`);
         }
         const [underlying] = eligible;
         if (underlying === undefined)
             throw new Error(`IBKR lost the selected underlying for ${symbol}`);
-        return underlying;
+        return { conid: underlying.conid, symbol };
     }
-    async loadOptionContracts(symbol, month, right, callerSignal) {
+    async loadOptionContracts(symbol, month, right, options = {}) {
+        const callerSignal = options.signal;
+        const strikeRange = normalizeStrikeRange(options.strikeRange);
         const operation = new AbortController();
         const abortFromCaller = () => {
             operation.abort(callerSignal?.reason);
@@ -3741,7 +3842,7 @@ export class IbkrClient {
         else
             callerSignal?.addEventListener("abort", abortFromCaller, { once: true });
         try {
-            const { underlying, requests } = await this.withSecdefPriming(async () => {
+            const { underlying, requests, listedStrikeCount } = await this.withSecdefPriming(async () => {
                 const searchStarted = this.requestNow();
                 const selectedUnderlying = await this.loadOptionUnderlying(symbol, operation.signal);
                 this.emitOptionDiscoveryTelemetry({
@@ -3750,29 +3851,19 @@ export class IbkrClient {
                     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 },
                 }, operation.signal);
-                this.emitOptionDiscoveryTelemetry({
-                    phase: "STRIKES",
-                    symbol,
-                    month,
-                    right: right ?? null,
-                    durationMs: this.elapsedSince(strikesStarted),
-                    definitionRequestCount: 0,
-                    snapshotBatchCount: 0,
-                });
+                const strikesDurationMs = this.elapsedSince(strikesStarted);
                 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 = [
+                const listed = [
                     ...(right === undefined || right === "C"
                         ? callStrikes.map((strike) => ({ strike, right: "C" }))
                         : []),
@@ -3780,12 +3871,48 @@ export class IbkrClient {
                         ? putStrikes.map((strike) => ({ strike, right: "P" }))
                         : []),
                 ];
-                return { underlying: selectedUnderlying, requests: definitionRequests };
+                // One security definition costs one paced request, so the band is applied here, before any
+                // definition is requested. Applying it later would keep the full cost of the month.
+                const selected = listed.filter(({ strike }) => strikeInRange(strike, strikeRange));
+                this.emitOptionDiscoveryTelemetry({
+                    phase: "STRIKES",
+                    symbol,
+                    month,
+                    right: right ?? null,
+                    durationMs: strikesDurationMs,
+                    listedStrikeCount: listed.length,
+                    selectedStrikeCount: selected.length,
+                });
+                // A band that keeps nothing is a caller mistake, not an empty chain. Reporting it as an
+                // empty result would look like an unlisted expiry.
+                if (listed.length > 0 && selected.length === 0) {
+                    throw new Error(`IBKR option strike range [${String(strikeRange?.min ?? "-inf")}, ` +
+                        `${String(strikeRange?.max ?? "+inf")}] selected none of the ` +
+                        `${String(listed.length)} listed strikes for ${symbol} ${month}`);
+                }
+                return {
+                    underlying: selectedUnderlying,
+                    requests: selected,
+                    listedStrikeCount: listed.length,
+                };
             });
             const definitionsStarted = this.requestNow();
             const contracts = [];
             let malformedDefinitionCount = 0;
-            for (const batch of chunks(requests, OPTION_SECDEF_INFO_BATCH_SIZE)) {
+            const cached = await this.readCachedOptionDefinitions(underlying.conid, month, requests);
+            const pending = [];
+            let cachedDefinitionCount = 0;
+            for (const [position, request] of requests.entries()) {
+                const hit = cached[position];
+                if (hit === undefined || hit === null) {
+                    pending.push(request);
+                    continue;
+                }
+                cachedDefinitionCount += 1;
+                contracts.push(...hit);
+            }
+            const resolved = [];
+            for (const batch of chunks(pending, OPTION_SECDEF_INFO_BATCH_SIZE)) {
                 let responses;
                 try {
                     responses = await Promise.all(batch.map(({ strike, right: requestRight }) => this.req({
@@ -3805,13 +3932,17 @@ export class IbkrClient {
                     operation.abort(error);
                     throw error;
                 }
-                for (const response of responses) {
+                for (const [position, response] of responses.entries()) {
                     if (!Array.isArray(response)) {
                         throw new Error(`IBKR returned malformed option definitions for ${symbol} ${month}`);
                     }
+                    const request = batch[position];
+                    const resolvedForRequest = [];
+                    let requestHadMalformedRecord = false;
                     for (const raw of response) {
                         if (!isUnknownRecord(raw)) {
                             malformedDefinitionCount += 1;
+                            requestHadMalformedRecord = true;
                             continue;
                         }
                         let contract;
@@ -3828,23 +3959,43 @@ export class IbkrClient {
                         }
                         catch {
                             malformedDefinitionCount += 1;
+                            requestHadMalformedRecord = true;
                             continue;
                         }
                         if (contract)
-                            contracts.push(contract);
-                        else
+                            resolvedForRequest.push(contract);
+                        else {
                             malformedDefinitionCount += 1;
+                            requestHadMalformedRecord = true;
+                        }
+                    }
+                    contracts.push(...resolvedForRequest);
+                    // A partial answer is never stored. A later run must ask the broker again rather than
+                    // read a record that already lost contracts.
+                    if (request !== undefined && !requestHadMalformedRecord) {
+                        resolved.push({
+                            key: {
+                                underlyingConid: underlying.conid,
+                                month,
+                                right: request.right,
+                                strike: request.strike,
+                            },
+                            contracts: resolvedForRequest,
+                        });
                     }
                 }
             }
+            await this.writeCachedOptionDefinitions(resolved);
             this.emitOptionDiscoveryTelemetry({
                 phase: "DEFINITIONS",
                 symbol,
                 month,
                 right: right ?? null,
                 durationMs: this.elapsedSince(definitionsStarted),
-                definitionRequestCount: requests.length,
-                snapshotBatchCount: 0,
+                definitionRequestCount: pending.length,
+                listedStrikeCount,
+                selectedStrikeCount: requests.length,
+                cachedDefinitionCount,
             });
             if (requests.length === 0)
                 return { contracts: [], malformedDefinitionCount: 0 };
@@ -3858,6 +4009,59 @@ export class IbkrClient {
             callerSignal?.removeEventListener("abort", abortFromCaller);
         }
     }
+    /**
+     * Read one definition for each request from the cache, aligned by index.
+     *
+     * Every failure mode collapses to "miss": no cache, a rejected read, a misaligned result, or a
+     * record that is not a valid contract for the key it answers. The broker is then asked, so a bad
+     * cache costs time and never changes an answer.
+     */
+    async readCachedOptionDefinitions(underlyingConid, month, requests) {
+        const cache = this.optionDefinitionCache;
+        if (cache === undefined || requests.length === 0)
+            return requests.map(() => null);
+        const keys = requests.map(({ strike, right }) => ({
+            underlyingConid,
+            month,
+            right,
+            strike,
+        }));
+        // The result is treated as untrusted data, not as the declared type. An implementation that
+        // returns the wrong shape must degrade to a miss, never to a fabricated contract.
+        let answer;
+        try {
+            answer = await cache.get(keys);
+        }
+        catch {
+            return requests.map(() => null);
+        }
+        if (!Array.isArray(answer) || answer.length !== keys.length)
+            return requests.map(() => null);
+        const records = answer;
+        return keys.map((key, position) => {
+            const record = records[position];
+            if (record === null || record === undefined)
+                return null;
+            if (!Array.isArray(record))
+                return null;
+            const cachedContracts = record;
+            if (!cachedContracts.every((contract) => isCachedOptionContract(contract, key)))
+                return null;
+            return cachedContracts;
+        });
+    }
+    /** Store resolved definitions. A store failure is never fatal: the identity came from IBKR. */
+    async writeCachedOptionDefinitions(entries) {
+        const cache = this.optionDefinitionCache;
+        if (cache === undefined || entries.length === 0)
+            return;
+        try {
+            await cache.set(entries);
+        }
+        catch {
+            // A cache is an accelerator. Discovery already holds the broker answer.
+        }
+    }
     async fetchOptionChainSnapshot(contracts, malformedDefinitionCount, telemetry, signal) {
         const fields = [
             "bid",
@@ -3990,6 +4194,11 @@ export class IbkrClient {
         try {
             const result = this.onOptionDiscoveryTelemetry({
                 event: "OPTION_DISCOVERY_PHASE",
+                definitionRequestCount: 0,
+                snapshotBatchCount: 0,
+                listedStrikeCount: 0,
+                selectedStrikeCount: 0,
+                cachedDefinitionCount: 0,
                 ...event,
             });
             void Promise.resolve(result).catch(() => undefined);