@huskly/ibkr-client 0.6.0 → 0.7.0

package/README.md

@@ -1,9 +1,10 @@
-# IBKR CLI (`@huskly/ibkr-client`)
+# IBKR Client (`@huskly/ibkr-client`)
 
-A terminal trading CLI for the **Interactive Brokers Web API**, authenticating
-over **OAuth 1.0a** (no Client Portal Gateway required). Built to mirror the
-architecture of [huskly-cli](https://github.com/felipecsl/huskly-cli) so the two
-can merge into a single multi-broker CLI (IBKR + Schwab) over time.
+A reusable TypeScript client for the **Interactive Brokers Web API**,
+authenticating over **OAuth 1.0a** without the Client Portal Gateway. This
+package contains no command-line interface; terminal commands and presentation
+belong exclusively in
+[huskly-cli](https://github.com/felipecsl/huskly-cli).
 
 The OAuth 1.0a live-session-token handshake is performed by the
 [`ibkr-client`](https://github.com/art1c0/ibkr-client) package. See the
@@ -12,17 +13,15 @@ the keys below are generated and registered in the IBKR self-service portal.
 
 ## Layout
 
-The repo is split into a reusable **library** and a thin **CLI**, mirroring
-huskly-cli's `@huskly/schwab-client` + CLI split:
+The repository contains only the reusable client library:
 
 | Path                     | Purpose                                                                  |
 | ------------------------ | ------------------------------------------------------------------------ |
-| `src/types.ts`           | Broker-neutral `BrokerClient` interface + domain types (the merge contract) |
+| `src/types.ts`           | Broker-neutral `BrokerClient` interface and normalized domain types         |
 | `src/ibkr/ibkrClient.ts` | `IbkrClient` — typed wrapper over `ibkr-client` implementing `BrokerClient` |
 | `src/ibkr/oauthConfig.ts`| Builds the OAuth config from `.pem` files + env vars                      |
 | `src/ibkr/dhPrime.ts`    | Extracts the DH prime (hex) from `dhparam.pem`                            |
 | `src/ibkr/optionContract.ts` | Canonical OSI parsing and formatting for IBKR option contracts        |
-| `src/cli/`               | `commander` program, `--broker` flag, and command handlers               |
 
 The `*.pem` files (`private_signature.pem`, `private_encryption.pem`,
 `dhparam.pem`, plus the public keys) are the cryptographic material from the
@@ -31,7 +30,7 @@ wiki setup step and are git-ignored.
 ## Setup
 
 ```bash
-npm install
+yarn install --frozen-lockfile
 ```
 
 Provide the account-specific secrets, either by copying the template:
@@ -56,43 +55,21 @@ Optional environment variables:
 - `IBKR_KEYS_DIR` — directory holding the `.pem` files (defaults to the current
   working directory).
 - `IBKR_ACCOUNT_ID` — target a specific account (otherwise the first is used).
+- `IBKR_TRANSACTION_CURRENCY` — transaction-query currency (defaults to `USD`).
 
-## Usage
+## Library API
 
-Run in development (via `tsx`, no build step):
+`IbkrClient` owns IBKR authentication, requests, raw response types, and
+normalization. Consumers such as huskly-cli provide presentation, command
+routing, and caching. Its broker-neutral account API includes:
 
-```bash
-npm run dev -- account
-npm run dev -- positions
-npm run dev -- positions AAPL          # filter by symbol
-npm run dev -- positions --type EQUITY # filter by asset type
-npm run dev -- positions --csv         # CSV instead of a table
-```
-
-Or build and use the `ibkr-cli` binary:
-
-```bash
-npm run build
-node dist/cli/index.js account
-```
-
-A global `--broker <ibkr|schwab>` flag (default `ibkr`) selects the broker.
-Only IBKR is implemented today; `schwab` is reserved for the huskly-cli merge.
-
-Example output:
-
-```
-💰 Account Summary
-
-Authenticated: yes   Competing: no
-Account:       U********
-──────────────────────────────────────────────────
-Net Liquidation:  $123,456.78
-Available Funds:  $...
-...
-```
+- `getAccountBalances()` and `getPositions()` for account state.
+- `getQuotes()` and `searchInstruments()` for equity/ETF discovery and quotes.
+- `fetchTransactionHistory()` for normalized portfolio transactions.
+- `fetchOrders()` for normalized live orders, including aggregate `WORKING`
+  matching across IBKR's active order states.
 
-## Strategy market data
+### Strategy market data
 
 The reusable `IbkrClient` also exposes typed, read-only strategy data:
 
@@ -152,12 +129,12 @@ NODE
 ## Development
 
 ```bash
-npm run lint          # eslint
-npm run format        # prettier --write
-npm run typecheck     # tsc --noEmit
-npm test              # typecheck + native node:test suite
-npm run build         # tsc -> dist/
-npm run check         # lint + format:check + typecheck
+yarn lint       # eslint
+yarn format     # prettier --write
+yarn typecheck  # tsc --noEmit
+yarn test       # typecheck + native node:test suite
+yarn build      # tsc -> dist/
+yarn run check  # lint + format:check + typecheck
 ```
 
 CI (`.github/workflows/ci.yml`) runs lint, format check, typecheck, tests, and build on

package/dist/ibkr/ibkrApiTypes.d.ts

@@ -51,6 +51,80 @@ export interface IbkrStockListing {
 }
 /** `trsrv/stocks` response: keyed by the requested symbol. */
 export type IbkrStocksResponse = Record<string, IbkrStockListing[] | undefined>;
+export interface IbkrTransactionsResponse {
+    currency?: string;
+    from?: number;
+    to?: number;
+    includesRealTime?: boolean;
+    transactions?: IbkrTransaction[];
+}
+export interface IbkrTransaction {
+    date?: string;
+    rawDate?: string;
+    cur?: string;
+    fxRate?: number;
+    pr?: number;
+    qty?: number;
+    acctid?: string;
+    amt?: number;
+    conid?: number;
+    type?: string;
+    desc?: string;
+}
+export interface IbkrLiveOrdersResponse {
+    orders?: IbkrLiveOrder[];
+    snapshot?: boolean;
+}
+export interface IbkrBrokerageAccountsResponse {
+    accounts?: string[];
+    selectedAccount?: string;
+}
+export interface IbkrSwitchAccountResponse {
+    set?: boolean;
+    acctId?: string;
+}
+export interface IbkrLiveOrder {
+    account?: string;
+    acct?: string;
+    orderId?: number | string;
+    order_id?: number | string;
+    conid?: number;
+    ticker?: string;
+    symbol?: string;
+    description1?: string;
+    contractDescription1?: string;
+    contract_description_1?: string;
+    side?: string;
+    orderType?: string;
+    order_type?: string;
+    orderStatus?: string;
+    order_status?: string;
+    status?: string;
+    totalSize?: string | number;
+    total_size?: string | number;
+    size?: string | number;
+    cumFill?: string | number;
+    cum_fill?: string | number;
+    filledQuantity?: string | number;
+    remainingQuantity?: string | number;
+    sizeAndFills?: string;
+    size_and_fills?: string;
+    avgPrice?: string | number;
+    averagePrice?: string | number;
+    average_price?: string | number;
+    price?: string | number;
+    limitPrice?: string | number;
+    stopPrice?: string | number;
+    orderDescription?: string;
+    order_description?: string;
+    orderDesc?: string;
+    orderDescriptionWithContract?: string;
+    order_description_with_contract?: string;
+    lastExecutionTime?: string;
+    lastExecutionTime_r?: number;
+    orderTime?: string;
+    order_time?: string;
+}
 /** One OHLCV bar from `iserver/marketdata/history`. */
 export interface IbkrMarketDataHistoryBar {
     o?: number;

package/dist/ibkr/ibkrApiTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ibkrApiTypes.d.ts","sourceRoot":"","sources":["../../src/ibkr/ibkrApiTypes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ibkrApiTypes.d.ts","sourceRoot":"","sources":["../../src/ibkr/ibkrApiTypes.ts"],"names":[],"mappings":"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"}

package/dist/ibkr/ibkrClient.d.ts

@@ -1,5 +1,5 @@
 import type { IbkrOauth1Config } from "./oauthConfig.js";
-import type { AccountBalances, AuthStatus, BrokerClient, BrokerPosition, BrokerQuote, OptionContract, OptionMarketQuote, OptionQuoteRequest, OptionRight, PriceHistoryBar, PriceHistoryRequest } from "../types.js";
+import type { AccountBalances, AuthStatus, BrokerAccountOrders, BrokerClient, BrokerInstrument, BrokerInstrumentSearchProjection, BrokerOrdersOptions, BrokerPosition, BrokerQuote, BrokerTransactionHistory, OptionContract, OptionMarketQuote, OptionQuoteRequest, OptionRight, PriceHistoryBar, PriceHistoryRequest } from "../types.js";
 /**
  * Typed IBKR Web API client implementing the broker-neutral {@link BrokerClient}.
  * Wraps the `ibkr-client` npm package, which performs the OAuth 1.0a
@@ -25,7 +25,10 @@ export declare class IbkrClient implements BrokerClient {
     private normalizePosition;
     getQuotes(symbols: string[]): Promise<Record<string, BrokerQuote>>;
     /** Resolve equity/ETF symbols to IBKR contracts via `trsrv/stocks`. */
-    private searchInstruments;
+    searchInstruments(symbol: string, projection?: BrokerInstrumentSearchProjection): Promise<BrokerInstrument[]>;
+    fetchTransactionHistory(startDate: Date, endDate: Date): Promise<BrokerTransactionHistory[]>;
+    fetchOrders(options: BrokerOrdersOptions): Promise<BrokerAccountOrders[]>;
+    private prepareBrokerageAccount;
     private normalizeStockListing;
     private normalizeStockContract;
     private resolveQuoteContract;
@@ -45,6 +48,24 @@ export declare class IbkrClient implements BrokerClient {
     private fetchOptionQuotes;
     private historyDays;
     private fetchQuoteHistory;
+    private normalizeTransaction;
+    private normalizeOrder;
+    private normalizeOrderLeg;
+    private normalizeOrderStatus;
+    private normalizeOrderType;
+    private normalizeOrderSide;
+    private ibkrStatusFilter;
+    private orderMatchesStatus;
+    private orderBelongsToAccount;
+    private orderInDateRange;
+    private orderTimeMs;
+    private parseOrderTime;
+    private firstNumber;
+    private firstPositiveNumber;
+    private quantityFromDescription;
+    private filledQuantityFromSizeAndFills;
+    private parseTransactionTime;
+    private transactionKey;
     /** Overridable in request-level tests so snapshot warm-up does not sleep. */
     protected wait(ms: number): Promise<void>;
     private normalizeQuote;

package/dist/ibkr/ibkrClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ibkrClient.d.ts","sourceRoot":"","sources":["../../src/ibkr/ibkrClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ibkrClient.d.ts","sourceRoot":"","sources":["../../src/ibkr/ibkrClient.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EACV,eAAe,EACf,UAAU,EACV,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,gCAAgC,EAGhC,mBAAmB,EACnB,cAAc,EACd,WAAW,EAEX,wBAAwB,EACxB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAmLrB;;;;;GAKG;AACH,qBAAa,UAAW,YAAW,YAAY;IAC7C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IACpC,OAAO,CAAC,WAAW,CAAC,CAAgB;IACpC,OAAO,CAAC,gBAAgB,CAAC,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgD;gBAEpE,MAAM,EAAE,gBAAgB;IAIpC,6EAA6E;IAC7E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IASf,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC;IAWpC,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAY/B,kBAAkB,IAAI,OAAO,CAAC,eAAe,CAAC;IAc9C,YAAY,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAa9D,yEAAyE;YAC3D,iBAAiB;IAc/B,kFAAkF;YACpE,WAAW;IAqBzB,OAAO,CAAC,iBAAiB;IAsBnB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAyCxE,uEAAuE;IACjE,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,gCAAkD,GAC7D,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAiBxB,uBAAuB,CAC3B,SAAS,EAAE,IAAI,EACf,OAAO,EAAE,IAAI,GACZ,OAAO,CAAC,wBAAwB,EAAE,CAAC;IAoChC,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;YA2BjE,uBAAuB;IAerC,OAAO,CAAC,qBAAqB;IAgB7B,OAAO,CAAC,sBAAsB;YAehB,oBAAoB;IAgClC,qFAAqF;IAC/E,eAAe,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IA4B7E,mFAAmF;IAC7E,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,EAAE,CAAC;IAuBpB,2FAA2F;IACrF,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAclF,2EAA2E;IACrE,cAAc,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAMlF,2EAA2E;IACrE,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;YAgBxD,qBAAqB;IAYnC,OAAO,CAAC,eAAe;YAWT,mBAAmB;YAgEnB,iBAAiB;IAiE/B,OAAO,CAAC,WAAW;YAeL,iBAAiB;IAqB/B,OAAO,CAAC,oBAAoB;IA2C5B,OAAO,CAAC,cAAc;IAsDtB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,oBAAoB;IAS5B,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,cAAc;IAyBtB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,uBAAuB;IAS/B,OAAO,CAAC,8BAA8B;IAOtC,OAAO,CAAC,oBAAoB;IAmC5B,OAAO,CAAC,cAAc;IAUtB,6EAA6E;IAC7E,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,OAAO,CAAC,cAAc;IAoDtB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,cAAc;IAmBtB,iEAAiE;cACjD,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE;QACpC,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;QACtE,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,CAAC,CAAC;cAIE,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE;QAC5B,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;QACtE,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,CAAC,CAAC;IAkBd,OAAO,CAAC,mBAAmB;IAqB3B,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,WAAW;CAuBpB"}

package/dist/ibkr/ibkrClient.js

@@ -39,6 +39,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;
@@ -221,8 +242,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 +289,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 +302,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 ?? [];
@@ -561,6 +654,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);