feat(sync): support TVDB targets when remapping unmatched seasons (#178)

Author: ellite

backend/migrations/versions/d1e2f3a4b5c6_add_season_override_tvdb_target.py

@@ -0,0 +1,29 @@
+"""add tvdb target to show_season_overrides
+
+Revision ID: d1e2f3a4b5c6
+Revises: c8d9e0f1a2b3
+Create Date: 2026-08-15
+"""
+
+from alembic import op
+
+
+revision = "d1e2f3a4b5c6"
+down_revision = "c8d9e0f1a2b3"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # A remap target is now either a TMDB show or a TVDB show (#178) - exactly
+    # one of target_show_tmdb_id/target_show_tvdb_id is set, enforced at the
+    # API layer rather than a DB constraint (matches Show.tmdb_id/tvdb_id,
+    # which use the same either-or convention with no DB-level check).
+    op.execute("ALTER TABLE show_season_overrides ALTER COLUMN target_show_tmdb_id DROP NOT NULL")
+    op.execute("ALTER TABLE show_season_overrides ADD COLUMN IF NOT EXISTS target_show_tvdb_id INTEGER")
+
+
+def downgrade() -> None:
+    op.execute("DELETE FROM show_season_overrides WHERE target_show_tmdb_id IS NULL")
+    op.execute("ALTER TABLE show_season_overrides DROP COLUMN IF EXISTS target_show_tvdb_id")
+    op.execute("ALTER TABLE show_season_overrides ALTER COLUMN target_show_tmdb_id SET NOT NULL")

backend/models/season_override.py

@@ -1,4 +1,5 @@
 from datetime import datetime
+from typing import Optional
 from sqlalchemy import DateTime, ForeignKey, Integer, UniqueConstraint, func
 from sqlalchemy.orm import Mapped, mapped_column
 from .base import Base
@@ -10,10 +11,14 @@ class ShowSeasonOverride(Base):
         UniqueConstraint("user_id", "source_show_tmdb_id", "source_season_number", name="uq_season_override"),
     )
 
-    id                   : Mapped[int]      = mapped_column(Integer, primary_key=True)
-    user_id              : Mapped[int]      = mapped_column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
-    source_show_tmdb_id  : Mapped[int]      = mapped_column(Integer, nullable=False)
-    source_season_number : Mapped[int]      = mapped_column(Integer, nullable=False)
-    target_show_tmdb_id  : Mapped[int]      = mapped_column(Integer, nullable=False)
-    target_season_number : Mapped[int]      = mapped_column(Integer, nullable=False)
-    created_at           : Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), nullable=False)
+    id                   : Mapped[int]           = mapped_column(Integer, primary_key=True)
+    user_id              : Mapped[int]           = mapped_column(Integer, ForeignKey("users.id", ondelete="CASCADE"), nullable=False)
+    source_show_tmdb_id  : Mapped[int]           = mapped_column(Integer, nullable=False)
+    source_season_number : Mapped[int]           = mapped_column(Integer, nullable=False)
+    # Exactly one of target_show_tmdb_id/target_show_tvdb_id is set (#178) -
+    # same either-or convention as Show.tmdb_id/tvdb_id, validated at the API
+    # layer rather than a DB constraint.
+    target_show_tmdb_id  : Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
+    target_show_tvdb_id  : Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
+    target_season_number : Mapped[int]           = mapped_column(Integer, nullable=False)
+    created_at           : Mapped[datetime]      = mapped_column(DateTime, server_default=func.now(), nullable=False)

backend/routers/sync.py

@@ -2,7 +2,7 @@
 import logging
 import re
 from fastapi import APIRouter, Depends, Query, HTTPException, BackgroundTasks
-from pydantic import BaseModel
+from pydantic import BaseModel, model_validator
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 from sqlalchemy import select, update, delete, func, cast
 from sqlalchemy.orm import selectinload
@@ -5928,9 +5928,18 @@ async def _stamp_matched_show_warnings(db: AsyncSession, user_id: int, warnings:
 class SeasonOverrideBody(BaseModel):
     source_show_tmdb_id: int
     source_season_number: int
-    target_show_tmdb_id: int
+    # Exactly one of these two must be set - the target is either a TMDB show
+    # or a TVDB show (#178).
+    target_show_tmdb_id: int | None = None
+    target_show_tvdb_id: int | None = None
     target_season_number: int
 
+    @model_validator(mode="after")
+    def _exactly_one_target(self) -> "SeasonOverrideBody":
+        if bool(self.target_show_tmdb_id) == bool(self.target_show_tvdb_id):
+            raise ValueError("Exactly one of target_show_tmdb_id or target_show_tvdb_id must be set")
+        return self
+
 
 @router.get("/season-overrides")
 async def list_season_overrides(
@@ -5942,24 +5951,36 @@ async def list_season_overrides(
     )
     overrides = result.scalars().all()
 
-    # Resolve show titles for all distinct TMDB IDs referenced by overrides
-    all_tmdb_ids = {o.source_show_tmdb_id for o in overrides} | {o.target_show_tmdb_id for o in overrides}
-    show_title_map: dict[int, str] = {}
+    # Resolve show titles for all distinct TMDB/TVDB IDs referenced by overrides
+    all_tmdb_ids = {o.source_show_tmdb_id for o in overrides} | {o.target_show_tmdb_id for o in overrides if o.target_show_tmdb_id}
+    all_tvdb_ids = {o.target_show_tvdb_id for o in overrides if o.target_show_tvdb_id}
+    tmdb_title_map: dict[int, str] = {}
+    tvdb_title_map: dict[int, str] = {}
     if all_tmdb_ids:
         shows_res = await db.execute(select(Show.tmdb_id, Show.title).where(Show.tmdb_id.in_(list(all_tmdb_ids))))
         for tmdb_id, title in shows_res.all():
             if tmdb_id is not None:
-                show_title_map[tmdb_id] = title
+                tmdb_title_map[tmdb_id] = title
+    if all_tvdb_ids:
+        shows_res = await db.execute(select(Show.tvdb_id, Show.title).where(Show.tvdb_id.in_(list(all_tvdb_ids))))
+        for tvdb_id, title in shows_res.all():
+            if tvdb_id is not None:
+                tvdb_title_map[tvdb_id] = title
 
     return [
         {
             "id": o.id,
             "source_show_tmdb_id": o.source_show_tmdb_id,
             "source_season_number": o.source_season_number,
-            "source_show_title": show_title_map.get(o.source_show_tmdb_id),
+            "source_show_title": tmdb_title_map.get(o.source_show_tmdb_id),
             "target_show_tmdb_id": o.target_show_tmdb_id,
+            "target_show_tvdb_id": o.target_show_tvdb_id,
+            "target_source": "tvdb" if o.target_show_tvdb_id else "tmdb",
             "target_season_number": o.target_season_number,
-            "target_show_title": show_title_map.get(o.target_show_tmdb_id),
+            "target_show_title": (
+                tvdb_title_map.get(o.target_show_tvdb_id) if o.target_show_tvdb_id
+                else tmdb_title_map.get(o.target_show_tmdb_id)
+            ),
         }
         for o in overrides
     ]
@@ -5980,14 +6001,19 @@ async def create_season_override(
     )
     override = existing.scalar_one_or_none()
     if override:
+        # Clear whichever target field isn't set - editing a TMDB-targeted
+        # remap into a TVDB one (or vice versa) must not leave a stale id
+        # from the previous target behind.
         override.target_show_tmdb_id = body.target_show_tmdb_id
+        override.target_show_tvdb_id = body.target_show_tvdb_id
         override.target_season_number = body.target_season_number
     else:
         override = ShowSeasonOverride(
             user_id=current_user.id,
             source_show_tmdb_id=body.source_show_tmdb_id,
             source_season_number=body.source_season_number,
             target_show_tmdb_id=body.target_show_tmdb_id,
+            target_show_tvdb_id=body.target_show_tvdb_id,
             target_season_number=body.target_season_number,
         )
         db.add(override)
@@ -5998,6 +6024,7 @@ async def create_season_override(
         "source_show_tmdb_id": override.source_show_tmdb_id,
         "source_season_number": override.source_season_number,
         "target_show_tmdb_id": override.target_show_tmdb_id,
+        "target_show_tvdb_id": override.target_show_tvdb_id,
         "target_season_number": override.target_season_number,
     }
 
@@ -6070,6 +6097,65 @@ async def apply_season_override(
     if not episodes:
         return {"status": "ok", "remapped": 0}
 
+    if override.target_show_tvdb_id:
+        # ── TVDB target (#178) - some shows have season/episode structures
+        # that only line up under TVDB's numbering, not TMDB's, so the remap
+        # target needs to be able to point at a TVDB show too. ──────────────
+        from core import tvdb as tvdb_client
+        from routers.shows import get_user_tvdb_key
+
+        tvdb_api_key = await get_user_tvdb_key(db, current_user.id)
+        if not tvdb_api_key:
+            raise HTTPException(status_code=400, detail="TVDB API key required")
+        tvdb_lang = tvdb_client.tvdb_language(await get_user_metadata_language(db, current_user.id))
+
+        target_show_result = await db.execute(select(Show).where(Show.tvdb_id == override.target_show_tvdb_id))
+        target_show = target_show_result.scalar_one_or_none()
+        if not target_show:
+            try:
+                raw_series = await tvdb_client.get_series(override.target_show_tvdb_id, tvdb_api_key)
+            except Exception as e:
+                raise HTTPException(status_code=502, detail=f"Could not fetch target show from TVDB: {e}")
+            show_fmt = tvdb_client.format_series(raw_series, language=tvdb_lang)
+            target_show = Show(
+                tvdb_id=override.target_show_tvdb_id,
+                tmdb_id=None,
+                title=show_fmt.get("title") or f"TVDB #{override.target_show_tvdb_id}",
+                original_title=show_fmt.get("original_title"),
+                overview=show_fmt.get("overview"),
+                poster_path=show_fmt.get("poster_path"),
+                backdrop_path=show_fmt.get("backdrop_path"),
+                status=show_fmt.get("status"),
+                first_air_date=show_fmt.get("first_air_date"),
+                last_air_date=show_fmt.get("last_air_date"),
+                tmdb_data={"seasons": show_fmt.get("seasons", []), "genres": show_fmt.get("genres", []), "source": "tvdb"},
+            )
+            db.add(target_show)
+            await db.flush()
+
+        try:
+            raw_eps = await tvdb_client.get_series_episodes(
+                override.target_show_tvdb_id, override.target_season_number, tvdb_api_key, language=tvdb_lang
+            )
+        except Exception as e:
+            raise HTTPException(status_code=502, detail=f"Could not fetch target season from TVDB: {e}")
+        tvdb_ep_map = {e.get("number"): e for e in raw_eps}
+
+        async def remap_episode_tvdb(media: Media, raw_ep: dict | None) -> None:
+            media.show_id = target_show.id
+            media.season_number = override.target_season_number
+            if raw_ep:
+                await enrich_episode_from_tvdb(media, tvdb_client.format_episode(raw_ep))
+
+        for media in episodes:
+            raw_ep = tvdb_ep_map.get(media.episode_number)
+            await apply_media_change_safely(
+                db, media, lambda media=media, raw_ep=raw_ep: remap_episode_tvdb(media, raw_ep)
+            )
+
+        await db.commit()
+        return {"status": "ok", "remapped": len(episodes)}
+
     # Find or create the target Show
     target_show_result = await db.execute(
         select(Show).where(Show.tmdb_id == override.target_show_tmdb_id)

frontend/src/lib/api.ts

@@ -245,7 +245,9 @@ export interface ShowSeasonOverride {
   source_show_tmdb_id: number;
   source_season_number: number;
   source_show_title: string | null;
-  target_show_tmdb_id: number;
+  target_show_tmdb_id: number | null;
+  target_show_tvdb_id: number | null;
+  target_source: "tmdb" | "tvdb";
   target_season_number: number;
   target_show_title: string | null;
 }

frontend/src/pages/connections.astro

@@ -458,8 +458,11 @@ const sonarrConfigured   = !!(settings.sonarr_url && settings.sonarr_token);
                         <span class="text-zinc-200 font-medium">{o.source_show_title ?? `TMDB #${o.source_show_tmdb_id}`}</span>
                         <span class="ml-1.5 text-zinc-500">Season {o.source_season_number}</span>
                         <span class="mx-1.5 text-zinc-600">→</span>
-                        <span class="text-zinc-300">{o.target_show_title ?? `TMDB #${o.target_show_tmdb_id}`}</span>
+                        <span class="text-zinc-300">{o.target_show_title ?? (o.target_source === 'tvdb' ? `TVDB #${o.target_show_tvdb_id}` : `TMDB #${o.target_show_tmdb_id}`)}</span>
                         <span class="ml-1.5 text-zinc-500">Season {o.target_season_number}</span>
+                        <span class={`ml-1.5 text-[10px] font-semibold uppercase tracking-wide px-1.5 py-0.5 rounded ${o.target_source === 'tvdb' ? 'bg-blue-500/15 text-blue-400' : 'bg-emerald-500/15 text-emerald-400'}`}>
+                          {o.target_source}
+                        </span>
                       </div>
                       <button
                         type="button"
@@ -4828,7 +4831,8 @@ const sonarrConfigured   = !!(settings.sonarr_url && settings.sonarr_token);
         seasonsList.innerHTML = '';
         seasonsLoading.classList.remove('hidden');
         try {
-          const showRes = await fetch(`/api/proxy/shows/${tmdbId}`, {
+          const showUrl = tvdbId ? `/api/proxy/shows/tvdb/${tvdbId}` : `/api/proxy/shows/${tmdbId}`;
+          const showRes = await fetch(showUrl, {
             headers: { 'Authorization': `Bearer ${token}` },
           });
           const showData = showRes.ok ? await showRes.json() : null;
@@ -5001,18 +5005,20 @@ const sonarrConfigured   = !!(settings.sonarr_url && settings.sonarr_token);
       }
 
       // Remap mode
-      if (!targetTmdbId || !targetSeasonNumber) return;
+      if ((!targetTmdbId && !targetTvdbId) || !targetSeasonNumber) return;
       saveBtn.textContent = 'Saving…';
       try {
+        const remapBody: any = {
+          source_show_tmdb_id: srcTmdbId,
+          source_season_number: srcSeason,
+          target_season_number: targetSeasonNumber,
+        };
+        if (targetTvdbId) remapBody.target_show_tvdb_id = targetTvdbId;
+        else remapBody.target_show_tmdb_id = targetTmdbId;
         const createRes = await fetch('/api/proxy/sync/season-overrides', {
           method: 'POST',
           headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({
-            source_show_tmdb_id: srcTmdbId,
-            source_season_number: srcSeason,
-            target_show_tmdb_id: targetTmdbId,
-            target_season_number: targetSeasonNumber,
-          }),
+          body: JSON.stringify(remapBody),
         });
         if (!createRes.ok) throw new Error(await createRes.text());
         const override = await createRes.json();
@@ -5041,13 +5047,15 @@ const sonarrConfigured   = !!(settings.sonarr_url && settings.sonarr_token);
       (document.getElementById('remap-modal-title') as HTMLElement).textContent = 'Remap Season';
       (document.getElementById('remap-source-label') as HTMLElement).textContent = `"${title}" — Season ${season}`;
       (document.getElementById('remap-tmdb-label') as HTMLElement).textContent = 'Search for the correct TMDB show';
-      (document.getElementById('remap-tmdb-section') as HTMLElement).classList.remove('hidden');
-      (document.getElementById('remap-tvdb-section') as HTMLElement).classList.add('hidden');
       (document.getElementById('remap-seasons-area') as HTMLElement).classList.remove('hidden');
       (document.getElementById('remap-save') as HTMLButtonElement).textContent = 'Save & Apply';
+      // TMDB/TVDB toggle (#178) - some shows' season structure only exists on
+      // TVDB, so the remap target needs the same TMDB/TVDB choice the "Match"
+      // flow already has, not just TMDB search.
+      (document.getElementById('match-tab-bar') as HTMLElement).classList.remove('hidden');
       modal.classList.remove('hidden');
       modal.classList.add('flex');
-      searchInput.focus();
+      setMatchTab('tmdb');
     };
 
     (window as any).openMatchModal = (seriesName: string) => {