"""
Authevo SDK Exceptions

Custom exception hierarchy for specific error handling and better developer experience.
"""


class AuthevoError(Exception):
    """Base exception for all Authevo SDK errors."""
    
    def __init__(self, message: str, docs_url: str = None):
        self.message = message
        self.docs_url = docs_url or "https://docs.authevo.com/troubleshooting"
        super().__init__(self._format_message())
    
    def _format_message(self) -> str:
        return f"{self.message}\n\nFor help, see: {self.docs_url}"


class AuthenticationError(AuthevoError):
    """Raised when API key is invalid, missing, or revoked."""
    
    def __init__(self, message: str = "API key invalid or missing"):
        super().__init__(
            message,
            docs_url="https://docs.authevo.com/authentication"
        )


class PolicyDeniedError(AuthevoError):
    """Raised when an action is denied by OPA policy."""
    
    def __init__(self, reason: str, policy_id: str):
        self.reason = reason
        self.policy_id = policy_id
        super().__init__(
            f"Policy '{policy_id}' denied action: {reason}",
            docs_url="https://docs.authevo.com/policies"
        )


class VerificationError(AuthevoError):
    """Raised when signature verification fails."""
    
    def __init__(self, message: str = "Signature verification failed"):
        super().__init__(
            message,
            docs_url="https://docs.authevo.com/verification"
        )


class RateLimitError(AuthevoError):
    """Raised when API rate limit is exceeded."""
    
    def __init__(self, retry_after: int = 60):
        self.retry_after = retry_after
        super().__init__(
            f"Rate limit exceeded. Retry after {retry_after} seconds.",
            docs_url="https://docs.authevo.com/rate-limits"
        )


class NetworkError(AuthevoError):
    """Raised when network or API connectivity issues occur."""
    
    def __init__(self, message: str = "Network connectivity error"):
        super().__init__(
            message,
            docs_url="https://docs.authevo.com/troubleshooting#network"
        )


class IdempotencyError(AuthevoError):
    """Raised when an idempotency key conflict occurs."""
    
    def __init__(self, message: str = "Idempotency key already used"):
        super().__init__(
            message,
            docs_url="https://docs.authevo.com/idempotency"
        )


class ConfigurationError(AuthevoError):
    """Raised when SDK configuration is invalid."""
    
    def __init__(self, message: str):
        super().__init__(
            message,
            docs_url="https://docs.authevo.com/configuration"
        )


class AgentRevokedError(AuthevoError):
    """Raised when attempting to use a revoked agent DID."""
    
    def __init__(self, did: str):
        self.did = did
        super().__init__(
            f"Agent DID has been revoked: {did}",
            docs_url="https://docs.authevo.com/revocation"
        )
