from abc import ABC, abstractmethod

from apps.providers.contracts import (
    CompetitionPayload,
    NormalizedSyncPayload,
    PlayerCareerPayload,
    PlayerPayload,
    PlayerStatsPayload,
    SeasonPayload,
    TeamPayload,
)


class BaseProviderAdapter(ABC):
    """
    Provider contract for normalized entity payloads consumed by ingestion services.

    Adapters must return provider-agnostic entity dictionaries (see
    ``apps.providers.contracts``) and keep provider-specific response shapes
    internal to the adapter/client/mapping layer.
    """

    namespace: str

    @abstractmethod
    def search_players(self, *, query: str = "", limit: int = 50, offset: int = 0) -> list[PlayerPayload]:
        raise NotImplementedError

    @abstractmethod
    def fetch_player(self, *, external_player_id: str) -> PlayerPayload | None:
        raise NotImplementedError

    @abstractmethod
    def fetch_players(self) -> list[PlayerPayload]:
        raise NotImplementedError

    @abstractmethod
    def fetch_competitions(self) -> list[CompetitionPayload]:
        raise NotImplementedError

    @abstractmethod
    def fetch_teams(self) -> list[TeamPayload]:
        raise NotImplementedError

    @abstractmethod
    def fetch_seasons(self) -> list[SeasonPayload]:
        raise NotImplementedError

    @abstractmethod
    def fetch_player_stats(self) -> list[PlayerStatsPayload]:
        raise NotImplementedError

    @abstractmethod
    def fetch_player_careers(self) -> list[PlayerCareerPayload]:
        raise NotImplementedError

    @abstractmethod
    def sync_all(self) -> NormalizedSyncPayload:
        raise NotImplementedError

    @abstractmethod
    def sync_incremental(self, *, cursor: str | None = None) -> NormalizedSyncPayload:
        raise NotImplementedError