"""Custom exceptions for sed.sh SDK."""

from typing import Optional, Any, Dict


class SedSHError(Exception):
    """Base exception for all sed.sh SDK errors.

    This exception and its subclasses are designed to be safe - they will never
    cause your application to crash unexpectedly. All API errors are caught and
    wrapped in appropriate exception types.
    """

    def __init__(
        self,
        message: str,
        status_code: Optional[int] = None,
        response: Optional[Dict[str, Any]] = None,
    ) -> None:
        """Initialize the exception.

        Args:
            message: Error message
            status_code: HTTP status code if applicable
            response: Full response data if available
        """
        super().__init__(message)
        self.message = message
        self.status_code = status_code
        self.response = response or {}

    def __str__(self) -> str:
        """Return string representation."""
        if self.status_code:
            return f"[{self.status_code}] {self.message}"
        return self.message


class AuthenticationError(SedSHError):
    """Raised when authentication fails (401 Unauthorized).

    This typically means:
    - Missing API key
    - Invalid API key
    - Expired API key
    """

    pass


class RateLimitError(SedSHError):
    """Raised when rate limit is exceeded (429 Too Many Requests).

    Note: This SDK does NOT implement automatic retries. You should implement
    retry logic with exponential backoff in your application if needed.
    """

    pass


class ResourceNotFoundError(SedSHError):
    """Raised when a resource is not found (404 Not Found).

    This typically means:
    - Invalid link code
    - Invalid inbox code
    - Invalid template ID
    - Invalid endpoint ID
    """

    pass


class InvalidRequestError(SedSHError):
    """Raised when request parameters are invalid (400 Bad Request).

    Note: This SDK does NOT perform client-side validation. All validation
    errors come from the API server.
    """

    pass


class PaymentRequiredError(SedSHError):
    """Raised when payment is required (402 Payment Required).

    This typically means insufficient account balance.
    """

    pass


class ServerError(SedSHError):
    """Raised when the server encounters an error (5xx status codes)."""

    pass


class NetworkError(SedSHError):
    """Raised when a network error occurs (connection timeout, DNS failure, etc.).

    Note: This SDK does NOT implement automatic retries for network errors.
    """

    pass
