@huskly/ibkr-client 0.6.0 → 0.8.0

package/dist/ibkr/ibkrClient.js

@@ -1,6 +1,7 @@
 import { createRequire } from "node:module";
 import { ASSET_CLASS_LABELS, toNumber } from "../helpers.js";
 import { normalizeOptionContract, parseOsiOptionSymbol } from "./optionContract.js";
+import { normalizeDerivativeContract, normalizeDerivativeDataAvailability, } from "./derivativeContract.js";
 // `ibkr-client`'s published ESM build is broken: its `import` condition points
 // at files that use extensionless relative imports, which Node's strict ESM
 // resolver rejects. Its CJS build is fine, so we deliberately load that via
@@ -18,6 +19,17 @@ const OPTION_QUOTE_FIELDS = [
     "7638", // Option open interest
     "7762", // Unformatted volume
 ].join(",");
+const DERIVATIVE_QUOTE_FIELDS = [
+    "31", // Last
+    "84", // Bid
+    "86", // Ask
+    "6509", // Market data availability
+    "7308", // Delta
+    "7633", // Implied volatility
+    "7635", // Mark price
+    "7638", // Option open interest
+    "7762", // Unformatted volume
+].join(",");
 const QUOTE_FIELDS = [
     "31", // Last
     "55", // Symbol
@@ -39,6 +51,27 @@ const OPTION_MARKETDATA_BATCH_SIZE = 100;
 const READ_ONLY_REQUEST_MAX_RETRIES = 3;
 const REQUEST_RETRY_BASE_DELAY_MS = 250;
 const REQUEST_RETRY_MAX_DELAY_MS = 5_000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const IBKR_STATUS_FILTERS = {
+    CANCELED: "cancelled",
+    CANCELLED: "cancelled",
+    FILLED: "filled",
+    PENDING_CANCEL: "pending_cancel",
+    PENDING_SUBMIT: "pending_submit",
+    PRE_SUBMITTED: "pre_submitted",
+    SUBMITTED: "submitted",
+};
+const IBKR_WORKING_STATUSES = new Set([
+    "API_PENDING",
+    "PENDING_SUBMIT",
+    "PRE_SUBMITTED",
+    "SUBMITTED",
+    "PENDING_CANCEL",
+]);
+/** Extract the canonical OSI symbol embedded in an IBKR option description. */
+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) {
     const asString = typeof raw === "string" ? raw.trim() : undefined;
@@ -124,6 +157,7 @@ export class IbkrClient {
     initPromise;
     accountIdPromise;
     optionDiscovery = new Map();
+    derivativeDiscovery = new Map();
     constructor(config) {
         this.raw = new RawIbkrClientCtor(config);
     }
@@ -221,8 +255,12 @@ export class IbkrClient {
     normalizePosition(p, dayPnl) {
         const qty = p.position ?? 0;
         const assetClass = p.assetClass ?? "";
+        const contractDescription = p.contractDesc ?? String(p.conid ?? "-");
+        const symbol = assetClass === "OPT"
+            ? (extractOsiPositionSymbol(contractDescription) ?? contractDescription)
+            : contractDescription;
         return {
-            symbol: p.contractDesc ?? String(p.conid ?? "-"),
+            symbol,
             assetType: ASSET_CLASS_LABELS[assetClass] ?? (assetClass || "-"),
             longQuantity: qty > 0 ? qty : 0,
             shortQuantity: qty < 0 ? Math.abs(qty) : 0,
@@ -264,7 +302,10 @@ export class IbkrClient {
         return quotes;
     }
     /** Resolve equity/ETF symbols to IBKR contracts via `trsrv/stocks`. */
-    async searchInstruments(symbol) {
+    async searchInstruments(symbol, projection = "symbol-search") {
+        if (projection !== "symbol-search" && projection !== "search") {
+            throw new Error(`IBKR search currently supports only symbol-search/search projections (got '${projection}').`);
+        }
         const query = symbol.trim().toUpperCase();
         if (!query)
             return [];
@@ -274,6 +315,71 @@ export class IbkrClient {
         });
         return (response[query] ?? []).flatMap((listing) => this.normalizeStockListing(query, listing));
     }
+    async fetchTransactionHistory(startDate, endDate) {
+        const accountId = await this.getAccountId();
+        const rows = await this.fetchAllPositions(accountId);
+        const positionsByConid = new Map(rows
+            .filter((position) => position.conid !== undefined)
+            .map((position) => [position.conid, position]));
+        const transactionsByKey = new Map();
+        const days = Math.max(1, Math.ceil((endDate.getTime() - startDate.getTime()) / DAY_MS) + 1);
+        for (const conid of positionsByConid.keys()) {
+            const response = await this.req({
+                path: "pa/transactions",
+                method: "POST",
+                data: {
+                    acctIds: [accountId],
+                    conids: [conid],
+                    currency: process.env["IBKR_TRANSACTION_CURRENCY"] ?? "USD",
+                    days,
+                },
+            });
+            for (const transaction of response.transactions ?? []) {
+                const normalized = this.normalizeTransaction(transaction, positionsByConid);
+                const time = new Date(normalized.time).getTime();
+                if (time < startDate.getTime() || time > endDate.getTime())
+                    continue;
+                transactionsByKey.set(this.transactionKey(normalized), normalized);
+            }
+        }
+        return [{ accountNumber: accountId, transactions: [...transactionsByKey.values()] }];
+    }
+    async fetchOrders(options) {
+        const accountId = await this.getAccountId();
+        await this.prepareBrokerageAccount(accountId);
+        const params = {};
+        if (options.status && options.status.toUpperCase() !== "WORKING") {
+            params["filters"] = this.ibkrStatusFilter(options.status);
+        }
+        const response = await this.req({
+            path: "iserver/account/orders",
+            params,
+        });
+        let orders = (response.orders ?? [])
+            .filter((order) => this.orderBelongsToAccount(order, accountId))
+            .map((order) => this.normalizeOrder(order))
+            .filter((order) => this.orderMatchesStatus(order, options.status))
+            .filter((order) => this.orderInDateRange(order, options.fromEnteredTime, options.toEnteredTime))
+            .sort((left, right) => this.orderTimeMs(right) - this.orderTimeMs(left));
+        if (options.maxResults !== undefined)
+            orders = orders.slice(0, options.maxResults);
+        return [{ accountNumber: accountId, orders }];
+    }
+    async prepareBrokerageAccount(accountId) {
+        const brokerageAccounts = await this.req({
+            path: "iserver/accounts",
+        });
+        if (brokerageAccounts.selectedAccount === accountId)
+            return;
+        if (brokerageAccounts.accounts && !brokerageAccounts.accounts.includes(accountId)) {
+            throw new Error(`IBKR account ${accountId} is not available for trading/order queries.`);
+        }
+        await this.req({
+            path: "iserver/account",
+            method: "POST",
+            data: { acctId: accountId },
+        });
+    }
     normalizeStockListing(symbol, listing) {
         const assetType = listing.assetClass === "STK" ? "EQUITY" : listing.assetClass;
         const contracts = listing.contracts ?? [];
@@ -357,6 +463,71 @@ export class IbkrClient {
             };
         });
     }
+    /** Discover listed derivative series over an inclusive calendar range. */
+    async getDerivativeExpiries(query) {
+        const contracts = (await Promise.all(monthCodes(query.from, query.to).map((month) => this.discoverDerivativeMonth(query.underlying, query.assetClass, month, query.exchange, query.right)))).flat();
+        const filtered = contracts.filter((contract) => contract.expiration >= query.from &&
+            contract.expiration <= query.to &&
+            (query.right === undefined || contract.right === query.right) &&
+            (query.tradingClass === undefined ||
+                contract.tradingClass === query.tradingClass.trim().toUpperCase()));
+        const expiries = filtered.map(({ assetClass, underlying, expiration, tradingClass, exchange, multiplier }) => ({
+            assetClass,
+            underlying,
+            expiration,
+            tradingClass,
+            exchange,
+            multiplier,
+        }));
+        return [
+            ...new Map(expiries.map((expiry) => [
+                [
+                    expiry.assetClass,
+                    expiry.underlying,
+                    expiry.expiration,
+                    expiry.tradingClass,
+                    expiry.exchange,
+                    String(expiry.multiplier),
+                ].join(":"),
+                expiry,
+            ])).values(),
+        ].sort((left, right) => left.expiration.localeCompare(right.expiration));
+    }
+    /** Discover contracts for one exact expiration, preserving class and venue identity. */
+    async getDerivativeContracts(query) {
+        const tradingClass = query.tradingClass?.trim().toUpperCase();
+        return (await this.discoverDerivativeMonth(query.underlying, query.assetClass, monthCode(query.expiration), query.exchange, query.right, query.strike)).filter((contract) => contract.expiration === query.expiration &&
+            (query.right === undefined || contract.right === query.right) &&
+            (query.strike === undefined || contract.strike === query.strike) &&
+            (tradingClass === undefined || contract.tradingClass === tradingClass));
+    }
+    /** Resolve exactly one contract and reject missing or ambiguous semantic identity. */
+    async resolveDerivativeContract(query) {
+        const contracts = await this.getDerivativeContracts(query);
+        if (!contracts.length) {
+            throw new Error(`IBKR returned no exact ${query.assetClass} contract for ${query.underlying} ${query.expiration} ${query.right}${String(query.strike)}`);
+        }
+        if (contracts.length !== 1) {
+            const classes = [...new Set(contracts.map((contract) => contract.tradingClass))].join(", ");
+            throw new Error(`Ambiguous ${query.assetClass} contract for ${query.underlying} ${query.expiration} ${query.right}${String(query.strike)}; specify tradingClass (${classes})`);
+        }
+        const contract = contracts[0];
+        if (!contract)
+            throw new Error("IBKR exact derivative resolution lost its selected contract");
+        return contract;
+    }
+    /** Return an exact-expiration derivative chain with explicit data availability. */
+    async getDerivativeChain(query) {
+        const contracts = await this.getDerivativeContracts(query);
+        if (!contracts.length) {
+            throw new Error(`IBKR returned no ${query.assetClass} contracts for ${query.underlying} ${query.expiration}`);
+        }
+        const quotes = await this.fetchDerivativeQuotes(contracts);
+        if (!quotes.some((quote) => quote.bid !== null && quote.ask !== null)) {
+            throw new Error(`IBKR returned no usable derivative quotes for ${query.underlying} ${query.expiration}`);
+        }
+        return quotes;
+    }
     /** Discover every listed weekly/monthly expiry in the requested calendar range. */
     async getOptionExpiries(symbol, right, fromDate, toDate) {
         const normalized = symbol.trim().toUpperCase();
@@ -415,6 +586,141 @@ export class IbkrClient {
             contract.right === input.right &&
             contract.strike === input.strike) ?? null);
     }
+    discoverDerivativeMonth(underlying, assetClass, month, exchange, right, strike) {
+        const normalizedUnderlying = underlying.trim().toUpperCase();
+        if (!normalizedUnderlying)
+            throw new Error("Derivative underlying is required");
+        const normalizedExchange = exchange?.trim().toUpperCase();
+        const key = [
+            normalizedUnderlying,
+            assetClass,
+            month,
+            normalizedExchange ?? "*",
+            right ?? "*",
+            strike === undefined ? "*" : String(strike),
+        ].join(":");
+        let pending = this.derivativeDiscovery.get(key);
+        if (!pending) {
+            pending = this.loadDerivativeContracts(normalizedUnderlying, assetClass, month, normalizedExchange, right, strike);
+            this.derivativeDiscovery.set(key, pending);
+        }
+        return pending;
+    }
+    async loadDerivativeContracts(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({
+            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));
+        if (candidates.length !== 1) {
+            throw new Error(`IBKR ${assetClass} underlying identity is ${candidates.length ? "ambiguous" : "missing"} for ${underlying}`);
+        }
+        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);
+        if (requestedExchange && !exchanges.includes(requestedExchange)) {
+            throw new Error(`IBKR does not list ${underlying} ${assetClass} discovery on ${requestedExchange}`);
+        }
+        const exchange = requestedExchange ?? (exchanges.length === 1 ? exchanges[0] : undefined);
+        const strikes = await this.req({
+            path: "iserver/secdef/strikes",
+            params: {
+                conid: String(conid),
+                sectype: assetClass,
+                month,
+                ...(exchange ? { exchange } : {}),
+            },
+        });
+        const availableRequests = [
+            ...(strikes.call ?? []).map((strike) => ({ strike, right: "C" })),
+            ...(strikes.put ?? []).map((strike) => ({ strike, right: "P" })),
+        ];
+        if (!availableRequests.length) {
+            throw new Error(`IBKR returned empty ${assetClass} strikes for ${underlying} ${month} after secdef/search priming`);
+        }
+        const requests = availableRequests.filter((request) => (requestedRight === undefined || request.right === requestedRight) &&
+            (requestedStrike === undefined || request.strike === requestedStrike));
+        if (!requests.length) {
+            return [];
+        }
+        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(conid),
+                    sectype: assetClass,
+                    month,
+                    strike,
+                    right,
+                    ...(exchange ? { exchange } : {}),
+                },
+            })));
+            for (const raw of responses.flat()) {
+                const contract = normalizeDerivativeContract(raw, assetClass, underlying);
+                if (contract && (!requestedExchange || contract.exchange === requestedExchange)) {
+                    contracts.push(contract);
+                }
+            }
+        }
+        const unique = [...new Map(contracts.map((contract) => [contract.conid, contract])).values()];
+        if (!unique.length) {
+            throw new Error(`IBKR returned no usable ${assetClass} definitions for ${underlying} ${month}`);
+        }
+        return unique;
+    }
+    async fetchDerivativeQuotes(contracts) {
+        const result = [];
+        for (const batch of chunks(contracts, OPTION_MARKETDATA_BATCH_SIZE)) {
+            const params = {
+                conids: batch.map((contract) => contract.conid).join(","),
+                fields: DERIVATIVE_QUOTE_FIELDS,
+            };
+            await this.req({ path: "iserver/marketdata/snapshot", params });
+            await this.wait(2000);
+            const snapshots = await this.req({
+                path: "iserver/marketdata/snapshot",
+                params,
+            });
+            const byConid = new Map(snapshots
+                .filter((snapshot) => snapshot.conid !== undefined)
+                .map((snapshot) => [snapshot.conid, snapshot]));
+            for (const contract of batch) {
+                const snapshot = byConid.get(contract.conid);
+                const updated = snapshot ? this.snapshotNumber(snapshot, "_updated") : undefined;
+                const updatedMs = updated === undefined ? undefined : updated < 100_000_000_000 ? updated * 1000 : updated;
+                const updatedDate = updatedMs === undefined ? undefined : new Date(updatedMs);
+                const timestamp = updatedDate && !Number.isNaN(updatedDate.getTime()) ? updatedDate.toISOString() : null;
+                result.push({
+                    contract,
+                    availability: normalizeDerivativeDataAvailability(snapshot?.["6509"]),
+                    timestamp,
+                    bid: snapshot ? (this.snapshotNumber(snapshot, "84") ?? null) : null,
+                    ask: snapshot ? (this.snapshotNumber(snapshot, "86") ?? null) : null,
+                    last: snapshot ? (this.snapshotNumber(snapshot, "31") ?? null) : null,
+                    mark: snapshot ? (this.snapshotNumber(snapshot, "7635") ?? null) : null,
+                    delta: snapshot ? (this.snapshotNumber(snapshot, "7308") ?? null) : null,
+                    impliedVolatility: snapshot ? (this.snapshotNumber(snapshot, "7633") ?? null) : null,
+                    volume: snapshot ? (this.snapshotVolume(snapshot) ?? null) : null,
+                    openInterest: snapshot ? (this.snapshotNumber(snapshot, "7638") ?? null) : null,
+                });
+            }
+        }
+        return result;
+    }
     discoverOptions(symbol, month) {
         const normalized = symbol.trim().toUpperCase();
         const key = `${normalized}:${month}`;
@@ -561,6 +867,240 @@ export class IbkrClient {
             return undefined;
         }
     }
+    normalizeTransaction(transaction, positionsByConid) {
+        const conid = transaction.conid;
+        const position = conid === undefined ? undefined : positionsByConid.get(conid);
+        const assetType = position?.assetClass === undefined
+            ? undefined
+            : (ASSET_CLASS_LABELS[position.assetClass] ?? position.assetClass);
+        const symbol = position?.contractDesc ?? (conid === undefined ? undefined : String(conid));
+        const description = transaction.desc ?? symbol;
+        const time = this.parseTransactionTime(transaction)?.toISOString() ?? "";
+        const type = (transaction.type ?? "TRANSACTION").toUpperCase();
+        const transferItem = {
+            instrument: {
+                ...(assetType === undefined ? {} : { assetType }),
+                ...(symbol === undefined ? {} : { symbol }),
+                ...(description === undefined ? {} : { description }),
+            },
+            ...(transaction.qty === undefined ? {} : { amount: transaction.qty }),
+            ...(transaction.pr === undefined ? {} : { cost: transaction.pr }),
+            transferItemType: type,
+        };
+        const activityId = [
+            conid === undefined ? "unknown" : String(conid),
+            time,
+            transaction.qty === undefined ? "" : String(transaction.qty),
+            transaction.amt === undefined ? "" : String(transaction.amt),
+        ].join(":");
+        return {
+            activityId,
+            time,
+            type,
+            status: "VALID",
+            ...(transaction.acctid === undefined ? {} : { subAccount: transaction.acctid }),
+            ...(description === undefined ? {} : { description }),
+            netAmount: toNumber(transaction.amt),
+            transferItems: [transferItem],
+        };
+    }
+    normalizeOrder(order) {
+        const description = order.orderDescriptionWithContract ??
+            order.order_description_with_contract ??
+            order.orderDesc ??
+            order.orderDescription ??
+            order.order_description;
+        const symbol = order.description1 ??
+            order.contract_description_1 ??
+            order.contractDescription1 ??
+            order.symbol ??
+            order.ticker;
+        const quantity = this.firstPositiveNumber(order.total_size, order.totalSize, order.size) ??
+            this.quantityFromDescription(description);
+        const filledQuantity = this.firstNumber(order.cum_fill, order.cumFill, order.filledQuantity) ??
+            this.filledQuantityFromSizeAndFills(order.size_and_fills ?? order.sizeAndFills);
+        const remainingQuantity = order.remainingQuantity !== undefined
+            ? toNumber(order.remainingQuantity)
+            : quantity !== undefined && filledQuantity !== undefined
+                ? Math.max(0, quantity - filledQuantity)
+                : undefined;
+        const status = this.normalizeOrderStatus(order.order_status ?? order.orderStatus ?? order.status);
+        const price = this.firstPositiveNumber(order.limitPrice, order.price, order.avgPrice, order.average_price, order.averagePrice);
+        const stopPrice = this.firstPositiveNumber(order.stopPrice);
+        const orderId = order.order_id ?? order.orderId;
+        const enteredTime = this.parseOrderTime(order)?.toISOString();
+        const orderType = this.normalizeOrderType(order.order_type ?? order.orderType);
+        return {
+            ...(orderId === undefined ? {} : { orderId }),
+            ...(enteredTime === undefined ? {} : { enteredTime }),
+            ...(status === undefined ? {} : { status }),
+            ...(orderType === undefined ? {} : { orderType }),
+            ...(quantity === undefined ? {} : { quantity }),
+            ...(filledQuantity === undefined ? {} : { filledQuantity }),
+            ...(remainingQuantity === undefined ? {} : { remainingQuantity }),
+            ...(price === undefined ? {} : { price }),
+            ...(stopPrice === undefined ? {} : { stopPrice }),
+            orderLegCollection: [this.normalizeOrderLeg(order, symbol)],
+        };
+    }
+    normalizeOrderLeg(order, symbol) {
+        const fallbackSymbol = symbol ?? (order.conid === undefined ? undefined : String(order.conid));
+        const instruction = this.normalizeOrderSide(order.side);
+        return {
+            ...(instruction === undefined ? {} : { instruction }),
+            instrument: { ...(fallbackSymbol === undefined ? {} : { symbol: fallbackSymbol }) },
+        };
+    }
+    normalizeOrderStatus(status) {
+        if (!status)
+            return undefined;
+        const normalized = status
+            .replace(/([a-z])([A-Z])/g, "$1_$2")
+            .replace(/\s+/g, "_")
+            .toUpperCase();
+        return normalized === "CANCELLED" ? "CANCELED" : normalized;
+    }
+    normalizeOrderType(type) {
+        if (!type)
+            return undefined;
+        if (type === "MKT")
+            return "MARKET";
+        if (type === "LMT")
+            return "LIMIT";
+        if (type === "STP")
+            return "STOP";
+        return type.replace(/\s+/g, "_").toUpperCase();
+    }
+    normalizeOrderSide(side) {
+        if (!side)
+            return undefined;
+        const upper = side.toUpperCase();
+        if (upper === "B" || upper === "BUY")
+            return "BUY";
+        if (upper === "S" || upper === "SELL")
+            return "SELL";
+        return upper;
+    }
+    ibkrStatusFilter(status) {
+        const normalized = status.toUpperCase();
+        return IBKR_STATUS_FILTERS[normalized] ?? normalized.toLowerCase();
+    }
+    orderMatchesStatus(order, requestedStatus) {
+        if (!requestedStatus)
+            return true;
+        const normalizedStatus = this.normalizeOrderStatus(requestedStatus);
+        if (normalizedStatus === "WORKING") {
+            return order.status !== undefined && IBKR_WORKING_STATUSES.has(order.status);
+        }
+        return order.status === normalizedStatus;
+    }
+    orderBelongsToAccount(order, accountId) {
+        const account = order.account ?? order.acct;
+        return account === undefined || account === accountId;
+    }
+    orderInDateRange(order, fromDate, toDate) {
+        const timeMs = this.orderTimeMs(order);
+        return !Number.isFinite(timeMs) || (timeMs >= fromDate.getTime() && timeMs <= toDate.getTime());
+    }
+    orderTimeMs(order) {
+        const parsed = order.enteredTime ? new Date(order.enteredTime).getTime() : Number.NaN;
+        return Number.isNaN(parsed) ? Number.NEGATIVE_INFINITY : parsed;
+    }
+    parseOrderTime(order) {
+        if (order.lastExecutionTime_r !== undefined) {
+            const parsed = new Date(order.lastExecutionTime_r);
+            if (!Number.isNaN(parsed.getTime()))
+                return parsed;
+        }
+        const value = order.order_time ?? order.orderTime ?? order.lastExecutionTime;
+        if (!value)
+            return undefined;
+        const compact = /^(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})$/.exec(value);
+        if (compact) {
+            const [, year, month, day, hour, minute, second] = compact;
+            return new Date(Date.UTC(2000 + Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second)));
+        }
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+    }
+    firstNumber(...values) {
+        for (const value of values) {
+            if (value === undefined)
+                continue;
+            const numeric = Number(value);
+            if (Number.isFinite(numeric))
+                return numeric;
+        }
+        return undefined;
+    }
+    firstPositiveNumber(...values) {
+        for (const value of values) {
+            const numeric = this.firstNumber(value);
+            if (numeric !== undefined && numeric > 0)
+                return numeric;
+        }
+        return undefined;
+    }
+    quantityFromDescription(description) {
+        const quantity = description
+            ? /\b(?:Bought|Sold|Buy|Sell)\s+(?<quantity>[\d.]+)/i.exec(description)?.groups?.["quantity"]
+            : undefined;
+        if (!quantity)
+            return undefined;
+        const parsed = Number(quantity);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    filledQuantityFromSizeAndFills(value) {
+        const quantity = value ? /(?<quantity>[\d.]+)/.exec(value)?.groups?.["quantity"] : undefined;
+        if (!quantity)
+            return undefined;
+        const parsed = Number(quantity);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    parseTransactionTime(transaction) {
+        if (transaction.rawDate && /^\d{8}$/.test(transaction.rawDate)) {
+            const year = transaction.rawDate.slice(0, 4);
+            const month = transaction.rawDate.slice(4, 6);
+            const day = transaction.rawDate.slice(6, 8);
+            return new Date(`${year}-${month}-${day}T00:00:00`);
+        }
+        const value = transaction.date;
+        if (!value)
+            return undefined;
+        const parsed = new Date(value);
+        if (!Number.isNaN(parsed.getTime()))
+            return parsed;
+        const match = /^(?:\w{3}) (?<month>\w{3}) (?<day>\d{1,2}) (?<time>\d{2}:\d{2}:\d{2}) (?<zone>\w{3}) (?<year>\d{4})$/.exec(value);
+        if (!match?.groups)
+            return undefined;
+        const zoneOffsets = {
+            EST: "-05:00",
+            EDT: "-04:00",
+            CST: "-06:00",
+            CDT: "-05:00",
+            MST: "-07:00",
+            MDT: "-06:00",
+            PST: "-08:00",
+            PDT: "-07:00",
+            UTC: "Z",
+            GMT: "Z",
+        };
+        const { month, day, time, zone, year } = match.groups;
+        if (!month || !day || !time || !zone || !year)
+            return undefined;
+        const normalized = `${day.padStart(2, "0")} ${month} ${year} ${time} ${zoneOffsets[zone] ?? "Z"}`;
+        const fallback = new Date(normalized);
+        return Number.isNaN(fallback.getTime()) ? undefined : fallback;
+    }
+    transactionKey(transaction) {
+        return [
+            transaction.activityId,
+            transaction.time,
+            transaction.type,
+            transaction.netAmount,
+            transaction.transferItems?.[0]?.amount ?? "",
+        ].join(":");
+    }
     /** Overridable in request-level tests so snapshot warm-up does not sleep. */
     wait(ms) {
         return sleep(ms);