gloomberb 0.9.3 → 0.9.5

package/src/sources/provider-router/financials.ts

@@ -1,6 +1,7 @@
 import type { CachedResourceRecord } from "../../data/resource-store";
 import type { AnalystResearchData, CorporateActionsData, FinancialStatement, Quote, TickerFinancials } from "../../types/financials";
 import { hasLikelyQuoteUnitMismatch } from "../../utils/currency-units";
+import { mergeFinancialStatementRows } from "../../utils/financial-statements";
 import { normalizePriceHistory, normalizeTickerFinancialsPriceHistory } from "../../utils/price-history";
 import { isQuoteStaleForCurrentSession } from "../../market-data/quotes/freshness";
 import {
@@ -122,33 +123,20 @@ export function hasDetailedStatementRows(data: TickerFinancials | null | undefin
   return rows.some((row) => DETAILED_STATEMENT_KEYS.some((key) => typeof row[key] === "number"));
 }
 
-function mergeStatementRows(
-  primaryRows: FinancialStatement[],
-  fallbackRows: FinancialStatement[],
-): FinancialStatement[] {
-  if (primaryRows.length === 0) return fallbackRows;
-  if (fallbackRows.length === 0) return primaryRows;
-
-  const fallbackByDate = new Map(fallbackRows.map((row) => [row.date, row]));
-  const primaryDates = new Set(primaryRows.map((row) => row.date));
-  const mergedRows = primaryRows.map((row) => ({
-    ...fallbackByDate.get(row.date),
-    ...row,
-    date: row.date,
-  }));
-
-  for (const row of fallbackRows) {
-    if (!primaryDates.has(row.date)) mergedRows.push(row);
-  }
+export function hasDeepStatementHistory(data: TickerFinancials | null | undefined): boolean {
+  if (!data) return false;
+  return data.annualStatements.length >= 5 || data.quarterlyStatements.length >= 8;
+}
 
-  return mergedRows.sort((left, right) => left.date.localeCompare(right.date));
+export function hasShallowStatementHistory(data: TickerFinancials | null | undefined): boolean {
+  return hasStatementRows(data) && !hasDeepStatementHistory(data);
 }
 
 export function mergeMissingStatementArrays(primary: TickerFinancials, fallback: TickerFinancials): TickerFinancials {
   return {
     ...primary,
-    annualStatements: mergeStatementRows(primary.annualStatements, fallback.annualStatements),
-    quarterlyStatements: mergeStatementRows(primary.quarterlyStatements, fallback.quarterlyStatements),
+    annualStatements: mergeFinancialStatementRows(primary.annualStatements, fallback.annualStatements),
+    quarterlyStatements: mergeFinancialStatementRows(primary.quarterlyStatements, fallback.quarterlyStatements),
   };
 }
 
@@ -216,8 +204,8 @@ export function mergeFinancials(primary: TickerFinancials | null, fallback: Tick
     profile: mergeDefinedObject(primary.profile, fallback.profile),
     fundamentals: mergeDefinedObject(primary.fundamentals, fallback.fundamentals),
     priceHistory: normalizePriceHistory(dominant.priceHistory.length > 0 ? dominant.priceHistory : secondary.priceHistory),
-    annualStatements: mergeStatementRows(primary.annualStatements, fallback.annualStatements),
-    quarterlyStatements: mergeStatementRows(primary.quarterlyStatements, fallback.quarterlyStatements),
+    annualStatements: mergeFinancialStatementRows(primary.annualStatements, fallback.annualStatements),
+    quarterlyStatements: mergeFinancialStatementRows(primary.quarterlyStatements, fallback.quarterlyStatements),
   });
 }
 

package/src/sources/provider-router/index.test.ts

@@ -1069,6 +1069,195 @@ describe("AssetDataRouter", () => {
     expect(yahooCalls).toBe(1);
   });
 
+  test("supplements shallow preferred provider statement history", async () => {
+    const cloudProvider: DataProvider = {
+      ...fallbackProvider,
+      id: "cloud",
+      name: "Cloud",
+      priority: 100,
+      async getTickerFinancials() {
+        return makeFinancials({
+          profile: { sector: "Technology" },
+          quote: makeQuote({ symbol: "LINK", price: 25 }),
+          quarterlyStatements: [
+            { date: "2025-03-31", operatingCashFlow: -271_000 },
+            { date: "2025-06-30", operatingCashFlow: -138_000 },
+            { date: "2025-09-30", operatingCashFlow: 653_000 },
+            { date: "2025-12-31", operatingCashFlow: -356_000 },
+            { date: "2026-03-31", operatingCashFlow: -543_000 },
+          ],
+        });
+      },
+    };
+    let yahooCalls = 0;
+    const yahooProvider: DataProvider = {
+      ...fallbackProvider,
+      id: "yahoo",
+      name: "Yahoo",
+      priority: 1000,
+      async getTickerFinancials() {
+        yahooCalls += 1;
+        return makeFinancials({
+          quarterlyStatements: [
+            { date: "2024-03-31", operatingCashFlow: -601_000 },
+            { date: "2024-06-30", operatingCashFlow: -488_000 },
+            { date: "2024-09-30", operatingCashFlow: -204_000 },
+            { date: "2024-12-31", operatingCashFlow: 122_000 },
+          ],
+        });
+      },
+    };
+
+    const router = new AssetDataRouter(yahooProvider, [cloudProvider]);
+    const merged = await router.getTickerFinancials("LINK", "NASDAQ");
+
+    expect(yahooCalls).toBe(1);
+    expect(merged.profile?.sector).toBe("Technology");
+    expect(merged.quote?.price).toBe(25);
+    expect(merged.quarterlyStatements.map((row) => row.date)).toEqual([
+      "2024-03-31",
+      "2024-06-30",
+      "2024-09-30",
+      "2024-12-31",
+      "2025-03-31",
+      "2025-06-30",
+      "2025-09-30",
+      "2025-12-31",
+      "2026-03-31",
+    ]);
+  });
+
+  test("enriches shallow batch provider statement history through the single financial route", async () => {
+    const shallowCloudRows = [
+      { date: "2025-03-31", eps: 0.44 },
+      { date: "2025-06-30", eps: 0.54 },
+      { date: "2025-09-30", eps: 0.75 },
+      { date: "2025-12-31", eps: 0.92 },
+      { date: "2026-03-31", eps: 0.84 },
+    ];
+    let cloudBatchCalls = 0;
+    let cloudSingleCalls = 0;
+    const cloudProvider: DataProvider = {
+      ...fallbackProvider,
+      id: "cloud",
+      name: "Cloud",
+      priority: 100,
+      async getTickerFinancials() {
+        cloudSingleCalls += 1;
+        return makeFinancials({
+          profile: { sector: "Technology" },
+          quote: makeQuote({ symbol: "AMD", price: 125 }),
+          quarterlyStatements: shallowCloudRows,
+        });
+      },
+      async getTickerFinancialsBatch(targets) {
+        cloudBatchCalls += 1;
+        return targets.map((target) => ({
+          target,
+          financials: makeFinancials({
+            profile: { sector: "Technology" },
+            quote: makeQuote({ symbol: target.symbol, price: 125 }),
+            quarterlyStatements: shallowCloudRows,
+          }),
+        }));
+      },
+    };
+    let yahooCalls = 0;
+    const yahooProvider: DataProvider = {
+      ...fallbackProvider,
+      id: "yahoo",
+      name: "Yahoo",
+      priority: 1000,
+      async getTickerFinancials() {
+        yahooCalls += 1;
+        return makeFinancials({
+          quarterlyStatements: [
+            { date: "2024-03-31", eps: 0.07 },
+            { date: "2024-06-30", eps: 0.16 },
+            { date: "2024-09-30", eps: 0.47 },
+            { date: "2024-12-31", eps: 0.29 },
+          ],
+        });
+      },
+    };
+
+    const router = new AssetDataRouter(yahooProvider, [cloudProvider]);
+    const results = await router.getTickerFinancialsBatch([{ symbol: "AMD", exchange: "NASDAQ" }], { forceRefresh: true });
+    const financials = results[0]?.financials;
+
+    expect(cloudBatchCalls).toBe(1);
+    expect(cloudSingleCalls).toBe(1);
+    expect(yahooCalls).toBe(1);
+    expect(financials?.profile?.sector).toBe("Technology");
+    expect(financials?.quote?.symbol).toBe("AMD");
+    expect(financials?.quarterlyStatements.map((row) => row.date)).toEqual([
+      "2024-03-31",
+      "2024-06-30",
+      "2024-09-30",
+      "2024-12-31",
+      "2025-03-31",
+      "2025-06-30",
+      "2025-09-30",
+      "2025-12-31",
+      "2026-03-31",
+    ]);
+  });
+
+  test("refreshes shallow cached provider statement history", async () => {
+    const dbPath = createTempDbPath("cached-shallow-statement-history");
+    const persistence = new AppPersistence(dbPath);
+    const cloudProvider: DataProvider = {
+      ...fallbackProvider,
+      id: "cloud",
+      name: "Cloud",
+      priority: 100,
+      async getTickerFinancials() {
+        return makeFinancials({
+          profile: { sector: "Technology" },
+          quote: makeQuote({ symbol: "LINK", price: 25 }),
+          quarterlyStatements: [
+            { date: "2025-03-31", operatingCashFlow: -271_000 },
+            { date: "2025-06-30", operatingCashFlow: -138_000 },
+            { date: "2025-09-30", operatingCashFlow: 653_000 },
+            { date: "2025-12-31", operatingCashFlow: -356_000 },
+            { date: "2026-03-31", operatingCashFlow: -543_000 },
+          ],
+        });
+      },
+    };
+    let yahooCalls = 0;
+    const yahooProvider: DataProvider = {
+      ...fallbackProvider,
+      id: "yahoo",
+      name: "Yahoo",
+      priority: 1000,
+      async getTickerFinancials() {
+        yahooCalls += 1;
+        return makeFinancials({
+          quarterlyStatements: [
+            { date: "2024-03-31", operatingCashFlow: -601_000 },
+            { date: "2024-06-30", operatingCashFlow: -488_000 },
+            { date: "2024-09-30", operatingCashFlow: -204_000 },
+            { date: "2024-12-31", operatingCashFlow: 122_000 },
+          ],
+        });
+      },
+    };
+
+    try {
+      const seedRouter = new AssetDataRouter(null, [cloudProvider], persistence.resources);
+      await seedRouter.getTickerFinancials("LINK", "NASDAQ");
+
+      const cachedRouter = new AssetDataRouter(yahooProvider, [cloudProvider], persistence.resources);
+      const merged = await cachedRouter.getTickerFinancials("LINK", "NASDAQ");
+
+      expect(yahooCalls).toBe(1);
+      expect(merged.quarterlyStatements).toHaveLength(9);
+    } finally {
+      persistence.close();
+    }
+  });
+
   test("fills missing preferred statement fields from richer fallback rows", async () => {
     const cloudProvider: DataProvider = {
       ...fallbackProvider,

package/src/sources/provider-router/primary.ts

@@ -6,6 +6,7 @@ import { resolveTickerFinancialsQuoteState } from "../../market-data/quotes/reso
 import { shouldLogProviderError } from "../provider-errors";
 import {
   hasDetailedStatementRows,
+  hasDeepStatementHistory,
   hasStatementRows,
   mergeMissingStatementArrays,
 } from "./financials";
@@ -80,7 +81,7 @@ export class ProviderRouterPrimaryRoutes {
         );
         if (!primaryResult) {
           primaryResult = { sourceKey, value };
-          if (hasDetailedStatementRows(value)) return primaryResult;
+          if (hasDetailedStatementRows(value) && hasDeepStatementHistory(value)) return primaryResult;
           continue;
         }
         if (hasStatementRows(value)) {
@@ -88,7 +89,7 @@ export class ProviderRouterPrimaryRoutes {
             sourceKey: primaryResult.sourceKey,
             value: mergeMissingStatementArrays(primaryResult.value, value),
           };
-          if (hasDetailedStatementRows(primaryResult.value)) return primaryResult;
+          if (hasDetailedStatementRows(primaryResult.value) && hasDeepStatementHistory(primaryResult.value)) return primaryResult;
         }
       } catch (error) {
         if (shouldLogProviderError(error)) {

package/src/sources/sec-edgar.test.ts

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, test } from "bun:test";
 import {
   SecEdgarClient,
   extractFilingContent,
+  parseCompanyFactsFinancialStatements,
   parseFilingDocuments,
   parseRecentFilings,
   parseTickerLookup,
@@ -119,6 +120,88 @@ describe("parseFilingDocuments", () => {
   });
 });
 
+describe("parseCompanyFactsFinancialStatements", () => {
+  test("maps SEC company facts into deeper annual and quarterly statement rows", () => {
+    const fact = (tag: string, unit: string, rows: unknown[]) => ({
+      [tag]: {
+        units: {
+          [unit]: rows,
+        },
+      },
+    });
+    const duration = (end: string, val: number, overrides: Record<string, unknown> = {}) => ({
+      start: `${end.slice(0, 4)}-01-01`,
+      end,
+      val,
+      filed: end,
+      form: "10-K",
+      fp: "FY",
+      ...overrides,
+    });
+    const instant = (end: string, val: number, overrides: Record<string, unknown> = {}) => ({
+      end,
+      val,
+      filed: end,
+      form: "10-K",
+      fp: "FY",
+      ...overrides,
+    });
+
+    const statements = parseCompanyFactsFinancialStatements({
+      facts: {
+        "us-gaap": {
+          ...fact("RevenueFromContractWithCustomerExcludingAssessedTax", "USD", [
+            duration("2020-12-31", 100),
+            duration("2021-03-31", 30, { form: "10-Q", fp: "Q1", frame: "CY2021Q1" }),
+            duration("2021-06-30", 40, { form: "10-Q", fp: "Q2", frame: "CY2021Q2" }),
+          ]),
+          ...fact("NetCashProvidedByUsedInOperatingActivities", "USD", [
+            duration("2020-12-31", 25),
+            duration("2021-03-31", 8, { form: "10-Q", fp: "Q1", frame: "CY2021Q1" }),
+          ]),
+          ...fact("PaymentsToAcquirePropertyPlantAndEquipment", "USD", [
+            duration("2020-12-31", 5),
+            duration("2021-03-31", 3, { form: "10-Q", fp: "Q1", frame: "CY2021Q1" }),
+          ]),
+          ...fact("Assets", "USD", [
+            instant("2020-12-31", 500),
+            instant("2021-03-31", 520, { form: "10-Q", fp: "Q1", frame: "CY2021Q1I" }),
+          ]),
+          ...fact("EarningsPerShareDiluted", "USD/shares", [
+            duration("2020-12-31", 1.25),
+            duration("2021-03-31", 0.35, { form: "10-Q", fp: "Q1", frame: "CY2021Q1" }),
+          ]),
+        },
+      },
+    });
+
+    expect(statements.annualStatements).toEqual([{
+      date: "2020-12-31",
+      totalRevenue: 100,
+      operatingCashFlow: 25,
+      capitalExpenditure: -5,
+      freeCashFlow: 20,
+      totalAssets: 500,
+      eps: 1.25,
+    }]);
+    expect(statements.quarterlyStatements).toEqual([
+      {
+        date: "2021-03-31",
+        totalRevenue: 30,
+        operatingCashFlow: 8,
+        capitalExpenditure: -3,
+        freeCashFlow: 5,
+        totalAssets: 520,
+        eps: 0.35,
+      },
+      {
+        date: "2021-06-30",
+        totalRevenue: 40,
+      },
+    ]);
+  });
+});
+
 describe("SecEdgarClient", () => {
   test("extracts readable text from filing html", () => {
     const content = extractFilingContent(`

package/src/sources/sec-edgar.ts

@@ -1,4 +1,5 @@
 import type { SecFilingDocument, SecFilingItem } from "../types/data-provider";
+import type { FinancialStatement } from "../types/financials";
 import { truncateWithEllipsis } from "../utils/text-wrap";
 import {
   PDF_FALLBACK_MESSAGE,
@@ -10,6 +11,7 @@ export { extractFilingContent } from "./sec-edgar/content";
 
 const LOOKUP_URL = "https://www.sec.gov/files/company_tickers_exchange.json";
 const SUBMISSIONS_URL = "https://data.sec.gov/submissions";
+const COMPANY_FACTS_URL = "https://data.sec.gov/api/xbrl/companyfacts";
 const FETCH_TIMEOUT_MS = 15_000;
 
 function sanitizeIdentityPart(value: string, fallback: string): string {
@@ -52,6 +54,69 @@ type LookupEntry = {
   name?: string;
 };
 
+type CompanyFactsEntry = {
+  start?: string;
+  end?: string;
+  val?: number;
+  fy?: number | null;
+  fp?: string | null;
+  form?: string;
+  filed?: string;
+  frame?: string;
+};
+
+type CompanyFactsStatementField = {
+  field: keyof FinancialStatement;
+  tags: string[];
+  units: string[];
+  periodType: "duration" | "instant";
+  transform?: (value: number) => number;
+};
+
+export type SecCompanyFactsStatements = {
+  annualStatements: FinancialStatement[];
+  quarterlyStatements: FinancialStatement[];
+};
+
+const COMPANY_FACTS_STATEMENT_FIELDS: CompanyFactsStatementField[] = [
+  {
+    field: "totalRevenue",
+    tags: ["RevenueFromContractWithCustomerExcludingAssessedTax", "Revenues", "SalesRevenueNet"],
+    units: ["USD"],
+    periodType: "duration",
+  },
+  { field: "grossProfit", tags: ["GrossProfit"], units: ["USD"], periodType: "duration" },
+  { field: "operatingIncome", tags: ["OperatingIncomeLoss"], units: ["USD"], periodType: "duration" },
+  { field: "netIncome", tags: ["NetIncomeLoss", "ProfitLoss"], units: ["USD"], periodType: "duration" },
+  {
+    field: "operatingCashFlow",
+    tags: [
+      "NetCashProvidedByUsedInOperatingActivities",
+      "NetCashProvidedByUsedInOperatingActivitiesContinuingOperations",
+    ],
+    units: ["USD"],
+    periodType: "duration",
+  },
+  {
+    field: "capitalExpenditure",
+    tags: ["PaymentsToAcquirePropertyPlantAndEquipment"],
+    units: ["USD"],
+    periodType: "duration",
+    transform: (value) => -Math.abs(value),
+  },
+  { field: "totalAssets", tags: ["Assets"], units: ["USD"], periodType: "instant" },
+  {
+    field: "totalEquity",
+    tags: [
+      "StockholdersEquity",
+      "StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest",
+    ],
+    units: ["USD"],
+    periodType: "instant",
+  },
+  { field: "eps", tags: ["EarningsPerShareDiluted"], units: ["USD/shares"], periodType: "duration" },
+];
+
 function normalize(value?: string): string {
   return (value ?? "").trim().toUpperCase();
 }
@@ -297,6 +362,160 @@ export function parseFilingDocuments(indexHtml: string, filing: SecFilingItem):
   return documents;
 }
 
+function companyFactsRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function companyFactsEntries(payload: unknown, tag: string, units: string[]): CompanyFactsEntry[] {
+  const facts = companyFactsRecord(companyFactsRecord(companyFactsRecord(payload)?.facts)?.["us-gaap"]);
+  const fact = companyFactsRecord(facts?.[tag]);
+  const unitRecord = companyFactsRecord(fact?.units);
+  if (!unitRecord) return [];
+
+  for (const unit of units) {
+    const entries = unitRecord[unit];
+    if (!Array.isArray(entries)) continue;
+    return entries
+      .map((entry) => companyFactsRecord(entry))
+      .filter((entry): entry is Record<string, unknown> => !!entry)
+      .map((entry) => ({
+        start: typeof entry.start === "string" ? entry.start : undefined,
+        end: typeof entry.end === "string" ? entry.end : undefined,
+        val: typeof entry.val === "number" ? entry.val : undefined,
+        fy: typeof entry.fy === "number" ? entry.fy : null,
+        fp: typeof entry.fp === "string" ? entry.fp : null,
+        form: typeof entry.form === "string" ? entry.form : undefined,
+        filed: typeof entry.filed === "string" ? entry.filed : undefined,
+        frame: typeof entry.frame === "string" ? entry.frame : undefined,
+      }))
+      .filter((entry) => (
+        typeof entry.val === "number"
+        && Number.isFinite(entry.val)
+        && typeof entry.end === "string"
+        && /^\d{4}-\d{2}-\d{2}$/.test(entry.end)
+      ));
+  }
+
+  return [];
+}
+
+function secFormRank(form: string | undefined): number {
+  const normalized = normalize(form);
+  if (normalized === "10-K/A") return 4;
+  if (normalized === "10-K") return 3;
+  if (normalized === "10-Q/A") return 2;
+  if (normalized === "10-Q") return 1;
+  return 0;
+}
+
+function companyFactsFiledRank(value: string | undefined): number {
+  if (!value || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return 0;
+  return Date.parse(`${value}T00:00:00Z`) || 0;
+}
+
+function compareCompanyFactsEntries(left: CompanyFactsEntry, right: CompanyFactsEntry | undefined): number {
+  if (!right) return 1;
+  const filedDiff = companyFactsFiledRank(left.filed) - companyFactsFiledRank(right.filed);
+  if (filedDiff !== 0) return filedDiff;
+  const formDiff = secFormRank(left.form) - secFormRank(right.form);
+  if (formDiff !== 0) return formDiff;
+  return String(left.frame ?? "").localeCompare(String(right.frame ?? ""));
+}
+
+function isAnnualCompanyFact(entry: CompanyFactsEntry): boolean {
+  const form = normalize(entry.form);
+  return (form === "10-K" || form === "10-K/A") && normalize(entry.fp ?? undefined) === "FY";
+}
+
+function isQuarterlyCompanyFact(entry: CompanyFactsEntry, periodType: "duration" | "instant"): boolean {
+  if (periodType === "instant") {
+    return /^CY\d{4}Q[1-4]I$/.test(entry.frame ?? "")
+      || (
+        (normalize(entry.form) === "10-Q" || normalize(entry.form) === "10-Q/A")
+        && /^Q[1-3]$/.test(normalize(entry.fp ?? undefined))
+      );
+  }
+  return /^CY\d{4}Q[1-4]$/.test(entry.frame ?? "");
+}
+
+function setCompanyFactValue(
+  rows: Map<string, FinancialStatement>,
+  selectedFacts: Map<string, CompanyFactsEntry>,
+  date: string,
+  field: keyof FinancialStatement,
+  value: number,
+  entry: CompanyFactsEntry,
+): void {
+  const selectionKey = `${date}:${String(field)}`;
+  if (compareCompanyFactsEntries(entry, selectedFacts.get(selectionKey)) < 0) return;
+  const row = rows.get(date) ?? { date };
+  (row as Record<string, unknown>)[field] = value;
+  rows.set(date, row);
+  selectedFacts.set(selectionKey, entry);
+}
+
+function fillCompanyFactsStatementRows(
+  rows: Map<string, FinancialStatement>,
+  selectedFacts: Map<string, CompanyFactsEntry>,
+  entries: CompanyFactsEntry[],
+  field: CompanyFactsStatementField,
+  period: "annual" | "quarterly",
+): void {
+  for (const entry of entries) {
+    if (!entry.end || typeof entry.val !== "number") continue;
+    const matchesPeriod = period === "annual"
+      ? isAnnualCompanyFact(entry)
+      : isQuarterlyCompanyFact(entry, field.periodType);
+    if (!matchesPeriod) continue;
+    setCompanyFactValue(
+      rows,
+      selectedFacts,
+      entry.end,
+      field.field,
+      field.transform ? field.transform(entry.val) : entry.val,
+      entry,
+    );
+  }
+}
+
+function finalizeCompanyFactsStatements(rows: Map<string, FinancialStatement>): FinancialStatement[] {
+  const statements = Array.from(rows.values()).sort((left, right) => left.date.localeCompare(right.date));
+  for (const statement of statements) {
+    if (
+      typeof statement.freeCashFlow !== "number"
+      && typeof statement.operatingCashFlow === "number"
+      && typeof statement.capitalExpenditure === "number"
+    ) {
+      statement.freeCashFlow = statement.operatingCashFlow + statement.capitalExpenditure;
+    }
+  }
+  return statements;
+}
+
+export function parseCompanyFactsFinancialStatements(payload: unknown): SecCompanyFactsStatements {
+  const annualRows = new Map<string, FinancialStatement>();
+  const quarterlyRows = new Map<string, FinancialStatement>();
+  const annualSelectedFacts = new Map<string, CompanyFactsEntry>();
+  const quarterlySelectedFacts = new Map<string, CompanyFactsEntry>();
+
+  for (const field of COMPANY_FACTS_STATEMENT_FIELDS) {
+    for (const tag of field.tags) {
+      const entries = companyFactsEntries(payload, tag, field.units);
+      if (entries.length === 0) continue;
+      fillCompanyFactsStatementRows(annualRows, annualSelectedFacts, entries, field, "annual");
+      fillCompanyFactsStatementRows(quarterlyRows, quarterlySelectedFacts, entries, field, "quarterly");
+      break;
+    }
+  }
+
+  return {
+    annualStatements: finalizeCompanyFactsStatements(annualRows),
+    quarterlyStatements: finalizeCompanyFactsStatements(quarterlyRows),
+  };
+}
+
 export class SecEdgarClient {
   private lookupPromise: Promise<Map<string, LookupEntry>> | null = null;
 
@@ -407,6 +626,18 @@ export class SecEdgarClient {
     return parseRecentFilings(payload, count);
   }
 
+  async getFinancialStatements(ticker: string): Promise<SecCompanyFactsStatements | null> {
+    const normalizedTicker = normalize(ticker);
+    if (!normalizedTicker) return null;
+
+    const lookup = await this.loadLookup();
+    const entry = lookup.get(normalizedTicker);
+    if (!entry) return null;
+
+    const payload = await this.fetchJson<unknown>(`${COMPANY_FACTS_URL}/CIK${entry.cik}.json`);
+    return parseCompanyFactsFinancialStatements(payload);
+  }
+
   async getFilingDocuments(filing: SecFilingItem): Promise<SecFilingDocument[]> {
     const { body } = await this.fetchText(filing.filingUrl);
     return parseFilingDocuments(body, filing);