From 5f270f75bb73092d89fd2d797173febf8c6ed08b Mon Sep 17 00:00:00 2001
From: Tyler Hoang <tyler@tylerhoang.xyz>
Date: Sun, 17 May 2026 14:27:18 -0700
Subject: feat: add FinancialRow/Statement/Response schemas

---
 backend/app/schemas.py    | 21 +++++++++++++++++++++
 backend/tests/test_api.py | 19 +++++++++++++++++++
 2 files changed, 40 insertions(+)

(limited to 'backend')

diff --git a/backend/app/schemas.py b/backend/app/schemas.py
index 2ee6dac..86f586c 100644
--- a/backend/app/schemas.py
+++ b/backend/app/schemas.py
@@ -107,6 +107,27 @@ class HistoryPoint(BaseModel):
     volume: float | None = None
 
 
+class FinancialRow(BaseModel):
+    label: str
+    indent: int = 0
+    is_total: bool = False
+    is_section: bool = False
+    is_margin: bool = False
+    values: list[float | None] = Field(default_factory=list)
+
+
+class FinancialStatement(BaseModel):
+    columns: list[str] = Field(default_factory=list)
+    rows: list[FinancialRow] = Field(default_factory=list)
+
+
+class FinancialsResponse(BaseModel):
+    period: Literal["annual", "quarterly"]
+    income: FinancialStatement
+    balance: FinancialStatement
+    cash_flow: FinancialStatement
+
+
 class WatchlistItem(BaseModel):
     symbol: str
     created_at: str
diff --git a/backend/tests/test_api.py b/backend/tests/test_api.py
index 1c99cf9..5d76dfd 100644
--- a/backend/tests/test_api.py
+++ b/backend/tests/test_api.py
@@ -334,6 +334,25 @@ def test_compute_ttm_ratios_guardrails_suppress_outliers(monkeypatch) -> None:
     assert "ev_to_ebitda" not in ratios
 
 
+def test_financials_schema_structure() -> None:
+    from app.schemas import FinancialRow, FinancialStatement, FinancialsResponse
+    row = FinancialRow(label="Revenue", indent=0, is_total=True, values=[1.0, 2.0, None])
+    assert row.label == "Revenue"
+    assert row.is_total is True
+    assert row.values[2] is None
+
+    stmt = FinancialStatement(columns=["FY 2024", "TTM"], rows=[row])
+    assert len(stmt.columns) == 2
+
+    resp = FinancialsResponse(
+        period="annual",
+        income=stmt,
+        balance=FinancialStatement(columns=[], rows=[]),
+        cash_flow=FinancialStatement(columns=[], rows=[]),
+    )
+    assert resp.period == "annual"
+
+
 def test_overview_uses_computed_sources_and_ratios(monkeypatch) -> None:
     clear_service_caches()
     monkeypatch.setattr(
-- 
cgit v1.3-2-g0d8e