Merge pull request #6 from neckaros/t3code/cross-library-episode-history

Author: neckaros

docs/SSE.md

@@ -235,7 +235,7 @@ interface MediasRatingMessage {
 // Watched events (user-specific). IDs include the media type and identity scheme.
 interface Watched {
   type: string;  // MediaType: "movie", "episode", etc.
-  id: string;    // e.g. "movie:imdb/tt1234567" or "episode:redseat/seriesId/1/2"
+  id: string;    // e.g. "movie:imdb/tt1234567" or "episode:imdb/tt0108778/1/2"
   userRef?: string;
   date: number;  // Timestamp when content was watched
   modified: number;
@@ -653,10 +653,11 @@ History IDs include the media type so IDs from different domains cannot collide.
 |---------|--------|---------|
 | Movie with IMDb ID | `movie:imdb/<imdbId>` | `movie:imdb/tt1234567` |
 | Movie without IMDb ID | `movie:redseat/<movieId>` | `movie:redseat/abc123` |
-| Series progress parent | `series:redseat/<seriesId>` | `series:redseat/series123` |
-| Episode | `episode:redseat/<seriesId>/<season>/<episode>` | `episode:redseat/series123/1/2` |
+| Series progress parent | `series:imdb/<seriesImdbId>` | `series:imdb/tt0108778` |
+| Episode | `episode:imdb/<seriesImdbId>/<season>/<episode>` | `episode:imdb/tt0108778/1/2` |
+| Episode fallback | `episode:redseat/<seriesId>/<season>/<episode>` | `episode:redseat/series123/1/2` |
 
-Episode IDs deliberately use the immutable local series ID and numeric season/episode tuple. Plugin metadata refreshes therefore cannot change watched state or progress IDs.
+Episode IDs use the series IMDb ID and numeric season/episode tuple so watched state follows the same show across libraries. Series without an IMDb ID temporarily use the RedSeat fallback; if IMDb metadata is added later, the server migrates watched state and progress immediately.
 
 ### REST API Endpoints
 
@@ -752,79 +753,24 @@ function isMatchingUnwatchedEvent(movie: LocalMovie, eventIds: string[]): boolea
 
 ## Offline Sync for Watch History
 
-When clients are offline or disconnected from SSE, they can miss `unwatched` events. The REST API provides a mechanism to sync these missed deletions.
-
-### How It Works
-
-- **`date > 0`**: Item is actively watched (timestamp indicates when it was watched)
-- **`date = 0`**: Item was unwatched/deleted (soft-deleted, kept for sync purposes)
-
-When content is marked as unwatched, instead of being deleted from the database, the `date` field is set to `0` and the `modified` timestamp is updated. This allows clients to fetch all changes (including deletions) via the history API.
+Unwatching content permanently deletes its history row. The server does not retain deletion tombstones.
 
 ### Client Sync Flow
 
 ```typescript
-// 1. Store last sync timestamp locally
-let lastSyncTimestamp = localStorage.getItem('lastHistorySync') || '0';
-
-// 2. Fetch all history changes since last sync, including deleted items
+// Replace local watched state with a complete server snapshot.
 async function syncHistory() {
-  const response = await fetch(
-    `/users/me/history?after=${lastSyncTimestamp}&includeDeleted=true`
-  );
+  const response = await fetch('/users/me/history');
   const items: Watched[] = await response.json();
-
-  for (const item of items) {
-    if (item.date > 0) {
-      // Active watched item - add or update in local state
-      addToLocalWatched(item);
-    } else {
-      // Deleted item (date = 0) - remove from local state
-      removeFromLocalWatched(item.type, item.id);
-    }
-
-    // Track highest modified timestamp for next sync
-    if (item.modified > parseInt(lastSyncTimestamp)) {
-      lastSyncTimestamp = item.modified.toString();
-    }
-  }
-
-  localStorage.setItem('lastHistorySync', lastSyncTimestamp);
+  replaceLocalWatched(items);
 }
-
-// 3. Call on app startup and periodically while online
-syncHistory();
 ```
 
+Connected clients can apply live `watched` and `unwatched` SSE events. After being offline, clients must perform this full reload because incremental history queries cannot report deletions.
+
 ### API Query Parameters
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `after` | number | Only return items modified after this timestamp (milliseconds) |
-| `includeDeleted` | boolean | Include items with `date=0` (unwatched). Default: `false` |
+| `after` | number | Only return watched items modified after this timestamp (milliseconds). This does not report deletions. |
 | `types` | string[] | Filter by content types (e.g., `movie`, `episode`) |
-
-### Example Response with Deleted Items
-
-```json
-[
-  {
-    "type": "movie",
-    "id": "movie:imdb/tt1234567",
-    "userRef": "user123",
-    "date": 1705766400000,
-    "modified": 1705852800000
-  },
-  {
-    "type": "movie",
-    "id": "movie:imdb/tt9876543",
-    "userRef": "user123",
-    "date": 0,
-    "modified": 1705939200000
-  }
-]
-```
-
-In this response:
-- First item: Movie was watched at timestamp `1705766400000`
-- Second item: Movie was unwatched (`date=0`), client should remove it from local state

scripts/remap_trakt_watched.py

@@ -42,9 +42,11 @@ class EpisodeRow:
     trakt: int | None
     tvdb: int | None
 
-    @property
-    def redseat_id(self) -> str:
-        return f"episode:redseat/{self.serie_ref}/{self.season}/{self.number}"
+
+def episode_history_id(series: SeriesRow, episode: EpisodeRow) -> str:
+    imdb = series.imdb.strip() if series.imdb else ""
+    key = f"imdb/{imdb}" if imdb else f"redseat/{series.id}"
+    return f"episode:{key}/{episode.season}/{episode.number}"
 
 
 class TraktClient:
@@ -192,7 +194,7 @@ def build_episode_map(
             fieldnames=[
                 "source",
                 "trakt_episode_id",
-                "redseat_episode_id",
+                "history_episode_id",
                 "serie_ref",
                 "serie_name",
                 "serie_imdb",
@@ -208,22 +210,27 @@ def build_episode_map(
         )
         writer.writeheader()
 
+        series_by_id = {series.id: series for series in series_rows}
         for episode in local_episodes.values():
             if not episode.trakt:
                 continue
+            series = series_by_id.get(episode.serie_ref)
+            if not series:
+                continue
             trakt_key = f"trakt:{episode.trakt}"
-            mapping[trakt_key] = episode.redseat_id
+            history_id = episode_history_id(series, episode)
+            mapping[trakt_key] = history_id
             writer.writerow(
                 {
                     "source": "local_db",
                     "trakt_episode_id": trakt_key,
-                    "redseat_episode_id": episode.redseat_id,
+                    "history_episode_id": history_id,
                     "serie_ref": episode.serie_ref,
-                    "serie_name": "",
-                    "serie_imdb": "",
-                    "serie_tmdb": "",
-                    "serie_tvdb": "",
-                    "serie_trakt": "",
+                    "serie_name": series.name,
+                    "serie_imdb": series.imdb or "",
+                    "serie_tmdb": series.tmdb or "",
+                    "serie_tvdb": series.tvdb or "",
+                    "serie_trakt": series.trakt or "",
                     "season": episode.season,
                     "episode": episode.number,
                     "episode_imdb": episode.imdb or "",
@@ -259,12 +266,13 @@ def build_episode_map(
                         continue
 
                     trakt_key = f"trakt:{trakt_episode_id}"
-                    mapping[trakt_key] = local_episode.redseat_id
+                    history_id = episode_history_id(series, local_episode)
+                    mapping[trakt_key] = history_id
                     writer.writerow(
                         {
                             "source": "trakt_api",
                             "trakt_episode_id": trakt_key,
-                            "redseat_episode_id": local_episode.redseat_id,
+                            "history_episode_id": history_id,
                             "serie_ref": series.id,
                             "serie_name": series.name,
                             "serie_imdb": series.imdb or "",
@@ -351,15 +359,19 @@ def rewrite_history(
         "progress_updated": 0,
         "progress_merged": 0,
         "progress_unresolved": 0,
+        "tombstones_removed": 0,
     }
 
     try:
+        conn.execute("BEGIN IMMEDIATE")
+        stats["tombstones_removed"] = conn.execute(
+            "DELETE FROM Watched WHERE date <= 0"
+        ).rowcount
         rows = list(
             conn.execute(
                 "SELECT type, id, user_ref, date, modified FROM Watched ORDER BY type, user_ref, id"
             )
         )
-        conn.execute("BEGIN IMMEDIATE")
         for row in rows:
             kind = row["type"]
             old_id = row["id"]
@@ -415,7 +427,7 @@ def rewrite_history(
                 stats[updated_key] += 1
             conn.execute(
                 """
-                UPDATE Watched SET date = 0
+                DELETE FROM Watched
                 WHERE type = ? AND id = ? AND user_ref = ?
                 """,
                 (kind, old_id, row["user_ref"]),
@@ -447,7 +459,8 @@ def rewrite_history(
             ).fetchone()
             parent = row["parent"]
             if kind == "episode":
-                parent = f"series:redseat/{new_id.split('/')[1]}"
+                prefix, series_id, _, _ = new_id.split("/")
+                parent = f"{prefix.replace('episode:', 'series:')}/{series_id}"
             if destination:
                 if destination["modified"] > row["modified"]:
                     value = destination["progress"]

src/model/history.rs

@@ -13,24 +13,34 @@ use super::{
     ModelController,
 };
 
-const HISTORY_MIGRATION: &str = "canonical_history_ids_v2";
+const HISTORY_MIGRATION: &str = "canonical_history_ids_v4";
+
+fn non_empty_id(id: Option<&str>) -> Option<&str> {
+    id.map(str::trim).filter(|id| !id.is_empty())
+}
+
+fn series_history_key(serie: &Serie) -> String {
+    non_empty_id(serie.imdb.as_deref())
+        .map(|imdb| format!("imdb/{imdb}"))
+        .unwrap_or_else(|| format!("redseat/{}", serie.id))
+}
 
 pub fn series_history_id(serie: &Serie) -> String {
-    format!("series:redseat/{}", serie.id)
+    format!("series:{}", series_history_key(serie))
 }
 
 pub fn movie_history_id(movie: &Movie) -> String {
-    movie
-        .imdb
-        .as_ref()
+    non_empty_id(movie.imdb.as_deref())
         .map(|imdb| format!("movie:imdb/{imdb}"))
         .unwrap_or_else(|| format!("movie:redseat/{}", movie.id))
 }
 
 pub fn episode_history_id(serie: &Serie, episode: &Episode) -> String {
     format!(
-        "episode:redseat/{}/{}/{}",
-        serie.id, episode.season, episode.number
+        "episode:{}/{}/{}",
+        series_history_key(serie),
+        episode.season,
+        episode.number
     )
 }
 
@@ -111,7 +121,7 @@ fn episode_legacy_ids(serie: &Serie, episode: &Episode) -> HashSet<String> {
         .collect();
 
     for key in [
-        serie.imdb.as_ref().map(|id| format!("imdb/{id}")),
+        non_empty_id(serie.imdb.as_deref()).map(|id| format!("imdb/{id}")),
         serie.tmdb.map(|id| format!("tmdb/{id}")),
         serie.tvdb.map(|id| format!("tvdb/{id}")),
         Some(format!("redseat/{}", serie.id)),
@@ -150,8 +160,22 @@ fn unique_candidates<T>(candidates: HashMap<String, HashSet<T>>) -> HashMap<Stri
 
 fn is_current_history_id(kind: &MediaType, id: &str) -> bool {
     match kind {
-        MediaType::Movie => id.starts_with("movie:imdb/") || id.starts_with("movie:redseat/"),
-        MediaType::Episode => id.starts_with("episode:redseat/"),
+        MediaType::Movie => ["movie:imdb/", "movie:redseat/"]
+            .into_iter()
+            .any(|prefix| non_empty_id(id.strip_prefix(prefix)).is_some()),
+        MediaType::Episode => {
+            let Some(path) = id.strip_prefix("episode:imdb/") else {
+                return false;
+            };
+            let mut parts = path.split('/');
+            matches!(
+                (parts.next(), parts.next(), parts.next(), parts.next()),
+                (Some(imdb), Some(season), Some(number), None)
+                    if non_empty_id(Some(imdb)).is_some()
+                        && season.parse::<u32>().is_ok()
+                        && number.parse::<u32>().is_ok()
+            )
+        }
         _ => true,
     }
 }
@@ -166,20 +190,27 @@ impl ModelController {
             return Ok(());
         }
 
-        let watched = self.store.get_all_watched().await?;
-        let progress = self.store.get_all_view_progress_rows().await?;
+        let tombstones_removed = self.store.purge_watched_tombstones().await?;
+        let mut watched = self.store.get_all_watched().await?;
+        let mut progress = self.store.get_all_view_progress_rows().await?;
+        watched.sort_by(|a, b| b.modified.cmp(&a.modified));
+        progress.sort_by(|a, b| b.modified.cmp(&a.modified));
         let legacy_movie_ids: HashSet<String> = watched
             .iter()
             .map(|row| (&row.kind, &row.id))
             .chain(progress.iter().map(|row| (&row.kind, &row.id)))
-            .filter(|(kind, id)| **kind == MediaType::Movie && !is_current_history_id(kind, id))
+            .filter(|(kind, id)| {
+                **kind == MediaType::Movie && !is_current_history_id(kind, id)
+            })
             .map(|(_, id)| id.clone())
             .collect();
         let legacy_episode_ids: HashSet<String> = watched
             .iter()
             .map(|row| (&row.kind, &row.id))
             .chain(progress.iter().map(|row| (&row.kind, &row.id)))
-            .filter(|(kind, id)| **kind == MediaType::Episode && !is_current_history_id(kind, id))
+            .filter(|(kind, id)| {
+                **kind == MediaType::Episode && !is_current_history_id(kind, id)
+            })
             .map(|(_, id)| id.clone())
             .collect();
 
@@ -285,8 +316,8 @@ impl ModelController {
         log_info(
             LogServiceType::Database,
             format!(
-                "History migration complete: watched rewrites={}, progress rewrites={}",
-                watched_count, progress_count
+                "History migration complete: watched rewrites={}, progress rewrites={}, tombstones removed={}",
+                watched_count, progress_count, tombstones_removed
             ),
         );
         Ok(())
@@ -334,4 +365,54 @@ impl ModelController {
             .await?;
         Ok(())
     }
+
+    pub async fn migrate_series_history_ids(
+        &self,
+        old_serie: &Serie,
+        new_serie: &Serie,
+    ) -> crate::Result<()> {
+        let old_prefix = format!("episode:{}/", series_history_key(old_serie));
+        let new_prefix = format!("episode:{}/", series_history_key(new_serie));
+        if old_prefix == new_prefix {
+            return Ok(());
+        }
+
+        let watched_rewrites = self
+            .store
+            .get_all_watched()
+            .await?
+            .into_iter()
+            .filter(|row| row.kind == MediaType::Episode)
+            .filter_map(|row| {
+                let suffix = row.id.strip_prefix(&old_prefix)?;
+                Some(HistoryIdRewrite {
+                    new_id: format!("{new_prefix}{suffix}"),
+                    kind: row.kind,
+                    old_id: row.id,
+                    user_ref: row.user_ref?,
+                })
+            })
+            .collect();
+        let progress_rewrites = self
+            .store
+            .get_all_view_progress_rows()
+            .await?
+            .into_iter()
+            .filter(|row| row.kind == MediaType::Episode)
+            .filter_map(|row| {
+                let suffix = row.id.strip_prefix(&old_prefix)?;
+                Some(ProgressIdRewrite {
+                    new_id: format!("{new_prefix}{suffix}"),
+                    new_parent: Some(series_history_id(new_serie)),
+                    kind: row.kind,
+                    old_id: row.id,
+                    user_ref: row.user_ref,
+                })
+            })
+            .collect();
+        self.store
+            .apply_history_rewrites(watched_rewrites, progress_rewrites)
+            .await?;
+        Ok(())
+    }
 }