from __future__ import annotations

from typing import Any


class AppError(Exception):
    """Structured application error that can be safely returned through the API."""

    def __init__(
        self,
        code: str,
        message: str,
        *,
        status_code: int = 400,
        details: dict[str, Any] | None = None,
    ) -> None:
        super().__init__(message)
        self.code = code
        self.message = message
        self.status_code = status_code
        self.details = details or {}


class ExternalServiceError(AppError):
    pass


class ValidationAppError(AppError):
    pass


class ExecutionAppError(AppError):
    pass