fix(tvdb): resolve TVDB IDs from TMDB IDs via remote-id search

[fallenbagel]

Description

When TMDB has no TVDB ID for a series, Seerr's TheTVDB integration quietly falls back to plain TMDB data. Every path that reaches TheTVDB works out the ID from TMDB alone, so the shows most likely to need better metadata are exactly the ones that never get it, and nothing surfaces that anything was skipped.

Seerr now asks TheTVDB directly which series carries that TMDB ID, and confirms the answer against that series' own record before trusting it, since the lookup will happily return a series that merely shares the number with another site's IDs. Shows that resolve this way get their TheTVDB metadata and stop prompting for a manual match.

How Has This Been Tested?

• Tested via unit tests

Screenshots / Logs (if applicable)

Checklist:

• I have read and followed the contribution guidelines.
• Disclosed any use of AI (see our policy)
• I have updated the documentation accordingly.
• All new and existing tests passed.
• Successful build pnpm build
• Translation keys pnpm i18n:extract
• Database migration (if required)

Summary by CodeRabbit

• Bug Fixes
  • TVDB information can now be resolved for TMDB series that do not already include a TVDB ID.
  • Improved matching helps prevent incorrect TVDB associations by validating series type and source identifiers.
  • TVDB enrichment now includes the resolved ID in a show’s external IDs.
  • TVDB lookup failures and ambiguous results are handled gracefully without interrupting show, season, or series retrieval.
  • Removed sensitive authentication details from TVDB error logging.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: bcd5148f-996e-49fe-9c39-7763a1500e61

📥 Commits

Reviewing files that changed from the base of the PR and between 6f5a177 and 5f14a99.

📒 Files selected for processing (3)

• server/api/tvdb/index.test.ts
• server/api/tvdb/index.ts
• server/api/tvdb/interfaces.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The TVDB provider now resolves missing TVDB IDs from TMDB series IDs. It validates remote ID metadata, integrates the asynchronous lookup into TVDB methods, enriches returned shows, and adds coverage for successful and unsuccessful resolutions.

Changes

TVDB ID resolution

Layer / File(s)	Summary
Resolution contract and lookup server/api/tvdb/interfaces.ts, server/api/tvdb/index.ts	Adds remote ID response types and resolves a unique TVDB series by validating TMDB TV remote IDs.
Async provider integration server/api/tvdb/index.ts	Updates TVDB lookup callers to await resolution and adds the resolved ID to enriched TMDB show data.
Resolution validation server/api/tvdb/index.test.ts	Tests valid matches, invalid metadata, non-series results, ambiguous results, empty results, and lookup errors.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Tvdb
  participant ExternalAPI
  participant TVDB
  Tvdb->>ExternalAPI: refresh authentication token
  Tvdb->>TVDB: search remote ID by TMDB series ID
  TVDB-->>Tvdb: candidate series
  Tvdb->>TVDB: fetch extended remote IDs
  TVDB-->>Tvdb: remote ID records
  Tvdb-->>Tvdb: return unique TVDB series ID or null

Loading

Suggested reviewers: 0xsysr3ll, danshilm

Merge Risk: ⚪ Minimal · up to deacf

Missing TVDB IDs can now be resolved from TMDB series IDs while invalid, ambiguous, and failed lookups safely retain the existing fallback behavior. The change is covered for the resolution success and failure paths and is ready to merge.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: resolving TVDB IDs from TMDB IDs through remote-ID search.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit hops through IDs bright,
TMDB points to TVDB light.
Remote clues are checked with care,
Empty paths return null air.
Tests guard each winding trail,
And enriched shows raise their detail.}

_{Comment @coderabbitai help to get the list of available commands.}