"""``/api/dashboard/kpis`` — server-aggregated Dashboard tiles.

Backs the Dashboard's "Claims / Billed / Received / Pending AR /
Denial rate" tiles + the monthly sparkline series + the
top-providers and top-denials lists.

Why this exists instead of ``GET /api/claims?limit=N``:
The Dashboard's KPIs are aggregates over *every* claim — billed,
received, denial rate, pending count, monthly billed/received. With
60k+ claims in production, paginating ``/api/claims`` and reducing
client-side silently produces wrong numbers (denial rate sampled,
billed summed from the first 100 rows). This endpoint does the
aggregation server-side in a single read so the Dashboard's numbers
are always correct regardless of dataset size.

SP36 Task 4: this single endpoint moved here from ``api.py:2732``.
"""
from __future__ import annotations

from fastapi import APIRouter, Depends, Query

from cyclone.auth.deps import matrix_gate
from cyclone.store import dashboard_kpis

router = APIRouter(dependencies=[Depends(matrix_gate)])


@router.get("/api/dashboard/kpis")
def get_dashboard_kpis(
    months: int = Query(6, ge=1, le=24),
    top_n_providers: int = Query(4, ge=0, le=50),
    top_n_denials: int = Query(5, ge=0, le=50),
) -> dict:
    """Server-aggregated Dashboard KPIs over the whole claim population."""
    return dashboard_kpis(
        months=months,
        top_n_providers=top_n_providers,
        top_n_denials=top_n_denials,
    )