"""
Custom exceptions for the pygeai-gam package.

This module defines a hierarchy of exceptions specific to GAM OAuth 2.0 operations.
All exceptions inherit from the base GAMClientError class.
"""


class GAMClientError(Exception):
    """
    Base exception class for all GAM client errors.

    All other GAM-specific exceptions inherit from this class, allowing
    users to catch all GAM-related errors with a single except clause.

    :param message: Human-readable error description
    :param status_code: Optional HTTP status code associated with the error
    :param response: Optional response object or data from the failed request
    """

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

    def __str__(self):
        if self.status_code:
            return f"[{self.status_code}] {self.message}"
        return self.message


class GAMAuthenticationError(GAMClientError):
    """
    Exception raised for authentication and authorization failures.

    This exception is raised when:
    - Invalid credentials are provided (401 Unauthorized)
    - Insufficient permissions for the requested resource (403 Forbidden)
    - Token has expired or is invalid
    - OAuth flow fails due to authentication issues

    :param message: Human-readable error description
    :param status_code: HTTP status code (typically 401 or 403)
    :param response: Response object or data from the failed request
    """

    pass


class GAMAPIError(GAMClientError):
    """
    Exception raised for general GAM API request failures.

    This exception is raised when:
    - API returns an error status code (4xx or 5xx)
    - Server-side errors occur (500, 502, 503, etc.)
    - Request validation fails (400 Bad Request)
    - Resource not found (404)

    :param message: Human-readable error description
    :param status_code: HTTP status code
    :param response: Response object or data from the failed request
    """

    pass


class GAMInvalidResponseError(GAMClientError):
    """
    Exception raised when the API response cannot be parsed or is invalid.

    This exception is raised when:
    - Response body is not valid JSON
    - Expected fields are missing from the response
    - Response format doesn't match the expected schema

    :param message: Human-readable error description
    :param response: The invalid response object or data
    """

    def __init__(self, message: str, response=None):
        super().__init__(message, status_code=None, response=response)


class GAMMissingParameterError(GAMClientError):
    """
    Exception raised when required parameters are missing from a request.

    This exception is raised when:
    - Required method parameters are None or empty
    - OAuth flow is missing required fields (client_id, redirect_uri, etc.)
    - Token refresh is attempted without a refresh_token

    :param message: Human-readable error description with details about missing parameter
    :param parameter_name: Name of the missing parameter
    """

    def __init__(self, message: str, parameter_name: str = None):
        super().__init__(message)
        self.parameter_name = parameter_name

    def __str__(self):
        if self.parameter_name:
            return f"Missing required parameter: {self.parameter_name}. {self.message}"
        return self.message
