FirstCore/app/api/helpers/response_helper.py

from flask import jsonify
from typing import List, Dict, Union, Optional, Any


class ResponseHelper:
    """
    A helper class for building standardized JSON responses in Flask.
    """

    @staticmethod
    def build_response(
        status: bool,
        message: str,
        data: Optional[Union[Dict, List, str]] = None,
        status_code: int = 200,
        error: Optional[Union[Dict, str]] = None,
    ) -> Dict[str, Any]:
        """
        Build a standardized JSON response.

        Args:
            status (bool): Indicates whether the request was successful.
            message (str): A message describing the result of the request.
            data (Optional[Union[Dict, List, str]]): The data to return in the response.
            status_code (int): The HTTP status code for the response.
            error (Optional[Union[Dict, str]]): Any error details to include in the response.

        Returns:
            Dict[str, Any]: A dictionary representing the JSON response.
        """
        response = {
            "status": status,
            "statusCode": status_code,
            "message": message,
            "data": data if data is not None else {},
            "error": error if error is not None else {},
        }
        return jsonify(response), status_code

    @staticmethod
    def success(
        data: Optional[Union[Dict, List, str]] = None,
        message: str = "Successful",
        status_code: int = 200,
        error: Optional[Union[Dict, str]] = None,
    ) -> Dict[str, Any]:
        """
        Return a success response.

        Args:
            data (Optional[Union[Dict, List, str]]): The data to return in the response.
            message (str): A message describing the result of the request.
            status_code (int): The HTTP status code for the response.
            error (Optional[Union[Dict, str]]): Any error details to include in the response.

        Returns:
            Dict[str, Any]: A dictionary representing the JSON response.
        """
        return ResponseHelper.build_response(True, message, data, status_code, error)

    @staticmethod
    def error(
        message: str = "An error occurred",
        status_code: int = 400,
        data: Optional[Union[Dict, List, str]] = None,
        error: Optional[Union[Dict, str]] = None,
    ) -> Dict[str, Any]:
        """
        Return an error response.

        Args:
            message (str): A message describing the error.
            status_code (int): The HTTP status code for the response.
            data (Optional[Union[Dict, List, str]]): The data to return in the response.
            error (Optional[Union[Dict, str]]): Any error details to include in the response.

        Returns:
            Dict[str, Any]: A dictionary representing the JSON response.
        """
        return ResponseHelper.build_response(False, message, data, status_code, error)

    @staticmethod
    def created(
        data: Optional[Union[Dict, List, str]] = None,
        message: str = "Resource created successfully",
        error: Optional[Union[Dict, str]] = None,
    ) -> Dict[str, Any]:
        """
        Return a response for a created resource.

        Args:
            data (Optional[Union[Dict, List, str]]): The data to return in the response.
            message (str): A message describing the result of the request.
            error (Optional[Union[Dict, str]]): Any error details to include in the response.

        Returns:
            Dict[str, Any]: A dictionary representing the JSON response.
        """
        return ResponseHelper.build_response(True, message, data, 201, error)

    @staticmethod
    def updated(
        data: Optional[Union[Dict, List, str]] = None,
        message: str = "Resource updated successfully",
        error: Optional[Union[Dict, str]] = None,
    ) -> Dict[str, Any]:
        """
        Return a response for an updated resource.

        Args:
            data (Optional[Union[Dict, List, str]]): The data to return in the response.
            message (str): A message describing the result of the request.
            error (Optional[Union[Dict, str]]): Any error details to include in the response.

        Returns:
            Dict[str, Any]: A dictionary representing the JSON response.
        """
        return ResponseHelper.build_response(True, message, data, 200, error)

    @staticmethod
    def internal_server_error(
        message: str = "Internal Server Error",
        data: Optional[Union[Dict, List, str]] = None,
        error: Optional[Union[Dict, str]] = None,
    ) -> Dict[str, Any]:
        """
        Return a response for an internal server error.

        Args:
            message (str): A message describing the error.
            data (Optional[Union[Dict, List, str]]): The data to return in the response.
            error (Optional[Union[Dict, str]]): Any error details to include in the response.

        Returns:
            Dict[str, Any]: A dictionary representing the JSON response.
        """
        return ResponseHelper.build_response(False, message, data, 500, error)

    @staticmethod
    def unauthorized(
        message: str = "Unauthorized",
        data: Optional[Union[Dict, List, str]] = None,
        error: Optional[Union[Dict, str]] = None,
    ) -> Dict[str, Any]:
        """
        Return a response for an unauthorized request.

        Args:
            message (str): A message describing the error.
            data (Optional[Union[Dict, List, str]]): The data to return in the response.
            error (Optional[Union[Dict, str]]): Any error details to include in the response.

        Returns:
            Dict[str, Any]: A dictionary representing the JSON response.
        """
        return ResponseHelper.build_response(False, message, data, 401, error)

    @staticmethod
    def forbidden(
        message: str = "Forbidden",
        data: Optional[Union[Dict, List, str]] = None,
        error: Optional[Union[Dict, str]] = None,
    ) -> Dict[str, Any]:
        """
        Return a response for a forbidden request.

        Args:
            message (str): A message describing the error.
            data (Optional[Union[Dict, List, str]]): The data to return in the response.
            error (Optional[Union[Dict, str]]): Any error details to include in the response.

        Returns:
            Dict[str, Any]: A dictionary representing the JSON response.
        """
        return ResponseHelper.build_response(False, message, data, 403, error)

    @staticmethod
    def not_found(
        message: str = "Resource not found",
        data: Optional[Union[Dict, List, str]] = None,
        error: Optional[Union[Dict, str]] = None,
    ) -> Dict[str, Any]:
        """
        Return a response for a not found resource.

        Args:
            message (str): A message describing the error.
            data (Optional[Union[Dict, List, str]]): The data to return in the response.
            error (Optional[Union[Dict, str]]): Any error details to include in the response.

        Returns:
            Dict[str, Any]: A dictionary representing the JSON response.
        """
        return ResponseHelper.build_response(False, message, data, 404, error)

    @staticmethod
    def unprocessable_entity(
        message: str = "Unprocessable entity",
        data: Optional[Union[Dict, List, str]] = None,
        error: Optional[Union[Dict, str]] = None,
    ) -> Dict[str, Any]:
        """
        Return a response for an unprocessable entity.

        Args:
            message (str): A message describing the error.
            data (Optional[Union[Dict, List, str]]): The data to return in the response.
            error (Optional[Union[Dict, str]]): Any error details to include in the response.

        Returns:
            Dict[str, Any]: A dictionary representing the JSON response.
        """
        return ResponseHelper.build_response(False, message, data, 422, error)
    
    @staticmethod
    def method_not_allowed(
        message: str = "Method Not Allowed",
        data: Optional[Union[Dict, List, str]] = None,
        error: Optional[Union[Dict, str]] = None,
    ) -> Dict[str, Any]:
        """
        Return a response for a method not allowed error.

        Args:
            message (str): A message describing the error.
            data (Optional[Union[Dict, List, str]]): The data to return in the response.
            error (Optional[Union[Dict, str]]): Any error details to include in the response.

        Returns:
            Dict[str, Any]: A dictionary representing the JSON response.
        """
        return ResponseHelper.build_response(False, message, data, 405, error)
    
    @staticmethod
    def bad_request(
        message: str = "Bad Request",
        data: Optional[Union[Dict, List, str]] = None,
        error: Optional[Union[Dict, str]] = None,
    ) -> Dict[str, Any]:
        """
        Return a response for a bad request error.

        Args:
            message (str): A message describing the error.
            data (Optional[Union[Dict, List, str]]): The data to return in the response.
            error (Optional[Union[Dict, str]]): Any error details to include in the response.

        Returns:
            Dict[str, Any]: A dictionary representing the JSON response.
        """
        return ResponseHelper.build_response(False, message, data, 400, error)