"""The provider-agnostic ``ManagerApi`` interface.

Every Manager-API adapter (the real Infomaniak client, the in-memory fake)
implements this Protocol. It speaks only in :mod:`mgf.cloud.manager.models`
types — no wire JSON leaks across it — so the CLI and any caller program against
one surface. Operations are synchronous, read-only in this slice, and return
immutable model snapshots; a missing resource raises
:class:`mgf.common.exceptions.ResourceNotFoundError`.

This is the hosting-and-DNS **read** surface. Mutations (create a DNS record,
upgrade a hosting) are deliberately out of this slice — an upgrade spends money
and is a founder-gated act — and would extend this Protocol when added.
"""

from __future__ import annotations

from typing import TYPE_CHECKING, Protocol, runtime_checkable

if TYPE_CHECKING:
    from mgf.cloud.manager.models import DnsRecord, HostingSite, Product, WebHosting

__all__ = ["ManagerApi"]


@runtime_checkable
class ManagerApi(Protocol):
    """The read operations every Manager-API adapter supports."""

    name: str

    # --- account / products --------------------------------------------------
    def list_products(self) -> tuple[Product, ...]:
        """List every product (hosting, domain, mailbox, cloud, …) on the account."""
        ...

    # --- web hosting ---------------------------------------------------------
    def list_web_hostings(self) -> tuple[WebHosting, ...]:
        """List the web-hosting products on the account."""
        ...

    def get_web_hosting(self, hosting_id: int) -> WebHosting:
        """Return one web hosting by id (raises if absent)."""
        ...

    def find_web_hosting(self, fqdn: str) -> WebHosting:
        """Return the web hosting whose ``customer_name`` matches ``fqdn`` (raises if absent)."""
        ...

    def list_sites(self, hosting_id: int) -> tuple[HostingSite, ...]:
        """List the sites served by a web hosting."""
        ...

    def get_site(self, hosting_id: int, site_id: int) -> HostingSite:
        """Return one site of a web hosting by id (raises if absent)."""
        ...

    # --- dns -----------------------------------------------------------------
    def list_dns_records(self, fqdn: str) -> tuple[DnsRecord, ...]:
        """List the DNS records of a domain's zone."""
        ...
