add earnings-date guard — warn when a report falls in the target horizon

Finnhub's earnings calendar now supplies next_earnings_date through the
fundamentals chain; persisted on fundamental_data (migration 006) and exposed in
the fundamentals API. The recommendation panel warns when earnings fall within
the ~30-day target horizon (a report can gap price through stop/target) and
otherwise shows the next date. Informational only.

Deploy: run alembic upgrade (new fundamental_data.next_earnings_date column).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

app/providers/fundamentals_chain.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 import logging
 import os
-from datetime import datetime, timezone
+from datetime import date, datetime, timedelta, timezone
 from pathlib import Path
 
 import httpx
@@ -59,6 +59,7 @@ class FinnhubFundamentalProvider:
         unavailable: dict[str, str] = {}
         api_symbol = _to_api_symbol(ticker)
 
+        today = date.today()
         async with httpx.AsyncClient(timeout=30.0, verify=_CA_BUNDLE_PATH) as client:
             profile_resp = await client.get(
                 f"{self._base_url}/stock/profile2",
@@ -72,11 +73,21 @@ class FinnhubFundamentalProvider:
                 f"{self._base_url}/stock/earnings",
                 params={"symbol": api_symbol, "limit": 1, "token": self._api_key},
             )
+            calendar_resp = await client.get(
+                f"{self._base_url}/calendar/earnings",
+                params={
+                    "symbol": api_symbol,
+                    "from": today.isoformat(),
+                    "to": (today + timedelta(days=120)).isoformat(),
+                    "token": self._api_key,
+                },
+            )
 
         for resp, endpoint in (
             (profile_resp, "profile2"),
             (metric_resp, "stock/metric"),
             (earnings_resp, "stock/earnings"),
+            (calendar_resp, "calendar/earnings"),
         ):
             if resp.status_code == 429:
                 raise RateLimitError(f"Finnhub rate limit hit for {ticker} ({endpoint})")
@@ -99,6 +110,8 @@ class FinnhubFundamentalProvider:
             first = earnings_payload[0] if isinstance(earnings_payload[0], dict) else {}
             earnings_surprise = _safe_float(first.get("surprisePercent"))
 
+        next_earnings_date = self._next_earnings(calendar_resp)
+
         if pe_ratio is None:
             unavailable["pe_ratio"] = "not available from provider payload"
         if revenue_growth is None:
@@ -115,9 +128,32 @@ class FinnhubFundamentalProvider:
             earnings_surprise=earnings_surprise,
             market_cap=market_cap,
             fetched_at=datetime.now(timezone.utc),
+            next_earnings_date=next_earnings_date,
             unavailable_fields=unavailable,
         )
 
+    @staticmethod
+    def _next_earnings(resp: httpx.Response) -> date | None:
+        """Earliest upcoming earnings date from Finnhub's calendar payload."""
+        try:
+            payload = resp.json() if resp.text else {}
+        except ValueError:
+            return None
+        entries = payload.get("earningsCalendar", []) if isinstance(payload, dict) else []
+        dates: list[date] = []
+        today = date.today()
+        for entry in entries if isinstance(entries, list) else []:
+            raw = entry.get("date") if isinstance(entry, dict) else None
+            if not raw:
+                continue
+            try:
+                parsed = date.fromisoformat(raw)
+            except ValueError:
+                continue
+            if parsed >= today:
+                dates.append(parsed)
+        return min(dates) if dates else None
+
 
 class AlphaVantageFundamentalProvider:
     """Fundamentals provider backed by Alpha Vantage free endpoints."""
@@ -235,9 +271,10 @@ class ChainedFundamentalProvider:
         field_source: dict[str, str] = {}
         errors: list[str] = []
         rate_limited = False
+        next_earnings_date = None
 
         for provider_name, provider in self._providers:
-            if all(merged[f] is not None for f in _FUNDAMENTAL_FIELDS):
+            if all(merged[f] is not None for f in _FUNDAMENTAL_FIELDS) and next_earnings_date:
                 break
             try:
                 data = await provider.fetch_fundamentals(ticker)
@@ -249,6 +286,9 @@ class ChainedFundamentalProvider:
                 errors.append(f"{provider_name}: {type(exc).__name__}: {exc}")
                 continue
 
+            if next_earnings_date is None and data.next_earnings_date is not None:
+                next_earnings_date = data.next_earnings_date
+
             for field in _FUNDAMENTAL_FIELDS:
                 if merged[field] is None:
                     value = getattr(data, field)
@@ -287,6 +327,7 @@ class ChainedFundamentalProvider:
             earnings_surprise=merged["earnings_surprise"],
             market_cap=merged["market_cap"],
             fetched_at=datetime.now(timezone.utc),
+            next_earnings_date=next_earnings_date,
             unavailable_fields=unavailable,
         )
 

app/providers/protocol.py

@@ -53,6 +53,7 @@ class FundamentalData:
     earnings_surprise: float | None
     market_cap: float | None
     fetched_at: datetime
+    next_earnings_date: date | None = None
     unavailable_fields: dict[str, str] = field(default_factory=dict)