.. module:: Decorators


Decorators
=========================

Response Wrapper
-----------------------------------------------------------------------------------

The ``@wrap_response`` decorator standardises all API endpoint responses into the
``ApiResponse`` contract, a ``TypedDict`` with four required fields:

.. code-block:: python

    {
        "code":   int,   # HTTP status code
        "status": str,   # "success" | "error" | "failure"
        "result": ...,   # payload on success, None on error/failure
        "error":  ...,   # error detail on error/failure, None on success
    }

``status`` semantics:

* ``"success"``  — 1XX / 2XX / 3XX responses
* ``"error"``    — 4XX managed errors (``ServiceException``, ``AuthorizationException``)
* ``"failure"``  — 5XX server errors (``InternalServerError`` or unhandled exceptions)

Usage example:

.. code-block:: python

    # -*- coding: utf-8 -*-

    from core_https import HTTPStatus
    from core_apis.decorators import wrap_response

    @wrap_response
    def get_item(item_id: int):
        return HTTPStatus.OK, {"id": item_id, "name": "Widget"}

    # Returns:
    # {"code": 200, "status": "success", "result": {"id": 1, "name": "Widget"}, "error": None}
..

Unhandled exceptions are caught and mapped to a generic 500 ``InternalServerError``
response, internal details are never disclosed to callers.


.. automodule:: core_apis.decorators.response_wrapper
   :members:
   :undoc-members:
   :show-inheritance:
   :private-members: