"""
Exception hierarchy for Mail Intake.

---

## Summary

This module defines the **canonical exception types** used throughout the
Mail Intake library.

All library-raised errors derive from `MailIntakeError`. Consumers are
encouraged to catch this base type (or specific subclasses) rather than
provider-specific or third-party exceptions.
"""


class MailIntakeError(Exception):
    """
    Base exception for all Mail Intake errors.

    Notes:
        **Guarantees:**

            - This is the root of the Mail Intake exception hierarchy
            - All errors raised by the library must derive from this class
            - Consumers should generally catch this type when handling library-level failures
    """


class MailIntakeAuthError(MailIntakeError):
    """
    Authentication and credential-related failures.

    Notes:
        **Lifecycle:**

            - Raised when authentication providers are unable to acquire,
              refresh, or persist valid credentials.
    """


class MailIntakeAdapterError(MailIntakeError):
    """
    Errors raised by mail provider adapters.

    Notes:
        **Lifecycle:**

            - Raised when a provider adapter encounters API errors, transport
              failures, or invalid provider responses.
    """


class MailIntakeParsingError(MailIntakeError):
    """
    Errors encountered while parsing message content.

    Notes:
        **Lifecycle:**

            - Raised when raw provider payloads cannot be interpreted or
              normalized into internal domain models.
    """