"""
Custom exception hierarchy for django-notify-hub.

All package exceptions inherit from NotificationError so callers
can catch the whole family with a single except clause.
"""


class NotificationError(Exception):
    """Base exception for all django-notify-hub errors."""


class BackendError(NotificationError):
    """Raised when a delivery backend fails to send a notification."""

    def __init__(self, backend_name: str, message: str, original: Exception | None = None):
        self.backend_name = backend_name
        self.original = original
        super().__init__(f"[{backend_name}] {message}")


class BackendNotConfiguredError(NotificationError):
    """Raised when a requested backend is not configured or importable."""

    def __init__(self, path: str):
        super().__init__(
            f"Backend '{path}' could not be imported. "
            "Ensure it is installed and the dotted path is correct."
        )


class InvalidRecipientError(NotificationError):
    """Raised when the recipient is not a valid User instance or queryset."""


class InvalidPayloadError(NotificationError):
    """Raised when notification title/body/data fails validation."""


class SignalRegistrationError(NotificationError):
    """Raised when a signal cannot be registered for a model."""

    def __init__(self, app_label: str, model_name: str, reason: str):
        super().__init__(
            f"Cannot register signal for '{app_label}.{model_name}': {reason}"
        )


class RecipientFieldError(NotificationError):
    """Raised when a dotted-path field string does not resolve to a User."""

    def __init__(self, field_path: str, model_name: str):
        super().__init__(
            f"Field path '{field_path}' on model '{model_name}' "
            "does not resolve to a User instance."
        )

