Aurora-Core/app/api/v1/people.py

"""Person endpoints (section 17)."""

from __future__ import annotations

from typing import Literal

from fastapi import APIRouter, Depends, Query
from redis.asyncio import Redis
from sqlalchemy.ext.asyncio import AsyncSession

from app.api.deps import cached_response, not_found
from app.core.database import get_db
from app.core.redis import get_redis
from app.core.security import enforce_rate_limit
from app.schemas.person import PersonCreditsOut, PersonDetailOut, PersonListOut
from app.services import person_service
from app.services.cache import build_key

router = APIRouter(prefix="/people", tags=["people"], dependencies=[Depends(enforce_rate_limit)])


@router.get("", response_model=PersonListOut)
async def list_people(
    known_for_department: str | None = Query(
        None, description="Exact match, e.g. Acting, Directing, Writing"
    ),
    sort_by: Literal["popularity", "name"] = Query("popularity"),
    sort_dir: Literal["asc", "desc"] = Query("desc"),
    page: int = Query(1, ge=1),
    page_size: int = Query(20, ge=1, le=50),
    session: AsyncSession = Depends(get_db),
) -> PersonListOut:
    return await person_service.list_people(
        session,
        known_for_department=known_for_department,
        sort_by=sort_by,
        sort_dir=sort_dir,
        page=page,
        page_size=page_size,
    )


@router.get("/{aurora_id}", response_model=PersonDetailOut)
async def get_person(
    aurora_id: str,
    session: AsyncSession = Depends(get_db),
    redis: Redis = Depends(get_redis),
) -> PersonDetailOut:
    try:
        return await cached_response(
            redis,
            build_key("person", aurora_id),
            PersonDetailOut,
            lambda: person_service.get_person_detail(session, aurora_id),
        )
    except person_service.PersonNotFoundError as exc:
        raise not_found("person", aurora_id) from exc


@router.get("/{aurora_id}/credits", response_model=PersonCreditsOut)
async def get_person_credits(
    aurora_id: str, session: AsyncSession = Depends(get_db)
) -> PersonCreditsOut:
    try:
        return await person_service.get_person_credits(session, aurora_id)
    except person_service.PersonNotFoundError as exc:
        raise not_found("person", aurora_id) from exc