# src/fxhnt/ports/market_data.py
"""Market-data client ports for the paper-forward strategies. Each has a urllib live adapter
(adapters/data/*) and a deterministic fake in tests. No network in the domain or in tests."""
from __future__ import annotations

from typing import Protocol


class DailyBarClient(Protocol):
    def adj_closes(self, symbol: str) -> dict[str, float]:
        """{ 'YYYY-MM-DD': adjusted_close } for a daily-bar history window."""
        ...


class CryptoPerpBarClient(Protocol):
    def panel(self) -> tuple[list[str], list[int], list[list[float]], list[list[float]], list[float]]:
        """(symbols, epoch_days, close[d][s], open[d][s], funding_now[s]) for the top-liquid perps."""
        ...


class FundamentalsClient(Protocol):
    def metrics(self, symbol: str) -> dict[str, float]:
        """Latest daily valuation metrics: {'peRatio','pbRatio','marketCap', ...} (most recent available)."""
        ...
    def statement_metrics(self, symbol: str) -> dict[str, float]:
        """Latest reported statement metrics: {'piotroskiFScore','roe','debtEquity','grossMargin', ...}."""
        ...


class UniverseSource(Protocol):
    def top_n(self, n: int) -> list[str]:
        """The n most-liquid US common-stock tickers by trailing dollar-volume (descending)."""
        ...


class HistoricalBarClient(Protocol):
    def bars(self, symbol: str, start_date: str | None = None) -> list[dict[str, float | str]]:
        """Full-history daily EOD bars: per-date {'date','adjClose','close','volume'} ascending."""
        ...


class SurvivorshipFreeUniverseSource(Protocol):
    def survivorship_free(self) -> list[tuple[str, str, str, str]]:
        """The FULL US common-stock candidate set WITH dates: (ticker, exchange, startDate, endDate),
        INCLUDING delisted names — the point-in-time-universe backbone for a walk-forward backtest."""
        ...
