Add GET /movies and GET /series browse/discover endpoints

The complement to /search for browsing without a query: paginated,
filterable (genre, year, status) and sortable (popularity,
release/air date, rating, title) listings. Offset-based pagination
rather than the Aurora ID cursor scheme, since sorting by
popularity/rating/date doesn't line up with creation-order cursors.

Total count is computed via a window function in the same query as
the page of results, avoiding a second round trip per request. An
invalid filter (malformed genre id, unknown status) is a 422 via a
per-service InvalidMovieFilterError/InvalidSeriesFilterError, caught
before any DB query runs.

build_movie_summary/build_series_summary refactored to share their
row-to-summary logic with the new list path, avoiding a redundant
get_by_id lookup when the row is already in hand.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

app/api/v1/movies.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
-from fastapi import APIRouter, Depends
+from typing import Literal
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
 from redis.asyncio import Redis
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -14,6 +16,7 @@ from app.schemas.movie import (
     MovieCreditsOut,
     MovieDetailOut,
     MovieImagesOut,
+    MovieListOut,
     MovieRecommendationsOut,
     MovieVideosOut,
 )
@@ -23,6 +26,32 @@ from app.services.cache import build_key
 router = APIRouter(prefix="/movies", tags=["movies"], dependencies=[Depends(enforce_rate_limit)])
 
 
+@router.get("", response_model=MovieListOut)
+async def list_movies(
+    genre: str | None = Query(None, description="Aurora genre id, e.g. aur_genre_..."),
+    year: int | None = Query(None, description="Primary release year"),
+    status_: str | None = Query(None, alias="status", description="Movie status, e.g. released"),
+    sort_by: Literal["popularity", "release_date", "vote_average", "title"] = 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),
+) -> MovieListOut:
+    try:
+        return await movie_service.list_movies(
+            session,
+            genre_aurora_id=genre,
+            year=year,
+            status=status_,
+            sort_by=sort_by,
+            sort_dir=sort_dir,
+            page=page,
+            page_size=page_size,
+        )
+    except movie_service.InvalidMovieFilterError as exc:
+        raise HTTPException(status.HTTP_422_UNPROCESSABLE_CONTENT, str(exc)) from exc
+
+
 @router.get("/{aurora_id}", response_model=MovieDetailOut)
 async def get_movie(
     aurora_id: str,

app/api/v1/series.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
-from fastapi import APIRouter, Depends
+from typing import Literal
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
 from redis.asyncio import Redis
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -10,13 +12,39 @@ 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.tv import SeriesDetailOut, SeriesSeasonsOut
+from app.schemas.tv import SeriesDetailOut, SeriesListOut, SeriesSeasonsOut
 from app.services import tv_service
 from app.services.cache import build_key
 
 router = APIRouter(prefix="/series", tags=["series"], dependencies=[Depends(enforce_rate_limit)])
 
 
+@router.get("", response_model=SeriesListOut)
+async def list_series(
+    genre: str | None = Query(None, description="Aurora genre id, e.g. aur_genre_..."),
+    year: int | None = Query(None, description="First air date year"),
+    status_: str | None = Query(None, alias="status", description="Series status, e.g. ended"),
+    sort_by: Literal["popularity", "first_air_date", "vote_average", "title"] = 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),
+) -> SeriesListOut:
+    try:
+        return await tv_service.list_series(
+            session,
+            genre_aurora_id=genre,
+            year=year,
+            status=status_,
+            sort_by=sort_by,
+            sort_dir=sort_dir,
+            page=page,
+            page_size=page_size,
+        )
+    except tv_service.InvalidSeriesFilterError as exc:
+        raise HTTPException(status.HTTP_422_UNPROCESSABLE_CONTENT, str(exc)) from exc
+
+
 @router.get("/{aurora_id}", response_model=SeriesDetailOut)
 async def get_series(
     aurora_id: str,