"""
Common Response Schemas
Standardized API responses with proper HTTP status codes

The 'success' field is automatically set based on status code:
- 2xx (200-299) = success: true
- 4xx/5xx = success: false (handled by exception handlers)
"""
from typing import Generic, TypeVar, Optional, List, Any, Dict
from pydantic import BaseModel, Field

T = TypeVar("T")


class ResponseBase(BaseModel):
    """
    Base response schema

    The 'success' field indicates operation success (true for 2xx codes)
    """
    success: bool = Field(default=True, description="Operation success status")
    message: str = Field(description="Response message")


class DataResponse(ResponseBase, Generic[T]):
    """
    Response with single data object

    Usage:
        return DataResponse(
            success=True,
            message="User retrieved successfully",
            data=user_data
        )

    Encryption Note:
        For GET endpoints, data will be auto-encrypted if ENCRYPTION_ENABLED=true
    """
    data: Optional[T] = Field(default=None, description="Response data")


class PaginationResponse(ResponseBase, Generic[T]):
    """
    Response with paginated data

    Usage:
        return PaginationResponse(
            success=True,
            message="Users retrieved successfully",
            data=users_list,
            total=100,
            page=1,
            size=10,
            pages=10
        )
    """
    data: List[T] = Field(description="List of items")
    total: int = Field(description="Total number of items")
    page: int = Field(description="Current page number")
    size: int = Field(description="Items per page")
    pages: int = Field(description="Total number of pages")


class ErrorResponse(BaseModel):
    """
    Error response schema (automatically generated by exception handlers)

    Example:
        {
            "success": false,
            "message": "User not found",
            "details": {"user_id": 123}
        }
    """
    success: bool = Field(default=False)
    message: str = Field(description="Error message")
    details: Dict[str, Any] = Field(default_factory=dict, description="Additional error details")