Add movie/series ratings and watchlist

Builds on the accounts foundation: PUT/DELETE a rating (0.5-10.0) or a watchlist entry on any movie or series, all scoped to the bearer token's own user, plus GET /account/ratings|watchlist/{movies,series} to list them back. Both are polymorphic entity_type/entity_id tables, same shape as watch_provider_offerings and trending_entries, so movie and series share one repository/router each rather than duplicating per type. Co-Authored-By: Claude Sonnet 5 <[email protected]>
2026-09-06 10:47:41 -05:00
parent a38c2074a6
commit 0ab31a314c
20 changed files with 1043 additions and 6 deletions
@@ -0,0 +1,62 @@
+"""The authenticated user's own ratings and watchlist (section 17,
+additive) -- everything here requires a bearer token and is scoped to the
+caller, unlike every other read endpoint in Aurora Core."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_current_user
+from app.core.database import get_db
+from app.core.security import enforce_rate_limit
+from app.models.user import User
+from app.schemas.movie import MovieListOut, RatedMovieListOut
+from app.schemas.tv import RatedSeriesListOut, SeriesListOut
+from app.services import movie_service, tv_service
+
+router = APIRouter(prefix="/account", tags=["account"], dependencies=[Depends(enforce_rate_limit)])
+
+
+@router.get("/ratings/movies", response_model=RatedMovieListOut)
+async def list_rated_movies(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=50),
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db),
+) -> RatedMovieListOut:
+    return await movie_service.list_rated_movies(session, user_id=user.id, page=page, page_size=page_size)
+
+
+@router.get("/ratings/series", response_model=RatedSeriesListOut)
+async def list_rated_series(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=50),
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db),
+) -> RatedSeriesListOut:
+    return await tv_service.list_rated_series(session, user_id=user.id, page=page, page_size=page_size)
+
+
+@router.get("/watchlist/movies", response_model=MovieListOut)
+async def list_watchlist_movies(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=50),
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db),
+) -> MovieListOut:
+    return await movie_service.list_watchlist_movies(
+        session, user_id=user.id, page=page, page_size=page_size
+    )
+
+
+@router.get("/watchlist/series", response_model=SeriesListOut)
+async def list_watchlist_series(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=50),
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db),
+) -> SeriesListOut:
+    return await tv_service.list_watchlist_series(
+        session, user_id=user.id, page=page, page_size=page_size
+    )
@@ -8,10 +8,12 @@ from fastapi import APIRouter, Depends, HTTPException, Query, status
 from redis.asyncio import Redis
 from sqlalchemy.ext.asyncio import AsyncSession

-from app.api.deps import cached_response, not_found
+from app.api.deps import cached_response, get_current_user, 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.models.user import User
+from app.schemas.account import RatingIn, RatingOut
 from app.schemas.movie import (
    MovieCreditsOut,
    MovieDetailOut,
@@ -155,3 +157,52 @@ async def get_movie_watch_providers(
        return await movie_service.get_movie_watch_providers(session, aurora_id)
    except movie_service.MovieNotFoundError as exc:
        raise not_found("movie", aurora_id) from exc
+
+
+@router.put("/{aurora_id}/rating", response_model=RatingOut)
+async def rate_movie(
+    aurora_id: str,
+    body: RatingIn,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db),
+) -> RatingOut:
+    try:
+        return await movie_service.rate_movie(session, aurora_id, user_id=user.id, value=body.value)
+    except movie_service.MovieNotFoundError as exc:
+        raise not_found("movie", aurora_id) from exc
+
+
+@router.delete("/{aurora_id}/rating", status_code=status.HTTP_204_NO_CONTENT)
+async def unrate_movie(
+    aurora_id: str,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db),
+) -> None:
+    try:
+        await movie_service.unrate_movie(session, aurora_id, user_id=user.id)
+    except movie_service.MovieNotFoundError as exc:
+        raise not_found("movie", aurora_id) from exc
+
+
+@router.post("/{aurora_id}/watchlist", status_code=status.HTTP_204_NO_CONTENT)
+async def add_movie_to_watchlist(
+    aurora_id: str,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db),
+) -> None:
+    try:
+        await movie_service.add_movie_to_watchlist(session, aurora_id, user_id=user.id)
+    except movie_service.MovieNotFoundError as exc:
+        raise not_found("movie", aurora_id) from exc
+
+
+@router.delete("/{aurora_id}/watchlist", status_code=status.HTTP_204_NO_CONTENT)
+async def remove_movie_from_watchlist(
+    aurora_id: str,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db),
+) -> None:
+    try:
+        await movie_service.remove_movie_from_watchlist(session, aurora_id, user_id=user.id)
+    except movie_service.MovieNotFoundError as exc:
+        raise not_found("movie", aurora_id) from exc
@@ -8,10 +8,12 @@ from fastapi import APIRouter, Depends, HTTPException, Query, status
 from redis.asyncio import Redis
 from sqlalchemy.ext.asyncio import AsyncSession

-from app.api.deps import cached_response, not_found
+from app.api.deps import cached_response, get_current_user, 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.models.user import User
+from app.schemas.account import RatingIn, RatingOut
 from app.schemas.tv import (
    SeriesCreditsOut,
    SeriesDetailOut,
@@ -135,3 +137,52 @@ async def get_series_watch_providers(
        return await tv_service.get_series_watch_providers(session, aurora_id)
    except tv_service.SeriesNotFoundError as exc:
        raise not_found("series", aurora_id) from exc
+
+
+@router.put("/{aurora_id}/rating", response_model=RatingOut)
+async def rate_series(
+    aurora_id: str,
+    body: RatingIn,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db),
+) -> RatingOut:
+    try:
+        return await tv_service.rate_series(session, aurora_id, user_id=user.id, value=body.value)
+    except tv_service.SeriesNotFoundError as exc:
+        raise not_found("series", aurora_id) from exc
+
+
+@router.delete("/{aurora_id}/rating", status_code=status.HTTP_204_NO_CONTENT)
+async def unrate_series(
+    aurora_id: str,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db),
+) -> None:
+    try:
+        await tv_service.unrate_series(session, aurora_id, user_id=user.id)
+    except tv_service.SeriesNotFoundError as exc:
+        raise not_found("series", aurora_id) from exc
+
+
+@router.post("/{aurora_id}/watchlist", status_code=status.HTTP_204_NO_CONTENT)
+async def add_series_to_watchlist(
+    aurora_id: str,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db),
+) -> None:
+    try:
+        await tv_service.add_series_to_watchlist(session, aurora_id, user_id=user.id)
+    except tv_service.SeriesNotFoundError as exc:
+        raise not_found("series", aurora_id) from exc
+
+
+@router.delete("/{aurora_id}/watchlist", status_code=status.HTTP_204_NO_CONTENT)
+async def remove_series_from_watchlist(
+    aurora_id: str,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db),
+) -> None:
+    try:
+        await tv_service.remove_series_from_watchlist(session, aurora_id, user_id=user.id)
+    except tv_service.SeriesNotFoundError as exc:
+        raise not_found("series", aurora_id) from exc
@@ -52,6 +52,8 @@ ENTITY_PREFIXES: dict[str, str] = {
    "release": "rel",
    "watch_provider": "watch_provider",
    "user": "user",
+    "rating": "rating",
+    "watchlist_entry": "watchlist",
 }


@@ -22,6 +22,7 @@ from prometheus_client import CONTENT_TYPE_LATEST, Counter, Histogram, generate_
 from starlette.exceptions import HTTPException as StarletteHTTPException

 from app.api.v1 import (
+    account,
    admin,
    auth,
    collections,
@@ -183,6 +184,7 @@ API_V1_PREFIX = "/api/v1"
 app.include_router(health.router, prefix=API_V1_PREFIX)
 app.include_router(search.router, prefix=API_V1_PREFIX)
 app.include_router(auth.router, prefix=API_V1_PREFIX)
+app.include_router(account.router, prefix=API_V1_PREFIX)
 app.include_router(movies.router, prefix=API_V1_PREFIX)
 app.include_router(series.router, prefix=API_V1_PREFIX)
 app.include_router(seasons.router, prefix=API_V1_PREFIX)
@@ -24,6 +24,7 @@ from app.models.movie import (
 )
 from app.models.person import Person
 from app.models.provider import IngestionJob, Provider, ProviderRecord
+from app.models.rating import Rating
 from app.models.trending import TrendingEntry
 from app.models.tv import (
    Episode,
@@ -36,6 +37,7 @@ from app.models.tv import (
 from app.models.user import User
 from app.models.video import Video
 from app.models.watch_provider import WatchProvider, WatchProviderOffering
+from app.models.watchlist import WatchlistEntry

 __all__ = [
    "Base",
@@ -79,4 +81,6 @@ __all__ = [
    "WatchProviderOffering",
    "TrendingEntry",
    "User",
+    "Rating",
+    "WatchlistEntry",
 ]
@@ -0,0 +1,34 @@
+"""User ratings -- section 17, additive (accounts/ratings/watchlist).
+
+Polymorphic across movie/series, same shape as WatchProviderOffering and
+TrendingEntry: `entity_type` + `entity_id` rather than a separate ratings
+table per entity type."""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import Float, ForeignKey, Index, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
+
+
+class Rating(Base, UUIDPrimaryKeyMixin, TimestampMixin):
+    __tablename__ = "ratings"
+    __table_args__ = (
+        UniqueConstraint("user_id", "entity_type", "entity_id"),
+        Index("ix_ratings_entity", "entity_type", "entity_id"),
+    )
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    entity_type: Mapped[str] = mapped_column(String(30), nullable=False)
+    entity_id: Mapped[uuid.UUID] = mapped_column(nullable=False)
+    # 0.5-10.0 in 0.5 steps, same scale as TMDb's own user ratings -- see
+    # app/schemas/account.py:RatingIn for the enforced bounds.
+    value: Mapped[float] = mapped_column(Float, nullable=False)
+
+
+__all__ = ["Rating"]
@@ -0,0 +1,30 @@
+"""User watchlists -- section 17, additive (accounts/ratings/watchlist).
+
+Polymorphic across movie/series, same shape as Rating -- no value beyond
+membership, so no extra columns beyond the timestamps."""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import ForeignKey, Index, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
+
+
+class WatchlistEntry(Base, UUIDPrimaryKeyMixin, TimestampMixin):
+    __tablename__ = "watchlist_entries"
+    __table_args__ = (
+        UniqueConstraint("user_id", "entity_type", "entity_id"),
+        Index("ix_watchlist_entries_user", "user_id", "entity_type"),
+    )
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    entity_type: Mapped[str] = mapped_column(String(30), nullable=False)
+    entity_id: Mapped[uuid.UUID] = mapped_column(nullable=False)
+
+
+__all__ = ["WatchlistEntry"]
@@ -0,0 +1,66 @@
+"""Data access for Rating."""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import delete, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.rating import Rating
+
+
+async def get_rating(
+    session: AsyncSession, *, user_id: uuid.UUID, entity_type: str, entity_id: uuid.UUID
+) -> Rating | None:
+    stmt = select(Rating).where(
+        Rating.user_id == user_id, Rating.entity_type == entity_type, Rating.entity_id == entity_id
+    )
+    result = await session.execute(stmt)
+    return result.scalar_one_or_none()
+
+
+async def upsert_rating(
+    session: AsyncSession, *, user_id: uuid.UUID, entity_type: str, entity_id: uuid.UUID, value: float
+) -> Rating:
+    rating = await get_rating(session, user_id=user_id, entity_type=entity_type, entity_id=entity_id)
+    if rating is not None:
+        rating.value = value
+        await session.flush()
+        return rating
+
+    rating = Rating(user_id=user_id, entity_type=entity_type, entity_id=entity_id, value=value)
+    session.add(rating)
+    await session.flush()
+    return rating
+
+
+async def delete_rating(
+    session: AsyncSession, *, user_id: uuid.UUID, entity_type: str, entity_id: uuid.UUID
+) -> None:
+    await session.execute(
+        delete(Rating).where(
+            Rating.user_id == user_id, Rating.entity_type == entity_type, Rating.entity_id == entity_id
+        )
+    )
+
+
+async def list_rated(
+    session: AsyncSession, *, user_id: uuid.UUID, entity_type: str, limit: int, offset: int
+) -> tuple[list[Rating], int]:
+    """Rated entities for a user, newest-rated first, paginated."""
+
+    total = await session.scalar(
+        select(func.count())
+        .select_from(Rating)
+        .where(Rating.user_id == user_id, Rating.entity_type == entity_type)
+    )
+    stmt = (
+        select(Rating)
+        .where(Rating.user_id == user_id, Rating.entity_type == entity_type)
+        .order_by(Rating.created_at.desc())
+        .limit(limit)
+        .offset(offset)
+    )
+    result = await session.execute(stmt)
+    return list(result.scalars().all()), total or 0
@@ -0,0 +1,71 @@
+"""Data access for WatchlistEntry."""
+
+from __future__ import annotations
+
+import uuid
+
+from sqlalchemy import delete, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.watchlist import WatchlistEntry
+
+
+async def get_entry(
+    session: AsyncSession, *, user_id: uuid.UUID, entity_type: str, entity_id: uuid.UUID
+) -> WatchlistEntry | None:
+    stmt = select(WatchlistEntry).where(
+        WatchlistEntry.user_id == user_id,
+        WatchlistEntry.entity_type == entity_type,
+        WatchlistEntry.entity_id == entity_id,
+    )
+    result = await session.execute(stmt)
+    return result.scalar_one_or_none()
+
+
+async def add_entry(
+    session: AsyncSession, *, user_id: uuid.UUID, entity_type: str, entity_id: uuid.UUID
+) -> WatchlistEntry:
+    """Idempotent: adding an already-watchlisted entity just returns the
+    existing row rather than raising on the unique constraint."""
+
+    entry = await get_entry(session, user_id=user_id, entity_type=entity_type, entity_id=entity_id)
+    if entry is not None:
+        return entry
+
+    entry = WatchlistEntry(user_id=user_id, entity_type=entity_type, entity_id=entity_id)
+    session.add(entry)
+    await session.flush()
+    return entry
+
+
+async def remove_entry(
+    session: AsyncSession, *, user_id: uuid.UUID, entity_type: str, entity_id: uuid.UUID
+) -> None:
+    await session.execute(
+        delete(WatchlistEntry).where(
+            WatchlistEntry.user_id == user_id,
+            WatchlistEntry.entity_type == entity_type,
+            WatchlistEntry.entity_id == entity_id,
+        )
+    )
+
+
+async def list_entries(
+    session: AsyncSession, *, user_id: uuid.UUID, entity_type: str, limit: int, offset: int
+) -> tuple[list[WatchlistEntry], int]:
+    """Watchlisted entities for a user, newest-added first, paginated."""
+
+    total = await session.scalar(
+        select(func.count())
+        .select_from(WatchlistEntry)
+        .where(WatchlistEntry.user_id == user_id, WatchlistEntry.entity_type == entity_type)
+    )
+    stmt = (
+        select(WatchlistEntry)
+        .where(WatchlistEntry.user_id == user_id, WatchlistEntry.entity_type == entity_type)
+        .order_by(WatchlistEntry.created_at.desc())
+        .limit(limit)
+        .offset(offset)
+    )
+    result = await session.execute(stmt)
+    return list(result.scalars().all()), total or 0
@@ -0,0 +1,21 @@
+"""Request/response schemas for the authenticated user's own ratings and
+watchlist (section 17, additive)."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class RatingIn(BaseModel):
+    # 0.5-10.0 in practice (TMDb's own scale), enforced as a continuous
+    # range rather than an enum of 0.5 steps -- not worth the extra
+    # validation for a value nothing downstream treats as discrete.
+    value: float = Field(ge=0.5, le=10.0)
+
+
+class RatingOut(BaseModel):
+    value: float
+    created_at: datetime
+    updated_at: datetime
@@ -106,3 +106,15 @@ class MovieListOut(BaseModel):
    total_results: int
    total_pages: int
    results: list[MovieSummaryOut] = []
+
+
+class RatedMovieOut(MovieSummaryOut):
+    rating: float
+
+
+class RatedMovieListOut(BaseModel):
+    page: int
+    page_size: int
+    total_results: int
+    total_pages: int
+    results: list[RatedMovieOut] = []
@@ -115,6 +115,18 @@ class SeriesListOut(BaseModel):
    results: list[SeriesSummaryOut] = []


+class RatedSeriesOut(SeriesSummaryOut):
+    rating: float
+
+
+class RatedSeriesListOut(BaseModel):
+    page: int
+    page_size: int
+    total_results: int
+    total_pages: int
+    results: list[RatedSeriesOut] = []
+
+
 class EpisodeBriefOut(BaseModel):
    id: str
    episode_number: int
@@ -9,7 +9,14 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from app.core.ids import aurora_id, parse_aurora_id
 from app.models.enums import ArtworkType, MovieStatus
 from app.models.movie import Movie
-from app.repositories import movie_repository, polymorphic, trending_repository
+from app.repositories import (
+    movie_repository,
+    polymorphic,
+    rating_repository,
+    trending_repository,
+    watchlist_repository,
+)
+from app.schemas.account import RatingOut
 from app.schemas.common import CollectionBriefOut, CompanyBriefOut, GenreOut, KeywordOut
 from app.schemas.movie import (
    MovieCreditsOut,
@@ -20,6 +27,8 @@ from app.schemas.movie import (
    MovieSummaryOut,
    MovieVideosOut,
    MovieWatchProvidersOut,
+    RatedMovieListOut,
+    RatedMovieOut,
 )
 from app.services.common import (
    build_watch_providers_out,
@@ -209,6 +218,79 @@ async def build_movie_summaries(
    return out


+async def rate_movie(
+    session: AsyncSession, movie_aurora_id: str, *, user_id: uuid.UUID, value: float
+) -> RatingOut:
+    movie_id = await _resolve_movie_id(movie_aurora_id)
+    if await movie_repository.get_movie_by_id(session, movie_id) is None:
+        raise MovieNotFoundError(movie_aurora_id)
+
+    rating = await rating_repository.upsert_rating(
+        session, user_id=user_id, entity_type="movie", entity_id=movie_id, value=value
+    )
+    return RatingOut(value=rating.value, created_at=rating.created_at, updated_at=rating.updated_at)
+
+
+async def unrate_movie(session: AsyncSession, movie_aurora_id: str, *, user_id: uuid.UUID) -> None:
+    movie_id = await _resolve_movie_id(movie_aurora_id)
+    if await movie_repository.get_movie_by_id(session, movie_id) is None:
+        raise MovieNotFoundError(movie_aurora_id)
+
+    await rating_repository.delete_rating(session, user_id=user_id, entity_type="movie", entity_id=movie_id)
+
+
+async def list_rated_movies(
+    session: AsyncSession, *, user_id: uuid.UUID, page: int, page_size: int
+) -> RatedMovieListOut:
+    ratings, total = await rating_repository.list_rated(
+        session, user_id=user_id, entity_type="movie", limit=page_size, offset=(page - 1) * page_size
+    )
+    results: list[RatedMovieOut] = []
+    for rating in ratings:
+        summary = await build_movie_summary(session, rating.entity_id)
+        if summary is not None:
+            results.append(RatedMovieOut(**summary.model_dump(), rating=rating.value))
+    total_pages = (total + page_size - 1) // page_size if total else 0
+
+    return RatedMovieListOut(
+        page=page, page_size=page_size, total_results=total, total_pages=total_pages, results=results
+    )
+
+
+async def add_movie_to_watchlist(
+    session: AsyncSession, movie_aurora_id: str, *, user_id: uuid.UUID
+) -> None:
+    movie_id = await _resolve_movie_id(movie_aurora_id)
+    if await movie_repository.get_movie_by_id(session, movie_id) is None:
+        raise MovieNotFoundError(movie_aurora_id)
+
+    await watchlist_repository.add_entry(session, user_id=user_id, entity_type="movie", entity_id=movie_id)
+
+
+async def remove_movie_from_watchlist(
+    session: AsyncSession, movie_aurora_id: str, *, user_id: uuid.UUID
+) -> None:
+    movie_id = await _resolve_movie_id(movie_aurora_id)
+    if await movie_repository.get_movie_by_id(session, movie_id) is None:
+        raise MovieNotFoundError(movie_aurora_id)
+
+    await watchlist_repository.remove_entry(session, user_id=user_id, entity_type="movie", entity_id=movie_id)
+
+
+async def list_watchlist_movies(
+    session: AsyncSession, *, user_id: uuid.UUID, page: int, page_size: int
+) -> MovieListOut:
+    entries, total = await watchlist_repository.list_entries(
+        session, user_id=user_id, entity_type="movie", limit=page_size, offset=(page - 1) * page_size
+    )
+    results = await build_movie_summaries(session, [entry.entity_id for entry in entries])
+    total_pages = (total + page_size - 1) // page_size if total else 0
+
+    return MovieListOut(
+        page=page, page_size=page_size, total_results=total, total_pages=total_pages, results=results
+    )
+
+
 async def list_now_playing(
    session: AsyncSession, *, region: str, page: int, page_size: int
 ) -> MovieListOut:
@@ -10,11 +10,20 @@ from app.core.ids import aurora_id, parse_aurora_id
 from app.models.credit import Credit
 from app.models.enums import ArtworkType, CompanyType, SeriesStatus
 from app.models.tv import Series
-from app.repositories import polymorphic, trending_repository, tv_repository
+from app.repositories import (
+    polymorphic,
+    rating_repository,
+    trending_repository,
+    tv_repository,
+    watchlist_repository,
+)
+from app.schemas.account import RatingOut
 from app.schemas.common import CastCreditOut, CompanyBriefOut, CrewCreditOut, GenreOut, KeywordOut
 from app.schemas.tv import (
    EpisodeBriefOut,
    EpisodeDetailOut,
+    RatedSeriesListOut,
+    RatedSeriesOut,
    SeasonBriefOut,
    SeasonDetailOut,
    SeriesCreditsOut,
@@ -316,6 +325,81 @@ async def build_series_summaries(
    return out


+async def rate_series(
+    session: AsyncSession, series_aurora_id: str, *, user_id: uuid.UUID, value: float
+) -> RatingOut:
+    series_id = _resolve_id(series_aurora_id, "series", SeriesNotFoundError)
+    if await tv_repository.get_series_by_id(session, series_id) is None:
+        raise SeriesNotFoundError(series_aurora_id)
+
+    rating = await rating_repository.upsert_rating(
+        session, user_id=user_id, entity_type="series", entity_id=series_id, value=value
+    )
+    return RatingOut(value=rating.value, created_at=rating.created_at, updated_at=rating.updated_at)
+
+
+async def unrate_series(session: AsyncSession, series_aurora_id: str, *, user_id: uuid.UUID) -> None:
+    series_id = _resolve_id(series_aurora_id, "series", SeriesNotFoundError)
+    if await tv_repository.get_series_by_id(session, series_id) is None:
+        raise SeriesNotFoundError(series_aurora_id)
+
+    await rating_repository.delete_rating(session, user_id=user_id, entity_type="series", entity_id=series_id)
+
+
+async def list_rated_series(
+    session: AsyncSession, *, user_id: uuid.UUID, page: int, page_size: int
+) -> RatedSeriesListOut:
+    ratings, total = await rating_repository.list_rated(
+        session, user_id=user_id, entity_type="series", limit=page_size, offset=(page - 1) * page_size
+    )
+    results: list[RatedSeriesOut] = []
+    for rating in ratings:
+        summary = await build_series_summary(session, rating.entity_id)
+        if summary is not None:
+            results.append(RatedSeriesOut(**summary.model_dump(), rating=rating.value))
+    total_pages = (total + page_size - 1) // page_size if total else 0
+
+    return RatedSeriesListOut(
+        page=page, page_size=page_size, total_results=total, total_pages=total_pages, results=results
+    )
+
+
+async def add_series_to_watchlist(
+    session: AsyncSession, series_aurora_id: str, *, user_id: uuid.UUID
+) -> None:
+    series_id = _resolve_id(series_aurora_id, "series", SeriesNotFoundError)
+    if await tv_repository.get_series_by_id(session, series_id) is None:
+        raise SeriesNotFoundError(series_aurora_id)
+
+    await watchlist_repository.add_entry(session, user_id=user_id, entity_type="series", entity_id=series_id)
+
+
+async def remove_series_from_watchlist(
+    session: AsyncSession, series_aurora_id: str, *, user_id: uuid.UUID
+) -> None:
+    series_id = _resolve_id(series_aurora_id, "series", SeriesNotFoundError)
+    if await tv_repository.get_series_by_id(session, series_id) is None:
+        raise SeriesNotFoundError(series_aurora_id)
+
+    await watchlist_repository.remove_entry(
+        session, user_id=user_id, entity_type="series", entity_id=series_id
+    )
+
+
+async def list_watchlist_series(
+    session: AsyncSession, *, user_id: uuid.UUID, page: int, page_size: int
+) -> SeriesListOut:
+    entries, total = await watchlist_repository.list_entries(
+        session, user_id=user_id, entity_type="series", limit=page_size, offset=(page - 1) * page_size
+    )
+    results = await build_series_summaries(session, [entry.entity_id for entry in entries])
+    total_pages = (total + page_size - 1) // page_size if total else 0
+
+    return SeriesListOut(
+        page=page, page_size=page_size, total_results=total, total_pages=total_pages, results=results
+    )
+
+
 _TRENDING_WINDOWS = ("day", "week")