"""Base contracts for Deal Desk quote adapters."""

from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Any, Literal


QuoteAdapterSupportStatus = Literal["supported", "partial", "unsupported", "ambiguous"]


@dataclass(frozen=True)
class QuoteAdapterSupportResult:
    status: QuoteAdapterSupportStatus
    reason: str = ""
    capability_gaps: list[str] = field(default_factory=list)


class QuoteAdapter(ABC):
    adapter_key: str
    detected_engine: str

    def allow_header_apply_without_capability_profile(self) -> bool:
        """Override only for already-shipped deterministic header write paths."""

        return False

    @abstractmethod
    def seller_quote_support(self, *, environment_profile: Any) -> QuoteAdapterSupportResult:
        """Return seller-facing status support for the detected quote stack."""

    @abstractmethod
    def live_approval_supported(self, *, environment_profile: Any) -> bool:
        """Return whether live approval visibility is available for this stack."""

    @abstractmethod
    def load_quote_records(
        self,
        *,
        opportunity_id: str,
        org_alias: str | None,
    ) -> list[Any]:
        """Load candidate quote headers for an opportunity."""

    @abstractmethod
    def load_quote_line_items(
        self,
        *,
        quote_id: str,
        org_alias: str | None,
        reference_type: str,
    ) -> list[Any]:
        """Load quote lines for preview on the detected quote stack."""

    @abstractmethod
    def quote_line_item_object_name(self) -> str:
        """Return the line-item object name for this adapter family."""

    @abstractmethod
    def preview_apply_support(self, *, preview: Any) -> tuple[bool, str]:
        """Return whether a previewed quote revision can proceed to apply."""

    @abstractmethod
    def build_quote_revision_plan(
        self,
        *,
        preview: Any,
        org_alias: str | None,
    ) -> Any:
        """Build the deterministic apply plan for a supported quote revision."""


__all__ = [
    "QuoteAdapter",
    "QuoteAdapterSupportResult",
    "QuoteAdapterSupportStatus",
]
