"""
Exception hierarchy for Mail Intake.

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.

    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.

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


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

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


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

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