flip_api.utils.api_response
===========================

.. py:module:: flip_api.utils.api_response


Attributes
----------

.. autoapisummary::

   flip_api.utils.api_response.HEADERS


Functions
---------

.. autoapisummary::

   flip_api.utils.api_response.success
   flip_api.utils.api_response.error
   flip_api.utils.api_response.unhandled_error
   flip_api.utils.api_response.api_response


Module Contents
---------------

.. py:data:: HEADERS

.. py:function:: success(status_code: int = status.HTTP_200_OK, data: dict | None = None) -> dict

   Construct a successful API response with default CORS headers.

   :param status_code: HTTP status code for the response. Defaults to 200 OK.
   :type status_code: int
   :param data: Response body payload. Defaults to an empty dict when None.
   :type data: dict | None

   :returns: Response envelope with ``statusCode``, ``headers``, and JSON-encoded ``body``.
   :rtype: dict


.. py:function:: error(status_code: int, error: Exception | Any) -> dict

   Construct an error response with logging and error message.

   :param status_code: HTTP status code for the response.
   :type status_code: int
   :param error: The error to log. If it has a ``message`` attribute, that is returned
                 to the client; otherwise a generic message is used.
   :type error: Exception | Any

   :returns: Response envelope with ``statusCode``, ``headers``, and JSON-encoded ``body``
             containing the error message.
   :rtype: dict


.. py:function:: unhandled_error(status_code: int, error: Exception | Any) -> dict

   Construct an unhandled error response with logging and generic error message.

   :param status_code: HTTP status code for the response.
   :type status_code: int
   :param error: The error to log. Logged at error level when it exposes a
                 ``message`` attribute.
   :type error: Exception | Any

   :returns: Response envelope with ``statusCode``, ``headers``, and JSON-encoded ``body``
             containing a generic error message.
   :rtype: dict


.. py:function:: api_response(status_code: int, body: dict | None = None) -> dict

   Construct a generic API response with default CORS headers.

   :param status_code: HTTP status code for the response.
   :type status_code: int
   :param body: Response body payload. Defaults to an empty dict when None.
   :type body: dict | None

   :returns: Response envelope with ``statusCode``, ``headers``, and JSON-encoded ``body``.
   :rtype: dict