# ============================================
# Projet   : API-KA
# Fichier  : src/api/routes/__init__.py
# Node     : m3u96b
# Author   : Simon-Pierre Boucher
# Contact  : contact@spboucher.ai
# Date     : 2026-08-16
# ============================================
"""Routes de l'API publique + enveloppe de réponse uniforme."""

from __future__ import annotations

from typing import Any

from src.config import get_settings


def envelope(
    data: Any,
    *,
    page: int | None = None,
    limit: int | None = None,
    total: int | None = None,
    extra_meta: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Construit la réponse uniforme ``{success, data, meta}`` de l'API.

    Le ``meta`` contient toujours le node (m3u96b) et, si fournis, la
    pagination (``page``, ``limit``, ``total``).
    """
    meta: dict[str, Any] = {}
    if page is not None:
        meta["page"] = page
    if limit is not None:
        meta["limit"] = limit
    if total is not None:
        meta["total"] = total
    meta["node"] = get_settings().node_name
    if extra_meta:
        meta.update(extra_meta)
    return {"success": True, "data": data, "meta": meta}