"""Exception classes for the Chaturbate Events client."""


class EventsError(Exception):
    """Base exception for all Chaturbate Events API failures.

    This exception serves as the base class for all API-related errors and
    includes enhanced error information such as HTTP status codes and response
    text when available.

    Attributes:
        status_code: HTTP status code from the failed request, if available.
        response_text: Raw response text from the API, if available.
    """

    def __init__(
        self,
        message: str,
        *,
        status_code: int | None = None,
        response_text: str | None = None,
    ) -> None:
        """Initialize EventsError with enhanced error information.

        Args:
            message: The error message describing what went wrong.
            status_code: HTTP status code from the failed request, if available.
            response_text: Raw response text from the API, if available.
        """
        super().__init__(message)
        self.status_code = status_code
        self.response_text = response_text

    def __str__(self) -> str:
        """Return user-friendly string representation of the error.

        Returns:
            The error message, optionally including the status code.
        """
        if self.status_code is not None:
            return f"{super().__str__()} (HTTP {self.status_code})"
        return super().__str__()

    def __repr__(self) -> str:
        """Return detailed string representation for debugging.

        Returns:
            A string showing the class name and all error attributes.
        """
        parts = [f"message={self.args[0]!r}"]
        if self.status_code is not None:
            parts.append(f"status_code={self.status_code}")
        if self.response_text is not None:
            parts.append(f"response_text={self.response_text[:50]!r}...")
        return f"{self.__class__.__name__}({', '.join(parts)})"


class AuthError(EventsError):
    """Authentication or authorization failure with the Events API.

    Raised when API credentials are invalid, missing, expired, or when the user
    lacks sufficient permissions for the requested operation. This typically
    occurs with HTTP 401 (Unauthorized) or 403 (Forbidden) responses.

    Examples:
        >>> raise AuthError("Invalid API token")
        >>> raise AuthError("Authentication failed", status_code=401)
    """
