"""Response envelope construction helpers."""

from __future__ import annotations

from typing import Any


def ok(data: Any, warnings: list[str] | None = None) -> dict[str, Any]:
    """Build a success envelope.

    Args:
        data: The response payload.
        warnings: Optional list of warning messages.

    Returns:
        A success envelope dict.

    """
    return {
        "ok": True,
        "warnings": warnings or [],
        "data": data,
    }


def error(code: str, message: str) -> dict[str, Any]:
    """Build an error envelope.

    Args:
        code: Machine-readable error code.
        message: Human-readable error message.

    Returns:
        An error envelope dict.

    """
    return {
        "ok": False,
        "error": {
            "code": code,
            "message": message,
        },
    }
