"""
# Summary

Authentication provider contracts for Mail Intake.

This module defines the **authentication abstraction layer** used by mail
adapters to obtain provider-specific credentials.

Authentication concerns are intentionally decoupled from adapter logic.
Adapters depend only on this interface and must not be aware of how
credentials are acquired, refreshed, or persisted.
"""

from abc import ABC, abstractmethod
from typing import Generic, TypeVar

T = TypeVar("T")


class MailIntakeAuthProvider(ABC, Generic[T]):
    """
    Abstract base class for authentication providers.

    This interface enforces a strict contract between authentication
    providers and mail adapters by requiring providers to explicitly
    declare the type of credentials they return.

    Notes:
        **Responsibilities:**

            - Acquire credentials from an external provider.
            - Refresh or revalidate credentials as needed.
            - Handle authentication-specific failure modes.
            - Coordinate with credential persistence layers where applicable.

        **Constraints:**

            - Mail adapters must treat returned credentials as opaque and
              provider-specific.
            - Mail adapters rely only on the declared credential type expected
              by the adapter.
    """

    @abstractmethod
    def get_credentials(self) -> T:
        """
        Retrieve valid, provider-specific credentials.

        Returns:
            T:
                Credentials of type `T` suitable for immediate use by the
                corresponding mail adapter.

        Raises:
            Exception:
                An authentication-specific exception indicating that
                credentials could not be obtained or validated.

        Notes:
            **Guarantees:**

                - This method is synchronous by design.
                - Represents the sole entry point through which adapters obtain
                  authentication material.
                - Implementations must either return credentials of the declared
                  type `T` that are valid at the time of return or raise an exception.
        """
        raise NotImplementedError