"""
shared/utils/responses.py
==========================
Funciones helper para respuestas HTTP uniformes en toda la API.

Todas las respuestas de la API siguen el mismo formato JSON:
{
    "success": true/false,
    "message": "Descripción opcional",
    "data": { ... } o null,
    "errors": { ... } o null,
    "meta": { "page": 1, "total": 100, ... } (solo en listas)
}

Ventaja: el frontend puede manejar cualquier respuesta de la misma forma.
"""

from rest_framework.response import Response
from rest_framework import status


def success_response(
    data=None,
    message: str = '',
    status_code: int = status.HTTP_200_OK,
    meta: dict = None
) -> Response:
    """
    Respuesta exitosa estandarizada.
    
    Args:
        data: Datos a retornar (dict, list, etc.)
        message: Mensaje descriptivo opcional
        status_code: Código HTTP (default: 200)
        meta: Metadatos de paginación u otros
    
    Ejemplo:
        return success_response(
            data=serializer.data,
            message='Asignatura creada exitosamente',
            status_code=201
        )
    """
    payload = {
        'success': True,
        'message': message,
        'data': data,
        'errors': None,
    }
    if meta:
        payload['meta'] = meta
    return Response(payload, status=status_code)


def error_response(
    message: str,
    errors=None,
    status_code: int = status.HTTP_400_BAD_REQUEST
) -> Response:
    """
    Respuesta de error estandarizada.
    
    Args:
        message: Mensaje de error principal (para mostrar al usuario)
        errors: Dict de errores por campo (de serializers) o lista
        status_code: Código HTTP (default: 400)
    
    Ejemplo:
        return error_response(
            message='Datos inválidos',
            errors=serializer.errors,
            status_code=422
        )
    """
    return Response({
        'success': False,
        'message': message,
        'data': None,
        'errors': errors,
    }, status=status_code)


def paginated_response(paginator, serializer_data, message: str = '') -> Response:
    """
    Respuesta paginada con metadatos de navegación.
    
    Args:
        paginator: Instancia del paginador de DRF con resultado
        serializer_data: Datos ya serializados
        message: Mensaje opcional
    
    Retorna la respuesta con meta.page, meta.total, meta.pages, etc.
    """
    return Response({
        'success': True,
        'message': message,
        'data': serializer_data,
        'errors': None,
        'meta': {
            'total':    paginator.page.paginator.count,
            'pages':    paginator.page.paginator.num_pages,
            'page':     paginator.page.number,
            'per_page': paginator.page_size,
            'next':     paginator.get_next_link(),
            'previous': paginator.get_previous_link(),
        }
    })