from __future__ import annotations
"""
Custom exceptions for the Budgero SDK.
"""


class BudgeroError(Exception):
    """Base exception for all Budgero SDK errors."""

    pass


class AuthenticationError(BudgeroError):
    """
    Raised when authentication fails.

    This can occur when:
    - The API key is invalid or expired
    - The API key has been revoked
    - The token is malformed
    """

    pass


class EncryptionError(BudgeroError):
    """
    Raised when encryption or decryption fails.

    This can occur when:
    - The encryption key is invalid
    - The key length is incorrect (must be 32 bytes for AES-256)
    - The encrypted payload is corrupted
    - The IV/nonce is invalid
    """

    pass


class APIError(BudgeroError):
    """
    Raised when an API request fails.

    Attributes:
        status_code: HTTP status code from the API.
        response_body: Raw response body if available.
    """

    def __init__(
        self,
        message: str,
        status_code: int | None = None,
        response_body: str | None = None,
    ):
        super().__init__(message)
        self.status_code = status_code
        self.response_body = response_body

    def __str__(self) -> str:
        base = super().__str__()
        if self.status_code:
            return f"{base} (HTTP {self.status_code})"
        return base


class ValidationError(BudgeroError):
    """
    Raised when input validation fails.

    This can occur when:
    - Required fields are missing
    - Field values are out of valid range
    - Date formats are invalid
    """

    pass


class NetworkError(BudgeroError):
    """
    Raised when a network error occurs.

    This can occur when:
    - The server is unreachable
    - The connection times out
    - DNS resolution fails
    """

    pass
