"""Domain Port for General Department of Taxation (GDT) E-Invoice Portal Gateway.

Compliant with Hexagonal Architecture / Clean Architecture (Rule 6).
The Application layer only depends on this Protocol contract; all network
operations (HTTP, TLS, Playwright) are implemented in Secondary Infrastructure Adapters.
"""
from __future__ import annotations

from typing import Any, Protocol, runtime_checkable
from uuid import UUID


@runtime_checkable
class GdtGatewayPort(Protocol):
    """Port interface for GDT portal authentication, captcha solving, and invoice scraping."""

    def authenticate_portal(
        self,
        tax_code: str,
        username: str,
        password: str,
        extra_config: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Authenticate with GDT portal, solving captcha automatically."""
        ...

    def solve_captcha(self) -> tuple[str, str]:
        """Fetch and solve GDT captcha returning (captcha_key, captcha_value)."""
        ...

    def fetch_invoices(
        self,
        token: str,
        from_date: str,
        to_date: str,
        sync_type: str = "all",
        tax_code: str | None = None,
        cookie_header: str = "",
    ) -> tuple[int, int, list[dict[str, Any]]]:
        """Fetch invoice batch from GDT portal."""
        ...

    def enrich_invoice_detail(
        self,
        invoice_id: str,
        inv_data: dict[str, Any],
    ) -> dict[str, Any] | None:
        """Fetch and persist line items from GDT portal on-demand."""
        ...

    def sync_invoice_detail(
        self,
        invoice_id: str,
    ) -> dict[str, Any]:
        """Direct single invoice detail sync from GDT portal."""
        ...