Add trending movies/series, refreshed on a schedule

Mirrors TMDb's own /trending/{movie|tv}/{day|week} ranking rather than
Aurora computing trending itself from popularity deltas -- that would
require re-syncing the entire catalog on a schedule, infeasible at any
real scale, whereas TMDb already computes this well from signals (real
view/search velocity) Aurora has no access to.

New: TrendingEntry model + migration 0003, MetadataProvider.get_trending
(concrete/optional, like aclose(), so existing test fakes don't all need
updating), refresh_trending() which actually ingests each trending item
(only ~20 per window, cheap enough to fully ingest rather than apply the
never-fabricate-a-stub rule recommendations uses), a twice-daily arq cron
job (WorkerSettings.cron_jobs, new to this codebase), a manual admin
trigger for right after a deploy, and GET /movies/trending + GET
/series/trending.

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

app/api/v1/admin.py

@@ -168,6 +168,29 @@ async def enqueue_collection_ingestion(
     )
 
 
+class TrendingRefreshEnqueuedOut(BaseModel):
+    arq_job_id: str
+    status: str = "enqueued"
+
+
+@router.post("/refresh-trending", response_model=TrendingRefreshEnqueuedOut)
+async def enqueue_trending_refresh(
+    queue: ArqRedis = Depends(get_queue),
+) -> TrendingRefreshEnqueuedOut:
+    """Manually kick off the same refresh the twice-daily cron job runs
+    (see WorkerSettings.cron_jobs) -- useful right after a fresh deploy so
+    GET /movies/trending isn't empty until the next scheduled tick. Not
+    tracked via ingestion_jobs (see refresh_trending_task's docstring), so
+    there's no job_id to poll -- check GET /movies/trending directly."""
+
+    arq_job = await queue.enqueue_job("refresh_trending_task")
+    if arq_job is None:
+        raise HTTPException(
+            status.HTTP_503_SERVICE_UNAVAILABLE, "Could not enqueue trending refresh (queue busy)."
+        )
+    return TrendingRefreshEnqueuedOut(arq_job_id=arq_job.job_id)
+
+
 @router.get("/ingest/jobs/{job_id}", response_model=IngestionJobOut)
 async def get_ingestion_job_status(
     job_id: uuid.UUID, session: AsyncSession = Depends(get_db)

app/api/v1/movies.py

@@ -75,6 +75,21 @@ async def upcoming_movies(
     return await movie_service.list_upcoming(session, region=region, page=page, page_size=page_size)
 
 
+@router.get("/trending", response_model=MovieListOut)
+async def trending_movies(
+    time_window: Literal["day", "week"] = Query("day", alias="window"),
+    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_trending(
+            session, time_window=time_window, 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

@@ -55,6 +55,21 @@ async def list_series(
         raise HTTPException(status.HTTP_422_UNPROCESSABLE_CONTENT, str(exc)) from exc
 
 
+@router.get("/trending", response_model=SeriesListOut)
+async def trending_series(
+    time_window: Literal["day", "week"] = Query("day", alias="window"),
+    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_trending(
+            session, time_window=time_window, 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,