gloomberb 0.5.1 → 0.6.1

package/src/plugins/ibkr/account-cache.test.ts

@@ -2,15 +2,16 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { existsSync, rmSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
+import {
+  clearPersistedBrokerAccounts,
+  loadPersistedBrokerAccountMap,
+  loadPersistedBrokerAccounts,
+  persistBrokerAccounts,
+} from "../../brokers/account-cache";
 import { AppPersistence } from "../../data/app-persistence";
 import type { BrokerInstanceConfig } from "../../types/config";
 import type { BrokerAccount } from "../../types/trading";
-import {
-  clearPersistedIbkrAccounts,
-  loadPersistedIbkrAccountMap,
-  loadPersistedIbkrAccounts,
-  persistIbkrAccounts,
-} from "./account-cache";
+import { ibkrBroker } from "./broker-adapter";
 
 const tempPaths: string[] = [];
 
@@ -55,10 +56,10 @@ describe("IBKR account cache", () => {
     const persistence = new AppPersistence(createTempDbPath("ibkr-account-cache"));
     const instance = createIbkrInstance("flex", { id: "ibkr-personal" });
 
-    persistIbkrAccounts(persistence.resources, instance, TEST_ACCOUNTS);
+    persistBrokerAccounts(persistence.resources, instance, ibkrBroker, TEST_ACCOUNTS);
 
-    expect(loadPersistedIbkrAccounts(persistence.resources, instance)).toEqual(TEST_ACCOUNTS);
-    expect(loadPersistedIbkrAccountMap(persistence.resources, [instance])).toEqual({
+    expect(loadPersistedBrokerAccounts(persistence.resources, instance, ibkrBroker)).toEqual(TEST_ACCOUNTS);
+    expect(loadPersistedBrokerAccountMap(persistence.resources, [instance], new Map([["ibkr", ibkrBroker]]))).toEqual({
       "ibkr-personal": TEST_ACCOUNTS,
     });
 
@@ -73,9 +74,9 @@ describe("IBKR account cache", () => {
       config: { connectionMode: "gateway", gateway: { host: "127.0.0.1", port: 4003, clientId: 1 } },
     });
 
-    persistIbkrAccounts(persistence.resources, original, TEST_ACCOUNTS);
+    persistBrokerAccounts(persistence.resources, original, ibkrBroker, TEST_ACCOUNTS);
 
-    expect(loadPersistedIbkrAccounts(persistence.resources, updated)).toBeNull();
+    expect(loadPersistedBrokerAccounts(persistence.resources, updated, ibkrBroker)).toBeNull();
     expect(persistence.resources.list({
       namespace: "plugin:ibkr",
       kind: "account-snapshot",
@@ -92,10 +93,10 @@ describe("IBKR account cache", () => {
     const persistence = new AppPersistence(createTempDbPath("ibkr-account-cache-clear"));
     const instance = createIbkrInstance("gateway", { id: "ibkr-live" });
 
-    persistIbkrAccounts(persistence.resources, instance, TEST_ACCOUNTS);
-    clearPersistedIbkrAccounts(persistence.resources, instance.id);
+    persistBrokerAccounts(persistence.resources, instance, ibkrBroker, TEST_ACCOUNTS);
+    clearPersistedBrokerAccounts(persistence.resources, instance);
 
-    expect(loadPersistedIbkrAccounts(persistence.resources, instance)).toBeNull();
+    expect(loadPersistedBrokerAccounts(persistence.resources, instance, ibkrBroker)).toBeNull();
     persistence.close();
   });
 });

package/src/plugins/ibkr/account-cache.ts

@@ -1,137 +1,32 @@
-import { createHash } from "crypto";
-import type { ResourceStore } from "../../data/resource-store";
 import type { BrokerInstanceConfig } from "../../types/config";
-import type { BrokerAccount } from "../../types/trading";
-import { normalizeIbkrConfig, type IbkrConnectionMode } from "./config";
-
-const IBKR_PLUGIN_NAMESPACE = "plugin:ibkr";
-const IBKR_ACCOUNT_SNAPSHOT_KIND = "account-snapshot";
-const IBKR_ACCOUNT_SNAPSHOT_SCHEMA_VERSION = 1;
+import type { CachePolicy } from "../../types/persistence";
+import { normalizeIbkrConfig } from "./config";
 
 const FLEX_ACCOUNT_CACHE_POLICY = {
   staleMs: 6 * 60 * 60 * 1000,
   expireMs: 30 * 24 * 60 * 60 * 1000,
-} as const;
+} as const satisfies CachePolicy;
 
 const GATEWAY_ACCOUNT_CACHE_POLICY = {
   staleMs: 30 * 1000,
   expireMs: 7 * 24 * 60 * 60 * 1000,
-} as const;
+} as const satisfies CachePolicy;
 
-interface PersistedIbkrAccountSnapshot {
-  connectionMode: IbkrConnectionMode;
-  accounts: BrokerAccount[];
+function hashString(input: string): string {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return `fnv1a:${(hash >>> 0).toString(16).padStart(8, "0")}`;
 }
 
-function getIbkrAccountSnapshotSourceKey(instance: BrokerInstanceConfig): string {
-  const normalized = normalizeIbkrConfig(instance.config);
-  return createHash("sha256")
-    .update(JSON.stringify(normalized))
-    .digest("hex");
+export function getIbkrAccountCacheSourceKey(instance: BrokerInstanceConfig): string {
+  return hashString(JSON.stringify(normalizeIbkrConfig(instance.config)));
 }
 
-function getAccountCachePolicy(instance: BrokerInstanceConfig) {
-  const normalized = normalizeIbkrConfig(instance.config);
-  return normalized.connectionMode === "gateway"
+export function getIbkrAccountCachePolicy(instance: BrokerInstanceConfig): CachePolicy {
+  return normalizeIbkrConfig(instance.config).connectionMode === "gateway"
     ? GATEWAY_ACCOUNT_CACHE_POLICY
     : FLEX_ACCOUNT_CACHE_POLICY;
 }
-
-function pruneMismatchedSnapshots(resources: ResourceStore, instance: BrokerInstanceConfig, sourceKey: string): void {
-  const records = resources.list<PersistedIbkrAccountSnapshot>({
-    namespace: IBKR_PLUGIN_NAMESPACE,
-    kind: IBKR_ACCOUNT_SNAPSHOT_KIND,
-    entityKey: instance.id,
-  }, {
-    schemaVersion: IBKR_ACCOUNT_SNAPSHOT_SCHEMA_VERSION,
-    allowExpired: true,
-  });
-
-  for (const record of records) {
-    if (record.sourceKey === sourceKey) continue;
-    resources.delete({
-      namespace: IBKR_PLUGIN_NAMESPACE,
-      kind: IBKR_ACCOUNT_SNAPSHOT_KIND,
-      entityKey: instance.id,
-      sourceKey: record.sourceKey,
-    });
-  }
-}
-
-export function loadPersistedIbkrAccounts(
-  resources: ResourceStore,
-  instance: BrokerInstanceConfig,
-): BrokerAccount[] | null {
-  const sourceKey = getIbkrAccountSnapshotSourceKey(instance);
-  pruneMismatchedSnapshots(resources, instance, sourceKey);
-
-  return resources.get<PersistedIbkrAccountSnapshot>({
-    namespace: IBKR_PLUGIN_NAMESPACE,
-    kind: IBKR_ACCOUNT_SNAPSHOT_KIND,
-    entityKey: instance.id,
-    sourceKey,
-  }, {
-    schemaVersion: IBKR_ACCOUNT_SNAPSHOT_SCHEMA_VERSION,
-  })?.value.accounts ?? null;
-}
-
-export function persistIbkrAccounts(
-  resources: ResourceStore,
-  instance: BrokerInstanceConfig,
-  accounts: BrokerAccount[],
-): void {
-  const sourceKey = getIbkrAccountSnapshotSourceKey(instance);
-  pruneMismatchedSnapshots(resources, instance, sourceKey);
-
-  resources.set<PersistedIbkrAccountSnapshot>({
-    namespace: IBKR_PLUGIN_NAMESPACE,
-    kind: IBKR_ACCOUNT_SNAPSHOT_KIND,
-    entityKey: instance.id,
-    sourceKey,
-  }, {
-    connectionMode: normalizeIbkrConfig(instance.config).connectionMode,
-    accounts,
-  }, {
-    schemaVersion: IBKR_ACCOUNT_SNAPSHOT_SCHEMA_VERSION,
-    cachePolicy: getAccountCachePolicy(instance),
-  });
-}
-
-export function loadPersistedIbkrAccountMap(
-  resources: ResourceStore,
-  brokerInstances: BrokerInstanceConfig[],
-): Record<string, BrokerAccount[]> {
-  const accountMap: Record<string, BrokerAccount[]> = {};
-
-  for (const instance of brokerInstances) {
-    if (instance.brokerType !== "ibkr") continue;
-    const accounts = loadPersistedIbkrAccounts(resources, instance);
-    if (!accounts || accounts.length === 0) continue;
-    accountMap[instance.id] = accounts;
-  }
-
-  return accountMap;
-}
-
-export function clearPersistedIbkrAccounts(
-  resources: ResourceStore,
-  instanceId: string,
-): void {
-  const records = resources.list<PersistedIbkrAccountSnapshot>({
-    namespace: IBKR_PLUGIN_NAMESPACE,
-    kind: IBKR_ACCOUNT_SNAPSHOT_KIND,
-    entityKey: instanceId,
-  }, {
-    schemaVersion: IBKR_ACCOUNT_SNAPSHOT_SCHEMA_VERSION,
-    allowExpired: true,
-  });
-
-  for (const record of records) {
-    resources.delete({
-      namespace: IBKR_PLUGIN_NAMESPACE,
-      kind: IBKR_ACCOUNT_SNAPSHOT_KIND,
-      entityKey: instanceId,
-      sourceKey: record.sourceKey,
-    });
-  }
-}

package/src/plugins/ibkr/broker-adapter.ts

@@ -1,6 +1,7 @@
 import type { BrokerAdapter, BrokerPosition } from "../../types/broker";
 import type { BrokerInstanceConfig } from "../../types/config";
 import {
+  buildIbkrConfigFromValues,
   getGatewayConfig,
   IBKR_CONFIG_FIELDS,
   isFlexConfigured,
@@ -8,6 +9,7 @@ import {
   normalizeIbkrConfig,
   type FlexQueryConfig,
 } from "./config";
+import { getIbkrAccountCachePolicy, getIbkrAccountCacheSourceKey } from "./account-cache";
 import { loadFlexStatement, parseFlexAccounts, parseFlexPositions } from "./flex";
 import { ibkrGatewayManager } from "./gateway-service";
 import { refreshGatewayData } from "./gateway-helpers";
@@ -49,9 +51,74 @@ export const ibkrBroker: BrokerAdapter = {
   },
 
   getStatus(instance) {
+    const normalized = normalizeIbkrConfig(instance.config);
+    if (normalized.connectionMode !== "gateway") {
+      return {
+        state: "disconnected",
+        message: "Flex profiles sync on demand",
+        mode: "flex",
+        updatedAt: 0,
+      };
+    }
     return { ...ibkrGatewayManager.getSnapshot(instance.id).status, mode: "gateway" };
   },
 
+  subscribeStatus(instance, listener) {
+    return ibkrGatewayManager.subscribe(instance.id, listener);
+  },
+
+  getPersistedConfigUpdate(instance) {
+    const normalized = normalizeIbkrConfig(instance.config);
+    if (normalized.connectionMode !== "gateway") return null;
+    const resolved = ibkrGatewayManager.getService(instance.id).getResolvedConnection();
+    return resolved ? buildPersistedIbkrGatewayConfig(instance.config, resolved) : null;
+  },
+
+  getAccountCacheSourceKey: getIbkrAccountCacheSourceKey,
+  getAccountCachePolicy: getIbkrAccountCachePolicy,
+
+  getProfileActions(instance) {
+    const normalized = normalizeIbkrConfig(instance.config);
+    return [{
+      id: "ibkr-console",
+      label: "IBKR Console",
+      widgetId: "ibkr-trading",
+      disabled: normalized.connectionMode !== "gateway",
+      disabledReason: "IBKR Console is available for Gateway / TWS profiles.",
+    }];
+  },
+
+  toConfigValues(instance) {
+    const normalized = normalizeIbkrConfig(instance.config);
+    return {
+      connectionMode: normalized.connectionMode,
+      token: normalized.flex.token,
+      queryId: normalized.flex.queryId,
+      endpoint: normalized.flex.endpoint,
+      gatewaySetupMode: normalized.gatewaySetupMode,
+      host: normalized.gateway.host,
+      port: normalized.gateway.port,
+      clientId: normalized.gateway.clientId,
+      marketDataType: normalized.gateway.marketDataType,
+    };
+  },
+
+  fromConfigValues(values, previous) {
+    const next = buildIbkrConfigFromValues(values);
+    const previousConfig = previous ? normalizeIbkrConfig(previous.config) : null;
+    if (!previousConfig || next.connectionMode !== "gateway") return next;
+
+    return {
+      ...next,
+      gateway: {
+        ...next.gateway,
+        marketDataType: next.gateway.marketDataType ?? previousConfig.gateway.marketDataType,
+        lastSuccessfulPort: previousConfig.gateway.lastSuccessfulPort,
+        lastSuccessfulClientId: previousConfig.gateway.lastSuccessfulClientId,
+      },
+    };
+  },
+
   async listAccounts(instance) {
     const normalized = normalizeIbkrConfig(instance.config);
     if (normalized.connectionMode === "gateway") {

package/src/plugins/ibkr/config.test.ts

@@ -22,24 +22,6 @@ describe("ibkr config helpers", () => {
     });
   });
 
-  test("defaults gateway profiles to automatic connection detection", () => {
-    const config = buildIbkrConfigFromValues({
-      connectionMode: "gateway",
-      gatewaySetupMode: "auto",
-    });
-
-    expect(config.connectionMode).toBe("gateway");
-    expect(config.gatewaySetupMode).toBe("auto");
-    expect(config.gateway).toEqual({
-      host: "127.0.0.1",
-      port: undefined,
-      clientId: undefined,
-      lastSuccessfulPort: undefined,
-      lastSuccessfulClientId: undefined,
-      marketDataType: "auto",
-    });
-  });
-
   test("treats explicit port/client configs as manual at runtime", () => {
     const config = normalizeIbkrConfig({
       connectionMode: "gateway",

package/src/plugins/ibkr/dialogs.tsx

@@ -1,10 +1,14 @@
-import { TextAttributes } from "@opentui/core";
-import type { InputRenderable } from "@opentui/core";
+import { Box, Input, Text } from "../../ui";
+import { TextAttributes } from "../../ui";
+import { type InputRenderable } from "../../ui";
 import { useEffect, useRef, useState } from "react";
-import { useDialogKeyboard, type PromptContext } from "@opentui-ui/dialog/react";
+import { type PromptContext } from "../../ui/dialog";
 import type { WizardStep } from "../../types/plugin";
 import { colors } from "../../theme/colors";
 
+export { ChoiceDialog } from "../../components";
+export type { ChoiceDialogChoice, ChoiceDialogProps } from "../../components";
+
 export function InputDialog({ resolve, step }: PromptContext<string> & { step: WizardStep }) {
   const inputRef = useRef<InputRenderable>(null);
   const [value, setValue] = useState("");
@@ -14,14 +18,14 @@ export function InputDialog({ resolve, step }: PromptContext<string> & { step: W
   }, []);
 
   return (
-    <box flexDirection="column">
-      <text attributes={TextAttributes.BOLD} fg={colors.text}>{step.label}</text>
-      <box height={1} />
+    <Box flexDirection="column">
+      <Text attributes={TextAttributes.BOLD} fg={colors.text}>{step.label}</Text>
+      <Box height={1} />
       {step.body?.map((line, index) => (
-        <text key={index} fg={colors.textDim}>{line || " "}</text>
+        <Text key={index} fg={colors.textDim}>{line || " "}</Text>
       ))}
-      <box height={1} />
-      <input
+      <Box height={1} />
+      <Input
         ref={inputRef}
         focused
         placeholder={step.placeholder || ""}
@@ -32,52 +36,6 @@ export function InputDialog({ resolve, step }: PromptContext<string> & { step: W
         onChange={(nextValue) => setValue(nextValue)}
         onSubmit={() => resolve(value.trim())}
       />
-    </box>
-  );
-}
-
-export function ChoiceDialog({
-  resolve,
-  dialogId,
-  title,
-  choices,
-}: PromptContext<string> & { title: string; choices: Array<{ id: string; label: string; desc: string }> }) {
-  const [index, setIndex] = useState(0);
-
-  useDialogKeyboard((event) => {
-    event.stopPropagation();
-    if (event.name === "up" || event.name === "k") setIndex((current) => Math.max(0, current - 1));
-    else if (event.name === "down" || event.name === "j") setIndex((current) => Math.min(choices.length - 1, current + 1));
-    else if (event.name === "return") resolve(choices[index]!.id);
-    else if (event.name === "escape") resolve("");
-  }, dialogId);
-
-  return (
-    <box flexDirection="column">
-      <text attributes={TextAttributes.BOLD} fg={colors.text}>{title}</text>
-      <box height={1} />
-      {choices.map((choice, choiceIndex) => {
-        const selected = choiceIndex === index;
-        return (
-          <box
-            key={choice.id}
-            flexDirection="row"
-            height={1}
-            backgroundColor={selected ? colors.selected : colors.bg}
-            onMouseMove={() => setIndex(choiceIndex)}
-            onMouseDown={() => resolve(choice.id)}
-          >
-            <text fg={selected ? colors.selectedText : colors.textDim}>{selected ? "▸ " : "  "}</text>
-            <text fg={selected ? colors.text : colors.textDim} attributes={selected ? TextAttributes.BOLD : 0}>
-              {choice.label}
-            </text>
-          </box>
-        );
-      })}
-      <box height={1} />
-      <text fg={colors.textDim}>{choices[index]?.desc || ""}</text>
-      <box height={1} />
-      <text fg={colors.textMuted}>↑↓ choose · Enter/click select · Esc cancel</text>
-    </box>
+    </Box>
   );
 }

package/src/plugins/ibkr/flex.test.ts

@@ -1,5 +1,13 @@
-import { describe, expect, test } from "bun:test";
-import { parseFlexAccounts, parseFlexPositions } from "./flex";
+import { afterEach, describe, expect, test } from "bun:test";
+import { setHttpFetchTransport } from "../../utils/http-transport";
+import { parseFlexAccounts, parseFlexPositions, requestFlexStatement } from "./flex";
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  setHttpFetchTransport(null);
+  globalThis.fetch = originalFetch;
+});
 
 describe("parseFlexPositions", () => {
   test("parses option positions with broker contract metadata", () => {
@@ -105,3 +113,50 @@ describe("parseFlexAccounts", () => {
     ]);
   });
 });
+
+describe("requestFlexStatement", () => {
+  test("uses the configured HTTP transport for statement requests", async () => {
+    const requests: string[] = [];
+    setHttpFetchTransport(async (url) => {
+      requests.push(url);
+      return new Response(
+        "<FlexStatementResponse><ReferenceCode>987654</ReferenceCode></FlexStatementResponse>",
+        { status: 200 },
+      );
+    });
+
+    await expect(requestFlexStatement({
+      token: "secret-flex-token",
+      queryId: "12345",
+      endpoint: "https://gdcdyn.interactivebrokers.com/Universal/servlet/FlexStatementService.SendRequest",
+    })).resolves.toBe("987654");
+
+    expect(requests).toHaveLength(1);
+    expect(requests[0]).toContain("q=12345");
+  });
+
+  test("adds request context to vague IBKR Flex errors without exposing the token", async () => {
+    globalThis.fetch = (async () => new Response(
+      "<FlexStatementResponse><ErrorMessage>Load failed</ErrorMessage></FlexStatementResponse>",
+      { status: 200 },
+    )) as typeof fetch;
+
+    let message = "";
+    try {
+      await requestFlexStatement({
+        token: "secret-flex-token",
+        queryId: "12345",
+        endpoint: "https://gdcdyn.interactivebrokers.com/Universal/servlet/FlexStatementService.SendRequest",
+      });
+    } catch (error) {
+      message = error instanceof Error ? error.message : String(error);
+    }
+
+    expect(message).toContain("IBKR Flex request failed while requesting the statement: Load failed.");
+    expect(message).toContain("Endpoint FlexStatementService.SendRequest");
+    expect(message).toContain("query ID 12345");
+    expect(message).toContain("token configured");
+    expect(message).toContain("Flex Web Service is enabled");
+    expect(message).not.toContain("secret-flex-token");
+  });
+});

package/src/plugins/ibkr/flex.ts

@@ -1,6 +1,7 @@
 import type { BrokerPosition } from "../../types/broker";
 import type { BrokerContractRef } from "../../types/instrument";
 import type { BrokerAccount, BrokerCashBalance } from "../../types/trading";
+import { httpFetch } from "../../utils/http-transport";
 import type { FlexQueryConfig } from "./config";
 import { IBKR_STATEMENT_URL } from "./config";
 
@@ -8,6 +9,17 @@ const IBKR_STATEMENT_GET_URL = "https://gdcdyn.interactivebrokers.com/Universal/
 const FLEX_STATEMENT_CACHE_MS = 15_000;
 const flexStatementCache = new Map<string, { createdAt: number; promise: Promise<string> }>();
 
+type FlexRequestPhase = "request" | "download";
+
+interface FlexErrorContext {
+  phase: FlexRequestPhase;
+  endpoint?: string;
+  queryId?: string;
+  token?: string;
+  referenceCode?: string;
+  httpStatus?: number;
+}
+
 function parseAttributes(raw: string): Record<string, string> {
   const attributes: Record<string, string> = {};
   for (const [, key, value] of raw.matchAll(/([a-zA-Z0-9]+)="([^"]*)"/g)) {
@@ -46,28 +58,107 @@ function parseFlexTimestamp(raw: string | undefined, fallbackDate: string | unde
   return new Date(Number(year), Number(month) - 1, Number(day)).getTime();
 }
 
+function decodeXmlText(value: string): string {
+  return value
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, "\"")
+    .replace(/&apos;/g, "'");
+}
+
+function extractFlexErrorMessage(text: string): string | null {
+  const errorMatch = text.match(/<ErrorMessage>([^<]+)<\/ErrorMessage>/);
+  if (errorMatch?.[1]) return decodeXmlText(errorMatch[1].trim());
+  return null;
+}
+
+function endpointName(endpoint: string | undefined): string {
+  if (!endpoint) return "default";
+  try {
+    const url = new URL(endpoint);
+    return url.pathname.split("/").filter(Boolean).at(-1) || url.hostname;
+  } catch {
+    return endpoint.split("?")[0]?.split("/").filter(Boolean).at(-1) || endpoint;
+  }
+}
+
+function buildFlexErrorMessage(providerMessage: string, context: FlexErrorContext): string {
+  const phase = context.phase === "request"
+    ? "requesting the statement"
+    : "downloading the generated statement";
+  const details = [
+    `Endpoint ${endpointName(context.endpoint)}`,
+    context.queryId ? `query ID ${context.queryId}` : null,
+    context.referenceCode ? `reference code ${context.referenceCode}` : null,
+    context.token ? "token configured" : "token missing",
+    context.httpStatus && context.httpStatus >= 400 ? `HTTP ${context.httpStatus}` : null,
+  ].filter(Boolean).join(", ");
+  const advice = context.phase === "request"
+    ? "Check that Flex Web Service is enabled, the token is active, and the query ID belongs to that token."
+    : "IBKR accepted the request but did not return the statement; retry shortly or check that the Flex query can generate a statement.";
+
+  return `IBKR Flex request failed while ${phase}: ${providerMessage}. ${details}. ${advice}`;
+}
+
+function flexError(providerMessage: string, context: FlexErrorContext): Error {
+  return new Error(buildFlexErrorMessage(providerMessage, context));
+}
+
 export async function requestFlexStatement(config: FlexQueryConfig): Promise<string> {
   const endpoint = config.endpoint || IBKR_STATEMENT_URL;
   const url = `${endpoint}?t=${config.token}&q=${config.queryId}&v=3`;
-  const resp = await fetch(url, { signal: AbortSignal.timeout(30_000) });
-  const text = await resp.text();
+  let resp: Response;
+  let text: string;
+  try {
+    resp = await httpFetch(url, { signal: AbortSignal.timeout(30_000) });
+    text = await resp.text();
+  } catch (error) {
+    throw flexError(error instanceof Error ? error.message : "Network request failed", {
+      phase: "request",
+      endpoint,
+      queryId: config.queryId,
+      token: config.token,
+    });
+  }
 
   const codeMatch = text.match(/<ReferenceCode>(\d+)<\/ReferenceCode>/);
   if (!codeMatch) {
-    const errorMatch = text.match(/<ErrorMessage>([^<]+)<\/ErrorMessage>/);
-    throw new Error(errorMatch?.[1] || "Failed to request Flex statement");
+    throw flexError(extractFlexErrorMessage(text) || "No reference code returned", {
+      phase: "request",
+      endpoint,
+      queryId: config.queryId,
+      token: config.token,
+      httpStatus: resp.status,
+    });
   }
 
   return codeMatch[1]!;
 }
 
-export async function getFlexStatement(token: string, referenceCode: string): Promise<string> {
+export async function getFlexStatement(
+  token: string,
+  referenceCode: string,
+  context: Pick<FlexQueryConfig, "endpoint" | "queryId"> = {},
+): Promise<string> {
   await new Promise((resolve) => setTimeout(resolve, 3_000));
 
   const url = `${IBKR_STATEMENT_GET_URL}?t=${token}&q=${referenceCode}&v=3`;
   for (let attempt = 0; attempt < 5; attempt += 1) {
-    const resp = await fetch(url, { signal: AbortSignal.timeout(30_000) });
-    const text = await resp.text();
+    let resp: Response;
+    let text: string;
+    try {
+      resp = await httpFetch(url, { signal: AbortSignal.timeout(30_000) });
+      text = await resp.text();
+    } catch (error) {
+      throw flexError(error instanceof Error ? error.message : "Network request failed", {
+        phase: "download",
+        endpoint: context.endpoint,
+        queryId: context.queryId,
+        token,
+        referenceCode,
+      });
+    }
 
     if (text.includes("<FlexQueryResponse") || text.includes("<FlexStatements")) {
       return text;
@@ -78,13 +169,26 @@ export async function getFlexStatement(token: string, referenceCode: string): Pr
       continue;
     }
 
-    const errorMatch = text.match(/<ErrorMessage>([^<]+)<\/ErrorMessage>/);
-    if (errorMatch) {
-      throw new Error(errorMatch[1]);
+    const providerMessage = extractFlexErrorMessage(text);
+    if (providerMessage) {
+      throw flexError(providerMessage, {
+        phase: "download",
+        endpoint: context.endpoint,
+        queryId: context.queryId,
+        token,
+        referenceCode,
+        httpStatus: resp.status,
+      });
     }
   }
 
-  throw new Error("Flex statement generation timed out");
+  throw flexError("statement generation timed out", {
+    phase: "download",
+    endpoint: context.endpoint,
+    queryId: context.queryId,
+    token,
+    referenceCode,
+  });
 }
 
 export async function loadFlexStatement(config: FlexQueryConfig): Promise<string> {
@@ -96,7 +200,7 @@ export async function loadFlexStatement(config: FlexQueryConfig): Promise<string
 
   const promise = (async () => {
     const referenceCode = await requestFlexStatement(config);
-    return getFlexStatement(config.token, referenceCode);
+    return getFlexStatement(config.token, referenceCode, config);
   })();
   flexStatementCache.set(cacheKey, { createdAt: Date.now(), promise });
   setTimeout(() => {