Add optional episode score param to watch/scrobble APIs

- MediaEpisodeWatchView.post and ScrobbleView.post (action=stop, episode)
  now accept an optional 0-10 `score`, so a player can set the user's
  episode rating in the same call that marks it watched
- Extract validate_episode_score/get_tracked_season/apply_episode_score
  into api/helpers.py, shared with the existing episode-score PATCH view
- Seasons-page rating popup gains a decimal "exact rating" input next to
  the whole-star picker (episode ratings only)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: dannyvfilms

src/api/contracts/openapi.yaml

@@ -1560,7 +1560,12 @@ paths:
   /api/v1/media/{media_type}/{source}/{media_id}/{season_number}/episodes/{episode_number}/watch/:
     post:
       operationId: api_v1_media_episodes_watch_create
-      description: Record a watch for the episode.
+      description: |-
+        Record a watch for the episode.
+
+        Optional body field `score` (0-10, or null to clear) sets the
+        episode's rating in the same call, mirroring
+        MediaEpisodeScoreView.patch.
       parameters:
       - in: path
         name: episode_number

src/api/fork_views_metadata.py

@@ -1,28 +1,31 @@
 # FORK: metadata-management and score endpoints mirroring web-only actions
 # (metadata_sync_views, score_views). URL wiring lives in fork_urls.py.
 import logging
-from decimal import Decimal, InvalidOperation
 from http import HTTPStatus as HTTP  # noqa: N814
 
 from django.apps import apps
 from drf_spectacular.utils import extend_schema
 from rest_framework import views as drf_views
 from rest_framework.response import Response
 
-from app import custom_metadata, history_cache
+from app import custom_metadata
 from app import metadata_sync_views as web_metadata_views
 from app.models import (
-    Episode,
     Item,
     MediaTypes,
     MetadataProviderPreference,
-    Season,
     Sources,
 )
 from app.services import metadata_resolution
 
 from .contract_serializers import DetailErrorSerializer
-from .helpers import check_valid_type, resolve_episode_coordinate_for_request
+from .helpers import (
+    apply_episode_score,
+    check_valid_type,
+    get_tracked_season,
+    resolve_episode_coordinate_for_request,
+    validate_episode_score,
+)
 from .schema import MEDIA_TYPE_PARAM, MEDIA_TYPE_TV_ONLY_PARAM
 
 logger = logging.getLogger(__name__)
@@ -255,17 +258,7 @@ def patch(
         if coordinate_error:
             return coordinate_error
 
-        season = (
-            Season.objects.filter(
-                item__media_id=media_id,
-                item__source=source,
-                item__season_number=season_number,
-                item__episode_number=None,
-                user=request.user,
-            )
-            .order_by("id")
-            .first()
-        )
+        season = get_tracked_season(request.user, media_id, source, season_number)
         if season is None:
             return Response(
                 {"detail": "Season not found or not tracked."},
@@ -277,49 +270,16 @@ def patch(
                 {"detail": "'score' is required (number or null)."},
                 status=HTTP.BAD_REQUEST,
             )
-        raw_score = request.data.get("score")
-        score = None
-        if raw_score is not None:
-            try:
-                score = Decimal(str(raw_score))
-            except (InvalidOperation, TypeError, ValueError):
-                return Response(
-                    {"detail": "Invalid score."},
-                    status=HTTP.BAD_REQUEST,
-                )
-            if not (Decimal(0) <= score <= Decimal(10)):
-                return Response(
-                    {"detail": "Score must be between 0 and 10."},
-                    status=HTTP.BAD_REQUEST,
-                )
+        score, error = validate_episode_score(request.data.get("score"))
+        if error:
+            return error
 
-        episodes = Episode.objects.filter(
-            related_season=season,
-            item__episode_number=int(episode_number),
-        )
-        if not episodes.exists():
+        if not apply_episode_score(season, episode_number, score):
             return Response(
                 {"detail": "Episode not tracked."},
                 status=HTTP.NOT_FOUND,
             )
 
-        episodes.update(score=score)
-
-        # episodes.update() runs raw SQL and skips post_save, so invalidate
-        # the affected history days like the web view does.
-        day_keys = [
-            history_cache.history_day_key(end_date)
-            for end_date in episodes.values_list("end_date", flat=True)
-        ]
-        day_keys = [day_key for day_key in day_keys if day_key]
-        if day_keys:
-            history_cache.invalidate_history_days(
-                request.user.id,
-                day_keys=day_keys,
-                logging_styles=("sessions", "repeats"),
-                reason="episode_score_change",
-            )
-
         return Response(
             {"score": str(score) if score is not None else None},
             status=HTTP.OK,

src/api/fork_views_scrobble.py

@@ -17,7 +17,12 @@
 from integrations.webhooks.generic_scrobble import GenericScrobbleProcessor, is_played
 
 from . import fork_views_playback
-from .helpers import try_parse_datetime_input
+from .helpers import (
+    apply_episode_score,
+    get_tracked_season,
+    try_parse_datetime_input,
+    validate_episode_score,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -76,6 +81,11 @@ def _scrobble_request_error(data):
                 status=HTTP.BAD_REQUEST,
             )
 
+    if "score" in data:
+        _, score_error = validate_episode_score(data.get("score"))
+        if score_error:
+            return score_error
+
     return None
 
 
@@ -183,6 +193,13 @@ class ScrobbleView(drf_views.APIView):
                         "nullable": True,
                         "description": "Only used by 'stop'. Defaults to now.",
                     },
+                    "score": {
+                        "type": "number",
+                        "nullable": True,
+                        "description": "Only used by 'stop', for media_type "
+                        "'episode'. Sets the user's rating (0-10) on the "
+                        "episode.",
+                    },
                 },
             },
         },
@@ -256,6 +273,9 @@ def _execute():
                 completed=is_played(payload),
             )
 
+            if "score" in request.data and media_type == MediaTypes.EPISODE.value:
+                self._apply_episode_score(request.user, payload, request.data["score"])
+
             return Response({"detail": "accepted"}, status=HTTP.OK)
 
         if client_event_id:
@@ -271,6 +291,31 @@ def _execute():
         return _execute()
 
 
+    def _apply_episode_score(self, user, payload, raw_score):
+        """Set the episode's rating; failures are logged, never raised.
+
+        Validity was already checked in `_scrobble_request_error`; this just
+        resolves the already-persisted episode and applies it.
+        """
+        score, _ = validate_episode_score(raw_score)
+        try:
+            item = fork_views_playback.resolve_video_item(
+                user,
+                payload["media_type"],
+                payload["ids"],
+                payload.get("season_number"),
+                payload.get("episode_number"),
+                create=False,
+            )
+            if item is None:
+                return
+            season = get_tracked_season(user, item.media_id, item.source, item.season_number)
+            if season is None:
+                return
+            apply_episode_score(season, item.episode_number, score)
+        except Exception:
+            logger.warning("Scrobble episode-score update failed", exc_info=True)
+
     def _store_playback_progress(self, user, payload, *, completed):
         """Persist the durable resume position; failures are never raised.
 

src/api/fork_views_tracking.py

@@ -15,21 +15,24 @@
 from app.fork_services_episode import drop_episode, resolve_or_create_season
 from app.fork_services_movie import resolve_or_create_movie
 from app.history_cache_utils import normalize_history_media_type_tokens
-from app.models import Episode, ItemTag, MediaTypes, Movie, Season, Tag
+from app.models import Episode, ItemTag, MediaTypes, Movie, Tag
 from app.services import metadata_resolution
 from app.tasks import bulk_episode_plays_task
 from app.templatetags.app_tags import media_url
 
 from .contract_serializers import DetailErrorSerializer
 from .helpers import (
     MEDIA_TYPE_MODEL_MAP,
+    apply_episode_score,
     check_source_type,
     check_valid_type,
+    get_tracked_season,
     paginate_data,
     parse_limit_offset,
     resolve_episode_coordinate_for_request,
     resolve_item_queryset,
     try_parse_datetime_input,
+    validate_episode_score,
 )
 from .schema import MEDIA_TYPE_PARAM, MEDIA_TYPE_TV_ONLY_PARAM
 from .serializers import HistorySerializer, serialize_data
@@ -52,21 +55,6 @@ def _tv_route_error(media_type, source):
     return None
 
 
-def _get_tracked_season(user, media_id, source, season_number):
-    """Return the user's tracked Season row or None."""
-    return (
-        Season.objects.filter(
-            item__media_id=media_id,
-            item__source=source,
-            item__season_number=season_number,
-            item__episode_number=None,
-            user=user,
-        )
-        .order_by("id")
-        .first()
-    )
-
-
 # /api/v1/media/tv/[source]/[media_id]/[season_number]/episodes/[episode_number]/watch/
 class MediaEpisodeWatchView(drf_views.APIView):
     """Add or remove a watch (play) for an episode.
@@ -89,11 +77,21 @@ def post(
         season_number,
         episode_number,
     ):
-        """Record a watch for the episode."""
+        """Record a watch for the episode.
+
+        Optional body field `score` (0-10, or null to clear) sets the
+        episode's rating in the same call, mirroring
+        MediaEpisodeScoreView.patch.
+        """
         error = _tv_route_error(media_type, source)
         if error:
             return error
 
+        score_provided = "score" in request.data
+        score, score_error = validate_episode_score(request.data.get("score"))
+        if score_error:
+            return score_error
+
         raw_end_date = request.data.get("end_date")
         if raw_end_date in (None, ""):
             end_date = timezone.now()
@@ -140,6 +138,8 @@ def post(
             )
 
         related_season.watch(int(episode_number), end_date)
+        if score_provided:
+            apply_episode_score(related_season, episode_number, score)
         episode = (
             Episode.objects.filter(
                 related_season=related_season,
@@ -194,7 +194,7 @@ def delete(
         if coordinate_error:
             return coordinate_error
 
-        related_season = _get_tracked_season(
+        related_season = get_tracked_season(
             request.user,
             media_id,
             source,

src/api/helpers.py

@@ -1,13 +1,15 @@
 import logging
 from calendar import monthrange
 from datetime import date
+from decimal import Decimal, InvalidOperation
 from http import HTTPStatus as HTTP  # noqa: N814
 
 from django.db.models import Count, OuterRef, Subquery
 from django.utils.dateparse import parse_date
 from django.utils.timezone import localdate
 from rest_framework.response import Response
 
+from app import history_cache
 from app.helpers import parse_completion_datetime
 from app.models import (
     TV,
@@ -843,3 +845,69 @@ def build_game_lengths_summary(payload):
     if "hltb_summary" not in summary and "igdb_summary" not in summary:
         return None
     return summary
+
+
+def get_tracked_season(user, media_id, source, season_number):
+    """Return the user's tracked Season row for a show/season, or None."""
+    return (
+        Season.objects.filter(
+            item__media_id=media_id,
+            item__source=source,
+            item__season_number=season_number,
+            item__episode_number=None,
+            user=user,
+        )
+        .order_by("id")
+        .first()
+    )
+
+
+def validate_episode_score(raw_score):
+    """Parse and range-check a 0-10 episode score.
+
+    Returns (score, None) on success, where score is a Decimal or None
+    (explicit clear); returns (None, error_response) on failure.
+    """
+    if raw_score is None:
+        return None, None
+    try:
+        score = Decimal(str(raw_score))
+    except (InvalidOperation, TypeError, ValueError):
+        return None, Response({"detail": "Invalid score."}, status=HTTP.BAD_REQUEST)
+    if not (Decimal(0) <= score <= Decimal(10)):
+        return None, Response(
+            {"detail": "Score must be between 0 and 10."},
+            status=HTTP.BAD_REQUEST,
+        )
+    return score, None
+
+
+def apply_episode_score(season, episode_number, score):
+    """Set `score` on all plays of a tracked episode within `season`.
+
+    Returns True if the episode was found and updated, False otherwise.
+    Uses queryset.update(), which skips post_save, so the affected
+    history-cache days are invalidated explicitly like the web view does.
+    """
+    episodes = Episode.objects.filter(
+        related_season=season,
+        item__episode_number=int(episode_number),
+    )
+    if not episodes.exists():
+        return False
+
+    episodes.update(score=score)
+
+    day_keys = [
+        history_cache.history_day_key(end_date)
+        for end_date in episodes.values_list("end_date", flat=True)
+    ]
+    day_keys = [day_key for day_key in day_keys if day_key]
+    if day_keys:
+        history_cache.invalidate_history_days(
+            season.user_id,
+            day_keys=day_keys,
+            logging_styles=("sessions", "repeats"),
+            reason="episode_score_change",
+        )
+    return True