fix(specials): handle season 0 in Jellyfin scrobbles, Trakt import, and Next Up (#132)

Author: ellite

backend/routers/history.py

@@ -568,6 +568,12 @@ def _group_last_watched(
     last_per_show: dict[int, tuple[int, int]] = {}
     last_watched_at: dict[int, datetime] = {}
     for show_id, season, episode, watched_at in rows:
+        if season is None or episode is None:
+            # Faulty history entry with an unknown season/episode (e.g. a
+            # pre-fix scrobble that lost season 0) - skip it rather than let
+            # it corrupt this show's position or crash the fallback lookup
+            # below, which assumes season/episode are always ints.
+            continue
         if show_id not in last_per_show:
             last_per_show[show_id] = (season, episode)
         if watched_at and (show_id not in last_watched_at or watched_at > last_watched_at[show_id]):

backend/routers/trakt.py

@@ -612,7 +612,7 @@ async def process_show(show_tmdb_id: int, entries: list[dict]):
                     ep_data = entry.get("episode", {})
                     season_num = ep_data.get("season")
                     ep_num = ep_data.get("number")
-                    if season_num is None or season_num == 0 or ep_num is None:
+                    if season_num is None or ep_num is None:
                         stats["skipped"] += 1
                         continue
                     try:

backend/routers/webhooks.py

@@ -521,9 +521,10 @@ def parse_jellyfin_payload(payload: dict) -> dict | None:
     position_ticks = payload.get("PlaybackPositionTicks") or payload.get("PositionTicks") or 0
     runtime_ticks = payload.get("RunTimeTicks") or 0
 
-    # SeasonNumber/EpisodeNumber are 1-indexed in the plugin template; 0 means absent
-    season_num = payload.get("SeasonNumber") or None
-    episode_num = payload.get("EpisodeNumber") or None
+    # SeasonNumber/EpisodeNumber are absent from the payload for movies;
+    # 0 is a valid season number (specials), so don't coerce it away.
+    season_num = payload.get("SeasonNumber")
+    episode_num = payload.get("EpisodeNumber")
 
     return {
         "notification_type": notification_type,

backend/tests/test_next_up.py

@@ -68,6 +68,23 @@ def test_keeps_most_recent_watched_at_across_rows(self):
         last_per_show, last_watched_at = _group_last_watched(rows)
         self.assertEqual(last_watched_at[1], newer)
 
+    def test_null_season_row_is_skipped_not_used_as_last_watched(self):
+        # Regression for #132: a faulty history entry with a NULL season (e.g.
+        # a pre-fix Season-0 scrobble) must not become a show's "furthest
+        # watched" position — get_next_up would later pass that None straight
+        # into an int comparison and crash the whole endpoint.
+        rows = [
+            (1, None, 3, datetime(2026, 1, 2, tzinfo=timezone.utc)),
+            (1, 1, 5, datetime(2026, 1, 1, tzinfo=timezone.utc)),
+        ]
+        last_per_show, last_watched_at = _group_last_watched(rows)
+        self.assertEqual(last_per_show[1], (1, 5))
+
+    def test_show_with_only_null_season_rows_has_no_entry(self):
+        rows = [(1, None, 1, None), (1, None, 2, None)]
+        last_per_show, last_watched_at = _group_last_watched(rows)
+        self.assertNotIn(1, last_per_show)
+
 
 class HasAiredTests(unittest.TestCase):
     """Regression tests for #104: Next Up must not suggest an episode before

backend/tests/test_webhooks.py

@@ -66,6 +66,37 @@ async def test_second_completed_event_for_same_media_within_window_is_skipped(se
         self.assertEqual(len(db.added), 0)
 
 
+class ParseJellyfinFlatPayloadSeasonZeroTests(unittest.TestCase):
+    """Regression test for #132: a Season 0 (specials) episode has
+    SeasonNumber: 0 in the flat webhook payload, which a falsy check like
+    `payload.get("SeasonNumber") or None` incorrectly coerces to None."""
+
+    def test_season_zero_is_preserved_not_coerced_to_none(self):
+        payload = {
+            "NotificationType": "PlaybackStart",
+            "ItemType": "Episode",
+            "ItemId": "abc123",
+            "Name": "Behind the Scenes",
+            "SeriesName": "Some Show",
+            "SeasonNumber": 0,
+            "EpisodeNumber": 1,
+            "Provider_tmdb": "999",
+        }
+        data = parse_jellyfin_payload(payload)
+        self.assertIsNotNone(data)
+        self.assertEqual(data["season_number"], 0)
+
+    def test_movie_has_no_season_number(self):
+        payload = {
+            "NotificationType": "PlaybackStart",
+            "ItemType": "Movie",
+            "ItemId": "xyz",
+            "Name": "A Movie",
+        }
+        data = parse_jellyfin_payload(payload)
+        self.assertIsNone(data["season_number"])
+
+
 class ParseJellyfinUserDataSavedPayloadTests(unittest.TestCase):
     """Regression test for #69: Jellyfin's official Webhook plugin has no
     "MarkPlayed" event — manually toggling watched/unwatched raises

frontend/src/components/HistoryCard.astro

@@ -21,10 +21,11 @@ const year = media.release_date?.slice(0, 4);
 const rawPoster = isEpisode ? (media.show_poster_path || media.poster_path) : media.poster_path;
 const posterPath = tmdbImageUrl(rawPoster, "w500");
 
+const hasSeasonEpisode = media.season_number != null && media.episode_number != null;
 const href = isEpisode
-  ? (!media.tvdb_sourced && media.show_tmdb_id)
+  ? (!media.tvdb_sourced && media.show_tmdb_id && hasSeasonEpisode)
     ? `/show/${media.show_tmdb_id}/season/${media.season_number}/${media.episode_number}`
-    : media.show_tvdb_id
+    : media.show_tvdb_id && hasSeasonEpisode
       ? `/show/tvdb/${media.show_tvdb_id}/season/${media.season_number}/${media.episode_number}`
       : `/media/episode/${media.tmdb_id}`
   : `/media/movie/${media.tmdb_id}`;