@huskly/ibkr-client 1.3.1 → 1.5.0

package/dist/ibkr/ibkrClient.js

@@ -272,6 +272,81 @@ 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;
+}
+/** The first pair of contracts that share one durable symbol, or `null` when every one is unique. */
+function firstSymbolCollision(contracts) {
+    const bySymbol = new Map();
+    for (const contract of contracts) {
+        const seen = bySymbol.get(contract.symbol);
+        if (seen !== undefined)
+            return { symbol: contract.symbol, first: seen, second: contract };
+        bySymbol.set(contract.symbol, contract);
+    }
+    return null;
+}
+/** 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, tradingClass, expiry, strike, right } = value;
+    if (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) {
+        return false;
+    }
+    // The class is part of identity, so a record that predates it, or that lost it, is a miss and
+    // the broker answers. `null` is a stated absence and is accepted; `undefined` is a record shape
+    // this version does not recognize.
+    if (tradingClass !== null && (typeof tradingClass !== "string" || tradingClass.length === 0)) {
+        return false;
+    }
+    // A record whose symbol does not carry its own root is not the identity it claims to be.
+    const parsed = parseOsiOptionSymbol(symbol);
+    return parsed !== null && parsed.root === (tradingClass ?? underlying);
+}
 /** A typed HTTP failure from the IBKR transport. */
 export class IbkrHttpError extends Error {
     status;
@@ -337,6 +412,7 @@ export class IbkrClient {
     initPromise;
     accountIdPromise;
     optionDiscovery = new Map();
+    optionDefinitionCache;
     optionContractResolution = new Map();
     priceHistoryContractResolution = new Map();
     derivativeDiscovery = new Map();
@@ -350,6 +426,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());
@@ -3089,11 +3166,17 @@ export class IbkrClient {
     async resolveQuoteContract(symbol) {
         const osi = parseOsiOptionSymbol(symbol);
         if (osi) {
+            // The OSI root names the listing class, which is the underlying only for a single-class
+            // name. It is passed as both: as the search root, which is all IBKR can be asked for here,
+            // and as the class, so a month that lists more than one class resolves to the one this
+            // symbol names instead of refusing. A caller holding a class-rooted symbol whose class IBKR
+            // does not resolve as a root must quote by `brokerId` (the conid) instead.
             const option = await this.resolveOptionContract({
-                symbol: osi.underlying,
+                symbol: osi.root,
                 expiry: osi.expiry,
                 strike: osi.strike,
                 right: osi.right,
+                tradingClass: osi.root,
             });
             return option
                 ? {
@@ -3500,8 +3583,11 @@ export class IbkrClient {
             return null;
         return normalizeOptionContract({
             conid: raw.conid ?? conid,
-            // `symbol` is absent on this payload; IBKR names the underlying `ticker`/`undSym` here.
-            symbol: raw.symbol ?? raw.ticker ?? raw.undSym,
+            // `symbol` is absent on this payload; IBKR names the underlying `undSym` and the listing
+            // class `ticker` here. `ticker` is the class - `SPXW` where `undSym` is `SPX` - so it is the
+            // trading class, and the underlying falls back to it for a single-listing name.
+            symbol: raw.undSym ?? raw.symbol ?? raw.ticker,
+            tradingClass: raw.tradingClass ?? raw.ticker,
             maturityDate: raw.expiry ?? raw.maturityDate,
             right: raw.putOrCall,
             strike: raw.strike,
@@ -3510,7 +3596,13 @@ export class IbkrClient {
     resolveOptionContract(input) {
         const underlying = input.symbol.trim().toUpperCase();
         const month = monthCode(input.expiry);
-        const key = [underlying, input.expiry, String(input.strike), input.right].join(":");
+        const key = [
+            underlying,
+            input.expiry,
+            String(input.strike),
+            input.right,
+            input.tradingClass?.trim().toUpperCase() ?? "*",
+        ].join(":");
         let pending = this.optionContractResolution.get(key);
         if (!pending) {
             pending = this.loadExactOptionContract({ ...input, symbol: underlying }, month).then((contract) => {
@@ -3553,6 +3645,7 @@ export class IbkrClient {
             }
             const rawConid = raw["conid"];
             const rawSymbol = raw["symbol"];
+            const rawTradingClass = raw["tradingClass"];
             const rawMaturityDate = raw["maturityDate"];
             const rawRight = raw["right"];
             const rawStrike = raw["strike"];
@@ -3562,6 +3655,7 @@ export class IbkrClient {
                 contract = normalizeOptionContract({
                     conid: typeof rawConid === "number" ? rawConid : undefined,
                     symbol: typeof rawSymbol === "string" ? rawSymbol : underlying.symbol,
+                    tradingClass: typeof rawTradingClass === "string" ? rawTradingClass : undefined,
                     maturityDate: typeof rawMaturityDate === "string" ? rawMaturityDate : undefined,
                     right: typeof rawRight === "string" ? rawRight : undefined,
                     strike: typeof rawStrike === "string" || typeof rawStrike === "number" ? rawStrike : undefined,
@@ -3576,10 +3670,20 @@ export class IbkrClient {
                 malformed = true;
                 continue;
             }
-            if (contract.underlying === input.symbol &&
+            const requestedClass = input.tradingClass?.trim().toUpperCase();
+            // A caller reaches this with either a plain underlying or an OSI root that names a class, so
+            // both are accepted as the requested root. The class filter below is what keeps two listings
+            // apart; without it, an underlying that lists two classes still refuses rather than guesses.
+            const rootMatches = contract.underlying === input.symbol || contract.tradingClass === input.symbol;
+            if (rootMatches &&
                 contract.expiry === input.expiry &&
                 contract.right === input.right &&
-                contract.strike === input.strike) {
+                contract.strike === input.strike &&
+                (requestedClass === undefined ||
+                    contract.tradingClass === requestedClass ||
+                    // A contract with no stated class answers a request for its own underlying root, which
+                    // is what a single-listing name asks for. It never answers for another class.
+                    (contract.tradingClass === null && contract.underlying === requestedClass))) {
                 matches.push(contract);
             }
         }
@@ -3588,7 +3692,16 @@ export class IbkrClient {
         }
         const unique = [...new Map(matches.map((contract) => [contract.conid, contract])).values()];
         if (unique.length > 1) {
-            throw new Error(`IBKR returned ambiguous option definitions for ${input.symbol} ${input.expiry}`);
+            // Two listing classes of one underlying are two products, and the caller must say which one
+            // it means. Two contracts inside one class are a collision the client cannot resolve; both
+            // stay a refusal rather than a guess.
+            const classes = [
+                ...new Set(unique.map((contract) => contract.tradingClass ?? contract.underlying)),
+            ].sort();
+            const detail = classes.length > 1
+                ? `; listing classes: ${classes.join(", ")}. Name one in 'tradingClass'.`
+                : "";
+            throw new Error(`IBKR returned ambiguous option definitions for ${input.symbol} ${input.expiry}${detail}`);
         }
         return unique[0] ?? null;
     }
@@ -3724,16 +3837,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),
@@ -3741,7 +3862,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);
@@ -3767,7 +3888,9 @@ export class IbkrClient {
             throw new Error(`IBKR lost the selected underlying for ${symbol}`);
         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);
@@ -3777,7 +3900,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({
@@ -3786,29 +3909,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" }))
                         : []),
@@ -3816,12 +3929,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({
@@ -3841,13 +3990,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;
@@ -3855,6 +4008,7 @@ export class IbkrClient {
                             contract = normalizeOptionContract({
                                 conid: typeof raw["conid"] === "number" ? raw["conid"] : undefined,
                                 symbol: typeof raw["symbol"] === "string" ? raw["symbol"] : underlying.symbol,
+                                tradingClass: typeof raw["tradingClass"] === "string" ? raw["tradingClass"] : undefined,
                                 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"
@@ -3864,23 +4018,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 };
@@ -3888,12 +4062,74 @@ export class IbkrClient {
             if (!unique.length) {
                 throw new Error(`IBKR returned no usable option definitions for ${symbol} ${month} (${String(malformedDefinitionCount)} malformed)`);
             }
+            // Two conids that reach one durable symbol are two contracts a consumer cannot tell apart.
+            // This is the check that lets an unstated listing class fall back to the underlying root: a
+            // fallback that would hide a collision is refused instead of returned.
+            const collision = firstSymbolCollision(unique);
+            if (collision !== null) {
+                throw new Error(`IBKR returned two option contracts with one identity for ${symbol} ${month}: ` +
+                    `${collision.symbol} is conid ${String(collision.first.conid)} and ` +
+                    `${String(collision.second.conid)}. IBKR stated no listing class for at least one.`);
+            }
             return { contracts: unique, malformedDefinitionCount };
         }
         finally {
             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",
@@ -4026,6 +4262,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);
@@ -4612,6 +4853,14 @@ export class IbkrClient {
         const parsed = Number(cleaned);
         return Number.isFinite(parsed) ? parsed : undefined;
     }
+    /**
+     * Read IBKR's `_updated` snapshot field as an ISO instant.
+     *
+     * `_updated` is a last-change time, not an observation time: it moves only when IBKR's record
+     * for the contract changes, and a repeated request does not move it. A quiet option on a live
+     * feed can hold one value for several minutes while it reports the same bid and ask, so a
+     * consumer must not read the age of this value as the age of its own reading.
+     */
     snapshotTimestamp(snapshot) {
         const updated = this.snapshotNumber(snapshot, "_updated");
         if (updated === undefined)