"""DepthSignal SDK exceptions.

All exception classes live here to avoid circular imports.
"""

import warnings
from typing import Optional


class DepthSignalError(Exception):
    """Base exception for DepthSignal API errors."""

    def __init__(self, status_code: int, detail: str):
        self.status_code = status_code
        self.detail = detail
        # Sanitize detail to prevent leaking internal server info
        safe_detail = detail[:500] if detail else "Unknown error"
        super().__init__(f"HTTP {status_code}: {safe_detail}")


class RateLimitError(DepthSignalError):
    """Raised when rate limit is exceeded."""

    def __init__(self, detail: str, retry_after: Optional[int] = None):
        super().__init__(429, detail)
        self.retry_after = retry_after


class AuthenticationError(DepthSignalError):
    """Raised when API key is invalid or expired."""

    def __init__(self, detail: str = "Invalid or expired API key"):
        super().__init__(401, detail)


class TierAccessError(DepthSignalError):
    """Raised when endpoint requires a higher tier."""

    def __init__(self, detail: str = "This endpoint requires a higher tier"):
        super().__init__(403, detail)


class APIConnectionError(DepthSignalError):
    """Raised when the API is unreachable.

    Named ``APIConnectionError`` (not ``ConnectionError``) to avoid
    shadowing Python's built-in ``ConnectionError``.
    """

    def __init__(self, detail: str = "Could not connect to DepthSignal API"):
        super().__init__(0, detail)


def _deprecated_connection_error(*args: object, **kwargs: object) -> APIConnectionError:
    """Backward-compatible factory. Use ``APIConnectionError`` instead."""
    warnings.warn(
        "depthsignal.ConnectionError is deprecated — use APIConnectionError",
        DeprecationWarning,
        stacklevel=2,
    )
    return APIConnectionError(*args, **kwargs)  # type: ignore[arg-type]


__all__ = [
    "DepthSignalError",
    "RateLimitError",
    "AuthenticationError",
    "TierAccessError",
    "APIConnectionError",
]
