"""Utilities for normalizing API responses."""

from __future__ import annotations

from typing import Any, Mapping

from pydantic import BaseModel

from ..core.constants import VERSION


def ensure_version_field(payload: Mapping[str, Any] | BaseModel) -> dict[str, Any]:
    """Return a copy of ``payload`` that always contains the version field."""

    if isinstance(payload, BaseModel):
        data = payload.model_dump()
    else:
        data = dict(payload)

    if "version" not in data or data["version"] is None:
        data["version"] = VERSION

    return data