routes.py

"""Versioned API routes under /api/v1/.

Two endpoints in the scaffold:

- ``GET /api/v1/health``  — liveness + running package version.
- ``GET /api/v1/echo``    — returns the ``msg`` query param wrapped in a
                            ``StrictModel``. Demonstrates the request/response
                            contract pattern that downstream tickets follow.

Session-store wiring is plumbed via ``request.app.state.session_store`` for
endpoints that need it (none in the scaffold; pattern is preserved for the
agent / chat endpoint a real project would add).
"""

from __future__ import annotations

from importlib.metadata import PackageNotFoundError, version

from fastapi import APIRouter
from pydantic import Field

from src.models._base import StrictModel
from src.models.health import HealthResponse


def _package_version() -> str:
    try:
        return version("harness-python-react")
    except PackageNotFoundError:
        return "0.0.0+local"


router = APIRouter(prefix="/api/v1")


class EchoResponse(StrictModel, strict=True):
    """Response body for `GET /api/v1/echo`."""

    echoed: str = Field(description="Whatever the client sent in `?msg=`")


@router.get("/health")
async def health() -> HealthResponse:
    """Liveness signal + the running package version.

    The version is sourced from ``importlib.metadata`` so the deployed
    container can be correlated with a ``pyproject.toml`` revision and a
    release tag without inspecting the image.
    """
    return HealthResponse(status="ok", version=_package_version())


@router.get("/echo")
async def echo(msg: str) -> EchoResponse:
    """Echo the ``msg`` query parameter back as a typed response."""
    return EchoResponse(echoed=msg)