"""
Unified API Response Format Utilities

This module provides helper functions to ensure all API endpoints
return a consistent response format.
"""

from rest_framework.response import Response
from rest_framework import status


def success_response(data=None, message=None, status_code=status.HTTP_200_OK):
    """
    Create a standardized success response.
    
    Args:
        data: Response data (dict, list, or any serializable object)
        message: Optional human-readable success message
        status_code: HTTP status code (default: 200)
    
    Returns:
        Response: DRF Response object with unified format
    
    Example:
        return success_response(
            data={"id": 1, "name": "Example"},
            message="Resource created successfully"
        )
    """
    response_data = {
        "success": True,
        "data": data,
    }
    
    if message:
        response_data["message"] = message
    
    return Response(response_data, status=status_code)


def error_response(
    error,
    errors=None,
    status_code=status.HTTP_400_BAD_REQUEST,
    message=None
):
    """
    Create a standardized error response.
    
    Args:
        error: Top-level error message (string)
        errors: Optional field-specific validation errors (dict)
        status_code: HTTP status code (default: 400)
        message: Optional additional message (deprecated, use error)
    
    Returns:
        Response: DRF Response object with unified format
    
    Example:
        return error_response(
            error="Validation failed",
            errors={"email": ["Invalid email format"]},
            status_code=status.HTTP_400_BAD_REQUEST
        )
    """
    response_data = {
        "success": False,
        "error": error,
    }
    
    if errors:
        response_data["errors"] = errors
    
    # Backward compatibility: if message is provided, use it as error
    if message and not error:
        response_data["error"] = message
    
    return Response(response_data, status=status_code)


def paginated_response(paginated_data, message=None):
    """
    Create a standardized paginated response.
    
    This wraps DRF's pagination response to include success flag
    and optional message while preserving pagination metadata.
    
    Args:
        paginated_data: DRF paginated response data (dict with count, next, previous, results)
        message: Optional human-readable message
    
    Returns:
        Response: DRF Response object with unified format
    
    Example:
        paginator = CustomPageNumberPagination()
        page = paginator.paginate_queryset(queryset, request)
        serializer = MySerializer(page, many=True)
        paginated_data = paginator.get_paginated_response(serializer.data).data
        return paginated_response(paginated_data, message="Keywords retrieved successfully")
    """
    response_data = {
        "success": True,
        **paginated_data  # Unpack count, next, previous, results
    }
    
    if message:
        response_data["message"] = message
    
    return Response(response_data)