From 37b6c1a8ee0629a19bd1a78d0f835f97f19327fd Mon Sep 17 00:00:00 2001
From: Christopher Downie
Date: Tue, 13 Oct 2026 17:38:52 -0500
Subject: [PATCH] fix: import IBKR Flex Query XML uploads in the statement
timezone
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Import → File upload accepted .xml files but no importer read Flex Query XML,
so a Flex statement fell through to the column mapper and could not be
imported. The Default import timezone therefore never applied (#16).
Uploads now use the broker SDK's Flex parser, the same parser broker sync
uses, with the statement timezone from the upload form. Sync and upload share
one SDK-trade mapping, so the same fill hashes identically from either path.
- Skip order/lot summary rows so fills are not counted twice
- Refuse statements that mix IBKR accounts
- Refuse uploads into an IBKR sync account in a timezone other than the one
it syncs with, which would otherwise store every fill twice
- Report zero-price and untimed rows instead of guessing
- Return a 400, not a 500, for a UTC offset statement timezone
Fixes #16
---
CHANGELOG.md | 1 +
README.md | 8 +-
apps/web/src/app/api/import/route.ts | 24 +-
apps/web/src/app/import/page.tsx | 10 +-
apps/web/src/server/broker-trades.ts | 28 ++
apps/web/src/server/ibkr-flex-xml-import.ts | 122 +++++++++
apps/web/src/server/sync.ts | 23 +-
apps/web/tests/ibkr-flex-xml-import.test.ts | 268 ++++++++++++++++++++
docs/importers.md | 31 ++-
9 files changed, 480 insertions(+), 35 deletions(-)
create mode 100644 apps/web/src/server/broker-trades.ts
create mode 100644 apps/web/src/server/ibkr-flex-xml-import.ts
create mode 100644 apps/web/tests/ibkr-flex-xml-import.test.ts
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 89250b0c..d5150f48 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -34,6 +34,7 @@ All notable changes to this project are documented here. The format follows [Kee
### Fixed
+- IBKR Flex Query XML statements can be uploaded on Import → File upload, and their times are read in the statement timezone, as broker sync does. Previously an XML upload was not recognized and could not be imported, so the Default import timezone never applied ([#16](https://github.com/LuxAlgo/trade-journal/issues/16)).
- Password protection now verifies the session signature on every API route. Previously, when `JOURNAL_PASSWORD` was set, any request carrying a cookie of the right name was accepted, so a forged cookie could read the journal.
## [0.1.0] - 2026-09-03
diff --git a/README.md b/README.md
index 1c97ac0e..caba9e34 100644
--- a/README.md
+++ b/README.md
@@ -112,7 +112,7 @@ One primitive drives everything: a raw **execution** (a fill). Executions come i
```mermaid
flowchart LR
BS["Broker sync (broker-sdk)"] --> EX["Executions (deduped fills)"]
- IM["14 documented statement formats + CSV mapper"] --> EX
+ IM["15 documented statement formats + CSV mapper"] --> EX
MN["Manual entry"] --> EX
EX --> RT["Round-trip engine (FIFO / LIFO / WAVG)"]
RT --> D["Dashboard + calendar"]
@@ -129,7 +129,7 @@ flowchart LR
| | |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Broker sync** | Read-only sync via [`@luxalgo/broker-sdk`](https://github.com/LuxAlgo/broker-sdk): Alpaca, Binance, Bybit, Coinbase, Kraken, OKX, Tradier, IBKR Flex, Hyperliquid, Questrade, Topstep, Trading212, Webull, Crypto.com, E*TRADE, Public, Charles Schwab, TradeStation, tastytrade, Robinhood Crypto, Gemini, and KuCoin. Connect forms render straight from SDK metadata. |
-| **Statement import** | **14 documented formats**, auto-detected: **TradeZella** and **Tradervue** (CSV migration), TradingView (paper and strategy exports), MetaTrader 4 and 5, ThinkorSwim, IBKR (activity + Flex), NinjaTrader, Tradovate, TopstepX, Webull, DAS Trader, plus a column mapper for any other CSV. Matching execution records dedupe within an account; review warnings and skipped rows before committing an import. Have an export we don't recognize? Open an issue with an anonymized sample; real files are the most useful contribution this repo can get. |
+| **Statement import** | **15 documented formats**, auto-detected: **TradeZella** and **Tradervue** (CSV migration), TradingView (paper and strategy exports), MetaTrader 4 and 5, ThinkorSwim, IBKR (activity + Flex), NinjaTrader, Tradovate, TopstepX, Webull, DAS Trader, plus a column mapper for any other CSV. Matching execution records dedupe within an account; review warnings and skipped rows before committing an import. Have an export we don't recognize? Open an issue with an anonymized sample; real files are the most useful contribution this repo can get. |
| **Round-trip engine** | Flat-to-flat position cycles from raw fills. FIFO / LIFO / weighted-average per account. Partial fills, scale-ins, flips, futures multipliers. Annotations survive rebuilds. |
| **Analytics** | Net/gross P&L, win and day-win rates, profit factor, expectancy, R multiples, streaks, drawdown and recovery, profit concentration, duration/time-of-day/weekday performance, per-symbol/tag/mistake/playbook breakdowns. Advanced filters on every dimension, comparison groups, and a two-way cross-analysis matrix. Reports also include rolling performance trends and a trade explorer scatter plot, with saved MAE/MFE estimates where available. |
| **Dashboard** | P&L calendar with weekly totals, cumulative and daily P&L, gauges, the open **Edge Score v2** radar, open positions, time-of-day performance. Drag cards to rearrange, hide what you don't use, save named layouts. Calendar insights highlight daily patterns. Light/dark themes, a collapsible sidebar, and mobile navigation support smaller screens. |
@@ -142,8 +142,8 @@ flowchart LR
| **Prop firms** | Evaluation and reset expenses, refunds, payout requests, partial receipts, reversals, cash ROI, account phases, renewal reminders, attachments, and generic cash CSV import/export. Separate from trade P&L. |
| **Privacy & export** | Privacy mode masks every monetary value (charts keep their shape) and persists across tabs. Trades export to CSV, reviews to PDF or PNG, and journal records to JSON; credentials, candle datasets, and attachment binaries are excluded from that export. |
-IBKR broker sync uses **Settings → General → Default import timezone** for Flex
-timestamps without an offset. Existing synced accounts with unknown or different
+IBKR broker sync and uploaded Flex XML statements use **Settings → General →
+Default import timezone** for Flex timestamps without an offset. Existing synced accounts with unknown or different
timezone provenance require recovery into a separate account; see
[IBKR timezone recovery](docs/importers.md#ibkr-broker-sync-and-timezone-recovery).
diff --git a/apps/web/src/app/api/import/route.ts b/apps/web/src/app/api/import/route.ts
index ffb44122..d698ee54 100644
--- a/apps/web/src/app/api/import/route.ts
+++ b/apps/web/src/app/api/import/route.ts
@@ -12,6 +12,12 @@ import { getImportTimeZone } from "@/server/settings";
import { isTimeZone } from "@/lib/timezone";
import type { ImportReviewOptions } from "@/lib/import-review";
import { previewNinjaTraderImport, commitNinjaTraderImport } from "@/server/ninjatrader-import";
+import {
+ IBKR_FLEX_XML,
+ flexUploadSyncProblem,
+ looksLikeFlexXml,
+ parseFlexXmlImport,
+} from "@/server/ibkr-flex-xml-import";
import type { AiImportOptions } from "@/lib/ai-import";
import {
createAiImportPreview,
@@ -75,7 +81,9 @@ export const POST = handler(async (request: Request) => {
: readAiImportPreview(statement, body.aiPreviewToken!)
: body.mapping
? parseWithMapping(body.content, body.mapping, { timeZone })
- : parseAuto(body.content, { timeZone, fileName: body.fileName, symbol: body.symbol });
+ : looksLikeFlexXml(body.content)
+ ? parseFlexXmlImport(body.content, timeZone)
+ : parseAuto(body.content, { timeZone, fileName: body.fileName, symbol: body.symbol });
if (!parsed) {
return ok({
@@ -86,6 +94,12 @@ export const POST = handler(async (request: Request) => {
});
}
+ const syncProblem =
+ parsed.format === IBKR_FLEX_XML.id && body.accountId
+ ? flexUploadSyncProblem(body.accountId, timeZone)
+ : null;
+ const errors = [...(parsed.errors ?? []), ...(syncProblem ? [syncProblem] : [])];
+
if (body.mode === "preview") {
const symbols = [...new Set(parsed.executions.map((e) => e.symbol))];
return ok({
@@ -113,7 +127,7 @@ export const POST = handler(async (request: Request) => {
),
},
warnings: parsed.warnings,
- errors: parsed.errors,
+ errors: syncProblem ? errors : parsed.errors,
needsSymbol: parsed.needsSymbol,
reconciliation:
parsed.format === "ninjatrader" && body.accountId
@@ -123,7 +137,7 @@ export const POST = handler(async (request: Request) => {
}
if (!body.accountId) return bad("accountId is required to commit");
- if (parsed.errors?.length) return bad(parsed.errors.join(" "));
+ if (errors.length) return bad(errors.join(" "));
if (parsed.executions.length === 0) return bad("No executions to import");
const result =
parsed.format === "ninjatrader"
@@ -148,4 +162,6 @@ export const POST = handler(async (request: Request) => {
});
/** The import page lists what auto-detection understands. */
-export const GET = handler(() => ok({ formats: FORMATS.map(({ id, label }) => ({ id, label })) }));
+export const GET = handler(() =>
+ ok({ formats: [...FORMATS, IBKR_FLEX_XML].map(({ id, label }) => ({ id, label })) }),
+);
diff --git a/apps/web/src/app/import/page.tsx b/apps/web/src/app/import/page.tsx
index 14ad0871..d0d11705 100644
--- a/apps/web/src/app/import/page.tsx
+++ b/apps/web/src/app/import/page.tsx
@@ -403,8 +403,12 @@ function FileImport() {
) : (
<>
Auto-detected:{" "}
- {formatData?.formats.map((format) => format.label.split(" (")[0]).join(", ")} —
- anything else via column mapping.
+ {[
+ ...new Set(
+ formatData?.formats.map((format) => format.label.split(" (")[0]) ?? [],
+ ),
+ ].join(", ")}{" "}
+ — anything else via column mapping.
>
)}
@@ -766,7 +770,7 @@ function BrokerConnect() {
{settingsError
? "Could not load the import timezone. Refresh and try again."
: settingsData
- ? `Statement timezone: ${settingsData.importTimeZone}. Used for Flex timestamps without an offset. Change it in Settings → Journal before connecting.`
+ ? `Statement timezone: ${settingsData.importTimeZone}. Used for Flex timestamps without an offset, and required for Flex XML files uploaded into this account. Change it in Settings → Journal before connecting.`
: "Loading statement timezone…"}
)}
diff --git a/apps/web/src/server/broker-trades.ts b/apps/web/src/server/broker-trades.ts
new file mode 100644
index 00000000..061d2b9e
--- /dev/null
+++ b/apps/web/src/server/broker-trades.ts
@@ -0,0 +1,28 @@
+import type { Trade } from "@luxalgo/broker-sdk";
+import type { ImportedExecution } from "@luxalgo/journal-importers";
+
+/**
+ * SDK fills as journal executions. Broker sync and statement uploads share this
+ * mapping so the same fill has the same content hash from either path.
+ */
+export const brokerTradesToExecutions = (
+ trades: Trade[],
+): { timed: ImportedExecution[]; untimed: number } => {
+ const rows: ImportedExecution[] = trades.map((trade) => ({
+ symbol: trade.symbol,
+ side: trade.side,
+ quantity: trade.quantity,
+ price: trade.price,
+ fee: trade.fee ?? 0,
+ // The SDK omits unparseable timestamps; a fill with no time can't be
+ // journaled meaningfully, so it is dropped rather than guessed at.
+ executedAt: trade.executedAt ?? "",
+ }));
+ const timed = rows.filter((row) => row.executedAt !== "");
+ return { timed, untimed: rows.length - timed.length };
+};
+
+export const untimedFillsReason = (untimed: number, statementTimeZone: boolean): string =>
+ statementTimeZone
+ ? `${untimed} fill(s) had no usable timestamp. Check for missing or invalid dates, unsupported timezone suffixes, or ambiguous or nonexistent daylight-saving times.`
+ : `${untimed} fill(s) had no usable timestamp.`;
diff --git a/apps/web/src/server/ibkr-flex-xml-import.ts b/apps/web/src/server/ibkr-flex-xml-import.ts
new file mode 100644
index 00000000..1432136f
--- /dev/null
+++ b/apps/web/src/server/ibkr-flex-xml-import.ts
@@ -0,0 +1,122 @@
+import { BrokerError } from "@luxalgo/broker-sdk";
+import { parseFlexStatement } from "@luxalgo/broker-sdk/adapters";
+import type { ParsedImport } from "@luxalgo/journal-importers";
+import { eq } from "drizzle-orm";
+import { accounts, db } from "@/db";
+import { RequestError, requireValue } from "./api";
+import { brokerTradesToExecutions, untimedFillsReason } from "./broker-trades";
+import {
+ assertIbkrSyncTimeZone,
+ canonicalImportTimeZone,
+ isIbkrSyncAccount,
+} from "./ibkr-sync-timezone";
+import { getImportTimeZone } from "./settings";
+
+export const IBKR_FLEX_XML = { id: "ibkr-flex-xml", label: "Interactive Brokers (Flex Query XML)" };
+
+/** A Flex Query response or statement, optionally after an XML declaration and comments. */
+export const looksLikeFlexXml = (content: string): boolean =>
+ /^\s*(?:<\?xml[^>]*\?>\s*)?(?:\s*)*<(?:FlexQueryResponse|FlexStatements?)[\s>]/.test(
+ content.replace(/^/, ""),
+ );
+
+/** Attribute maps for one element name, read the same way as the SDK's Flex parser. */
+const elements = (xml: string, tag: string): Record[] =>
+ [...xml.matchAll(new RegExp(`<${tag}\\s([^>]*?)/?>`, "g"))].map((match) =>
+ Object.fromEntries(
+ [...(match[1] ?? "").matchAll(/([\w-]+)="([^"]*)"/g)].map((pair) => [pair[1]!, pair[2]!]),
+ ),
+ );
+
+const isSummaryRow = (trade: Record): boolean =>
+ Boolean(trade.levelOfDetail) && trade.levelOfDetail!.toUpperCase() !== "EXECUTION";
+
+/**
+ * Parse an uploaded Flex Query XML statement with the broker SDK's Flex parser,
+ * the same parser broker sync uses. Naive `dateTime` values are read in the
+ * statement timezone, so the "Default import timezone" setting applies to
+ * uploads exactly as it applies to sync.
+ */
+export const parseFlexXmlImport = (content: string, timeZone: string): ParsedImport => {
+ requireValue(
+ !/^[+-]/.test(timeZone.trim()),
+ "Choose a named IANA statement timezone for IBKR Flex statements, such as America/New_York, not a UTC offset.",
+ );
+ const zone = canonicalImportTimeZone(timeZone);
+ const errors: string[] = [];
+ const warnings: string[] = [];
+
+ const rows = elements(content, "Trade");
+ const accountIds = new Set(
+ [...elements(content, "FlexStatement"), ...rows]
+ .map((attrs) => attrs.accountId?.trim())
+ .filter((id): id is string => Boolean(id)),
+ );
+ if (accountIds.size > 1)
+ errors.push(
+ `This Flex statement contains ${accountIds.size} IBKR accounts (${[...accountIds].join(", ")}). Export one account per Flex Query, or import each account's statement into its own journal account.`,
+ );
+
+ // Order, closed-lot and summary rows repeat the executions they summarize.
+ const summaries = rows.filter(isSummaryRow);
+ const executionXml = summaries.length
+ ? content.replace(/]*?\/?>/g, (tag) =>
+ isSummaryRow(elements(tag, "Trade")[0] ?? {}) ? "" : tag,
+ )
+ : content;
+ if (summaries.length)
+ warnings.push(
+ `${summaries.length} Trade summary row(s) (${[...new Set(summaries.map((row) => row.levelOfDetail))].join(", ")}) were skipped; only execution rows are imported.`,
+ );
+
+ let parsed: ReturnType;
+ try {
+ parsed = parseFlexStatement(executionXml, { statementTimeZone: zone });
+ } catch (error) {
+ if (error instanceof BrokerError) requireValue(false, error.message);
+ throw error;
+ }
+
+ const { timed, untimed } = brokerTradesToExecutions(parsed.trades);
+ const dropped = rows.length - summaries.length - parsed.trades.length;
+ if (dropped > 0)
+ warnings.push(
+ `${dropped} Trade row(s) were skipped: a missing symbol, side, quantity or price, or a zero price such as an option expiry or assignment.`,
+ );
+ if (untimed > 0)
+ warnings.push(
+ `${untimedFillsReason(untimed, true)} Flex dates must use the default yyyyMMdd date and HHmmss time formats.`,
+ );
+ if (timed.length === 0 && errors.length === 0)
+ errors.push(
+ "No executions could be read from this Flex statement. Include the Trades section at Execution level in the Flex Query.",
+ );
+
+ return {
+ format: IBKR_FLEX_XML.id,
+ executions: timed,
+ skippedRows: dropped + untimed,
+ warnings,
+ ...(errors.length ? { errors } : {}),
+ };
+};
+
+/**
+ * An upload into an IBKR sync account must use the statement timezone sync
+ * uses, or the same fills would hash differently and be stored twice.
+ */
+export const flexUploadSyncProblem = (accountId: string, zone: string): string | null => {
+ const account = db.select().from(accounts).where(eq(accounts.id, accountId)).get();
+ if (!account || (!isIbkrSyncAccount(account) && account.ibkrSyncTimeZone === null)) return null;
+ const syncZone = canonicalImportTimeZone(account.ibkrSyncTimeZone ?? getImportTimeZone());
+ const uploadZone = canonicalImportTimeZone(zone);
+ if (uploadZone !== syncZone)
+ return `This account syncs IBKR statements in ${syncZone}, but this upload uses ${uploadZone}. Upload with the ${syncZone} statement timezone so uploaded and synced fills match, or import into a separate account.`;
+ try {
+ assertIbkrSyncTimeZone(account, uploadZone);
+ } catch (error) {
+ if (error instanceof RequestError) return error.message;
+ throw error;
+ }
+ return null;
+};
diff --git a/apps/web/src/server/sync.ts b/apps/web/src/server/sync.ts
index e58995d8..f7eb71b9 100644
--- a/apps/web/src/server/sync.ts
+++ b/apps/web/src/server/sync.ts
@@ -1,9 +1,9 @@
import { connect, listBrokers, type BrokerId } from "@luxalgo/broker-sdk";
import { eq } from "drizzle-orm";
-import type { ImportedExecution } from "@luxalgo/journal-importers";
import { accounts, db } from "@/db";
import { decryptJson, encryptJson } from "./crypto";
import { nowIso } from "./ids";
+import { brokerTradesToExecutions, untimedFillsReason } from "./broker-trades";
import { insertExecutions, type InsertResult } from "./executions";
import { getImportTimeZone } from "./settings";
import { requireValue } from "./api";
@@ -52,20 +52,9 @@ export const syncAccount = async (accountId: string): Promise => {
const snapshot = await connection.fetchSnapshot();
const syncedAt = nowIso();
- const rows: ImportedExecution[] = snapshot.accounts.flatMap((brokerAccount) =>
- brokerAccount.trades.map((trade) => ({
- symbol: trade.symbol,
- side: trade.side,
- quantity: trade.quantity,
- price: trade.price,
- fee: trade.fee ?? 0,
- // The SDK omits unparseable timestamps; a fill with no time can't be
- // journaled meaningfully, so it is dropped rather than guessed at.
- executedAt: trade.executedAt ?? "",
- })),
+ const { timed, untimed } = brokerTradesToExecutions(
+ snapshot.accounts.flatMap((brokerAccount) => brokerAccount.trades),
);
- const timed = rows.filter((row) => row.executedAt !== "");
- const untimed = rows.length - timed.length;
const equity = snapshot.accounts.reduce((total, a) => total + a.equity, 0);
const positions = snapshot.accounts.flatMap((a) => a.positions);
@@ -100,11 +89,7 @@ export const syncAccount = async (accountId: string): Promise => {
if (untimed > 0) {
result.skipped += untimed;
if (result.skippedReasons.length < 5)
- result.skippedReasons.push(
- statementTimeZone !== undefined
- ? `${untimed} fill(s) had no usable timestamp. Check for missing or invalid dates, unsupported timezone suffixes, or ambiguous or nonexistent daylight-saving times.`
- : `${untimed} fill(s) had no usable timestamp.`,
- );
+ result.skippedReasons.push(untimedFillsReason(untimed, statementTimeZone !== undefined));
}
return { accountId, ...result, equity, positions: positions.length, syncedAt };
diff --git a/apps/web/tests/ibkr-flex-xml-import.test.ts b/apps/web/tests/ibkr-flex-xml-import.test.ts
new file mode 100644
index 00000000..d3f27567
--- /dev/null
+++ b/apps/web/tests/ibkr-flex-xml-import.test.ts
@@ -0,0 +1,268 @@
+import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { eq } from "drizzle-orm";
+import { formatTimestamp } from "../src/lib/timezone";
+
+const scratch = mkdtempSync(join(tmpdir(), "journal-flex-xml-"));
+vi.stubEnv("JOURNAL_DATA_DIR", scratch);
+vi.stubEnv("JOURNAL_PASSWORD", "");
+vi.mock("next/headers", () => ({ cookies: async () => ({ get: () => undefined }) }));
+const { db, accounts, executions, trades, settings } = await import("../src/db");
+const { encryptJson } = await import("../src/server/crypto");
+const { setSetting } = await import("../src/server/settings");
+const { syncAccount } = await import("../src/server/sync");
+const { POST: importFile, GET: importFormats } = await import("../src/app/api/import/route");
+const { GET: tradeDetail } = await import("../src/app/api/trades/[key]/route");
+
+// Synthetic fills shaped like the #16 report: NYMEX MCL executions whose Flex
+// dateTime carries no offset and is in the exchange's local time.
+interface Fill {
+ time: string;
+ side?: "BUY" | "SELL";
+ price?: string;
+ extra?: string;
+}
+const reported: Fill[] = [
+ { time: "20260918;085905", side: "BUY", price: "68.12" },
+ { time: "20260918;100830", side: "SELL", price: "68.40" },
+];
+const flexXml = (fills: Fill[] = reported, account = "U_TEST") =>
+ `
+
+
+
+
+${fills
+ .map(
+ ({ time, side = "BUY", price = "68.12", extra = "" }) =>
+ ``,
+ )
+ .join("\n")}
+
+
+
+`;
+
+const post = (body: object) =>
+ importFile(
+ new Request("http://localhost/api/import", { method: "POST", body: JSON.stringify(body) }),
+ );
+const preview = async (content: string, extra: object = {}) =>
+ (
+ await post({ mode: "preview", accountId: "file", content, fileName: "flex.xml", ...extra })
+ ).json();
+const commit = (content: string, extra: object = {}) =>
+ post({ mode: "commit", accountId: "file", content, fileName: "flex.xml", ...extra });
+const times = (rows: { executedAt: string }[]) => rows.map((row) => row.executedAt).sort();
+const stored = (accountId = "file") =>
+ db.select().from(executions).where(eq(executions.accountId, accountId)).all();
+
+let statement = flexXml();
+const mockFlexService = () =>
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async (input) => {
+ const url = String(input);
+ if (url.includes("/SendRequest?"))
+ return new Response(
+ "Successtest",
+ );
+ if (url.includes("/GetStatement?")) return new Response(statement);
+ throw new Error(`Unexpected network request: ${url}`);
+ }),
+ );
+
+beforeEach(() => {
+ db.delete(trades).run();
+ db.delete(executions).run();
+ db.delete(accounts).run();
+ db.delete(settings).run();
+ db.insert(accounts)
+ .values({ id: "file", name: "IBKR file", kind: "import", createdAt: "2026-01-01" })
+ .run();
+ db.insert(accounts)
+ .values({
+ id: "ibkr",
+ name: "IBKR sync",
+ kind: "sync",
+ broker: "ibkr-flex",
+ credentialsEnc: encryptJson({ flexToken: "test-only", flexQueryId: "test-only" }),
+ createdAt: "2026-01-01",
+ })
+ .run();
+ setSetting("importTimeZone", "America/New_York");
+ setSetting("timeZone", "Europe/Rome");
+ statement = flexXml();
+ mockFlexService();
+});
+afterEach(() => vi.unstubAllGlobals());
+afterAll(() => {
+ db.$client.close();
+ vi.unstubAllEnvs();
+ rmSync(scratch, { recursive: true, force: true });
+});
+
+describe("IBKR Flex Query XML upload honours the statement timezone (#16)", () => {
+ it("stores the report's New York fills at the right instant and shows them in Rome", async () => {
+ const result = await preview(flexXml());
+ expect(result).toMatchObject({
+ detected: "ibkr-flex-xml",
+ needsMapping: false,
+ timeZone: "America/New_York",
+ totals: { executions: 2, skippedRows: 0 },
+ });
+ expect(result.errors).toBeUndefined();
+ expect(times(result.executions)).toEqual([
+ "2026-09-18T12:59:05.000Z",
+ "2026-09-18T14:08:30.000Z",
+ ]);
+
+ const response = await commit(flexXml());
+ expect(response.status).toBe(200);
+ expect(await response.json()).toMatchObject({ inserted: 2, duplicates: 0 });
+ const trade = db.select().from(trades).get()!;
+ expect(trade).toMatchObject({
+ openedAt: "2026-09-18T12:59:05.000Z",
+ closedAt: "2026-09-18T14:08:30.000Z",
+ });
+ const detail = await (
+ await tradeDetail(new Request("http://localhost/api/trades/x"), {
+ params: Promise.resolve({ key: trade.key }),
+ })
+ ).json();
+ expect(
+ detail.executions
+ .map((fill: { executedAt: string }) => formatTimestamp(fill.executedAt, detail.timeZone))
+ .sort(),
+ ).toEqual(["2026-09-18 14:59:05", "2026-09-18 16:08:30"]);
+ });
+
+ it.each([
+ ["UTC", ["2026-09-18T08:59:05.000Z", "2026-09-18T10:08:30.000Z"]],
+ ["America/New_York", ["2026-09-18T12:59:05.000Z", "2026-09-18T14:08:30.000Z"]],
+ ["Pacific/Kiritimati", ["2026-09-17T18:59:05.000Z", "2026-09-17T20:08:30.000Z"]],
+ ])("reads naive Flex times in the chosen timezone %s", async (timeZone, expected) => {
+ setSetting("importTimeZone", timeZone);
+ expect(times((await preview(flexXml())).executions)).toEqual(expected);
+ expect(times((await preview(flexXml(), { timeZone })).executions)).toEqual(expected);
+ });
+
+ it("keeps an explicit offset regardless of the statement timezone", async () => {
+ const result = await preview(flexXml([{ time: "20260918;085905-0500" }]), {
+ timeZone: "Pacific/Kiritimati",
+ });
+ expect(times(result.executions)).toEqual(["2026-09-18T13:59:05.000Z"]);
+ });
+
+ it("treats a re-upload of the same statement as duplicates", async () => {
+ expect(await (await commit(flexXml())).json()).toMatchObject({ inserted: 2 });
+ expect(await (await commit(flexXml())).json()).toMatchObject({ inserted: 0, duplicates: 2 });
+ expect(stored()).toHaveLength(2);
+ });
+
+ it("lists Flex XML among the auto-detected formats", async () => {
+ const { formats } = await (await importFormats()).json();
+ expect(formats).toContainEqual({
+ id: "ibkr-flex-xml",
+ label: "Interactive Brokers (Flex Query XML)",
+ });
+ });
+});
+
+describe("Flex XML uploads into an IBKR sync account", () => {
+ it("matches synced fills exactly when uploaded in the sync timezone", async () => {
+ expect(await syncAccount("ibkr")).toMatchObject({ inserted: 2 });
+ const response = await commit(flexXml(), { accountId: "ibkr" });
+ expect(response.status).toBe(200);
+ expect(await response.json()).toMatchObject({ inserted: 0, duplicates: 2 });
+ expect(stored("ibkr").map((row) => row.source)).toEqual(["sync", "sync"]);
+ });
+
+ it("refuses an upload in another timezone instead of storing every fill twice", async () => {
+ await syncAccount("ibkr");
+ const before = stored("ibkr");
+ const previewed = await preview(flexXml(), { accountId: "ibkr", timeZone: "UTC" });
+ expect(previewed.errors.join(" ")).toMatch(/syncs IBKR statements in America\/New_York/);
+ const response = await commit(flexXml(), { accountId: "ibkr", timeZone: "UTC" });
+ expect(response.status).toBe(400);
+ expect((await response.json()).error).toMatch(/upload uses UTC/);
+ expect(stored("ibkr")).toEqual(before);
+ });
+
+ it("uses the zone the next sync will use when nothing has synced yet", async () => {
+ const response = await commit(flexXml(), { accountId: "ibkr", timeZone: "Europe/Rome" });
+ expect(response.status).toBe(400);
+ expect(stored("ibkr")).toHaveLength(0);
+ expect((await commit(flexXml(), { accountId: "ibkr" })).status).toBe(200);
+ expect(await syncAccount("ibkr")).toMatchObject({ inserted: 0, duplicates: 2 });
+ });
+
+ it("refuses an upload into history synced before timezone-aware sync", async () => {
+ await syncAccount("ibkr");
+ db.update(accounts).set({ ibkrSyncTimeZone: null }).where(eq(accounts.id, "ibkr")).run();
+ const response = await commit(flexXml(), { accountId: "ibkr" });
+ expect(response.status).toBe(400);
+ expect((await response.json()).error).toMatch(/before timezone-aware sync/);
+ });
+});
+
+describe("Flex XML statements that cannot be imported as-is", () => {
+ it("refuses a statement that mixes IBKR accounts", async () => {
+ const mixed = flexXml().replace(
+ "",
+ ``,
+ );
+ const result = await preview(mixed);
+ expect(result.errors.join(" ")).toMatch(/2 IBKR accounts \(U_TEST, U_OTHER\)/);
+ expect((await commit(mixed)).status).toBe(400);
+ expect(stored()).toHaveLength(0);
+ });
+
+ it("skips order and lot summaries so fills are not counted twice", async () => {
+ const result = await preview(
+ flexXml([
+ ...reported,
+ {
+ time: "20260918;085905",
+ side: "BUY",
+ price: "68.12",
+ extra: ' levelOfDetail="ORDER"',
+ },
+ ]).replace('levelOfDetail="EXECUTION" levelOfDetail="ORDER"', 'levelOfDetail="ORDER"'),
+ );
+ expect(result.totals.executions).toBe(2);
+ expect(result.warnings.join(" ")).toMatch(/1 Trade summary row\(s\) \(ORDER\) were skipped/);
+ });
+
+ it("reports zero-price and unreadable rows instead of guessing", async () => {
+ const result = await preview(
+ flexXml([
+ ...reported,
+ { time: "20260918;160000", side: "SELL", price: "0" },
+ { time: "2026-09-18;16:00:00" },
+ ]),
+ );
+ expect(result.totals).toMatchObject({ executions: 2, skippedRows: 2 });
+ expect(result.warnings.join(" ")).toMatch(/1 Trade row\(s\) were skipped.*zero price/);
+ expect(result.warnings.join(" ")).toMatch(/1 fill\(s\) had no usable timestamp.*yyyyMMdd/);
+ });
+
+ it("returns a clear error for a statement without executions", async () => {
+ const empty = flexXml([]);
+ expect((await preview(empty)).errors.join(" ")).toMatch(/Execution level/);
+ expect((await commit(empty)).status).toBe(400);
+ });
+
+ it("rejects a UTC offset as the statement timezone with a 400, not a crash", async () => {
+ const response = await post({ mode: "preview", content: flexXml(), timeZone: "+02:00" });
+ expect(response.status).toBe(400);
+ expect((await response.json()).error).toMatch(/named IANA statement timezone/);
+ });
+
+ it("leaves other XML to the column mapper", async () => {
+ const result = await preview(`\n`);
+ expect(result).toMatchObject({ detected: null, needsMapping: true });
+ });
+});
diff --git a/docs/importers.md b/docs/importers.md
index 232aba09..67bc1f45 100644
--- a/docs/importers.md
+++ b/docs/importers.md
@@ -29,6 +29,7 @@ Two validation tiers:
| MetaTrader 4 (HTML statement) | trades → reconstructed fills | HTML + MetaTrader markers | ☐ | ☐ |
| Interactive Brokers (activity CSV) | fills | `Trades,Header` section rows | ☐ | ☐ |
| Interactive Brokers (Flex Query) | fills | `ClientAccountID`/`Date/Time` headers | ✅¹ | ☐ |
+| Interactive Brokers (Flex XML) | fills | `FlexQueryResponse` root element | ☐ (fixtures) | ☐ |
| ThinkorSwim / Schwab (statement) | fills | `Account Trade History` section | ✅¹ | ☐ |
| NinjaTrader | fills | `Instrument`/`Action` headers | ✅¹ | ✅ (#10) |
| Tradovate | fills (Filled only) | `Contract`/`B/S`/`Fill Time` headers | ✅¹ | ☐ |
@@ -200,11 +201,31 @@ timezone of your Flex statement with IBKR. The instrument's exchange does not
determine this setting. An explicit `Z` or numeric offset in a timestamp takes
precedence. Display timezone still controls rendering and analytics only.
-This applies to broker sync. Direct Flex XML file upload is not supported; the
-IBKR file-upload formats are CSV. Date-only records retain the midnight fallback.
-Invalid timestamps, unsupported suffixes and ambiguous or nonexistent local times
-at daylight-saving transitions are skipped and counted in the sync warning.
-Check the source report for those records before relying on the resulting totals.
+Date-only records retain the midnight fallback. Invalid timestamps, unsupported
+suffixes and ambiguous or nonexistent local times at daylight-saving transitions
+are skipped and counted in the sync warning. Check the source report for those
+records before relying on the resulting totals.
+
+### IBKR Flex XML file upload
+
+**Import → File upload** also accepts a Flex Query XML statement (`.xml`). It is
+read by the same Broker SDK parser as broker sync, and the **Statement timezone**
+on the upload form applies to `dateTime` values without an explicit offset. The
+default Flex date and time formats (`yyyyMMdd`, `HHmmss`, `;` separator) are
+required; rows with other formats are skipped and counted in the preview warning.
+
+- Only execution rows are imported. Order, closed-lot and other summary rows
+ (`levelOfDetail` other than `EXECUTION`) are skipped so fills are not counted
+ twice.
+- Rows with a zero price, such as option expiries and assignments, are skipped
+ and counted, as in broker sync.
+- A file that contains more than one IBKR account is refused. Export one
+ account per Flex Query, or import each statement into its own journal account.
+- Uploading into an IBKR broker-sync account requires the statement timezone
+ that account syncs with: the recorded sync timezone, or the **Default import
+ timezone** if nothing has synced yet. Uploaded and synced copies of the same
+ fill then deduplicate. An upload in another timezone is refused before any
+ writes, because its fills would otherwise be stored twice.
The first sync that stores executions records its statement timezone internally.
Further syncs use the same timezone and existing deduplication. Accounts containing