# 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 BinanceFundingClient(Protocol):
    def scan(self, prev: set[str]) -> tuple[dict[str, float], dict[str, float], dict[str, float]]:
        """(liq, tf30, last24) for the union of the hedgeable liquid universe and prev positions.
        liq: {symbol: 24h_quote_volume_usd} for crypto-native, spot-hedgeable USDT perps with vol>LIQ_USD.
        tf30: {symbol: 30d-mean funding × INTERVALS_PER_DAY} (daily rate; only symbols with >=30 history).
        last24: {symbol: sum of the most recent INTERVALS_PER_DAY funding intervals} (today's booking rate)."""
        ...


class CrossVenueFundingClient(Protocol):
    def snapshot(self) -> tuple[dict[str, dict[str, float]], dict[str, dict[str, float]]]:
        """One fetch per run → (funding_by_venue, volume_by_venue), both from the same snapshot.
        funding_by_venue: { coin: { venue: daily_funding_rate } } across the supported venues.
        volume_by_venue:  { coin: { venue: 24h_quote_volume_usd } }."""
        ...


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 VolIndexClient(Protocol):
    def dvol(self, currency: str) -> dict[int, float]:
        """{ epoch_day: implied-vol-index } for BTC/ETH (Deribit DVOL)."""
        ...


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)."""
        ...
