from abc import ABC, abstractmethod
from collections.abc import Iterable
from dataclasses import dataclass
from datetime import datetime
from typing import Any


@dataclass(frozen=True)
class ExternalRecord:
    entity_type: str
    external_id: str
    payload: dict[str, Any]
    source_updated_at: datetime | None = None


class SourceAdapter(ABC):
    """Minimal contract implemented by each API or file-import adapter."""

    source_code: str
    source_name: str

    @abstractmethod
    def iter_records(self, *, entity_type: str) -> Iterable[ExternalRecord]:
        """Yield source records, handling pagination inside the adapter."""

    def supported_entity_types(self) -> set[str]:
        return {"product", "sale", "stock", "cost"}