@vanomarb/animap 0.0.0-stage → 1.0.0

package/src/byok/http.js

@@ -0,0 +1,82 @@
+// Shared plumbing for the provider clients (TMDB, TVDB, Fanart.tv), which run in the
+// caller's own process: a browser tab or a Node server. Keys go to the provider and
+// nowhere else: never to the mapping API, never into a log line, never into an error
+// message. Callers pass `fetch` so tests can drive the clients.
+
+export class ByokError extends Error {
+  /**
+   * code: 'invalid_key' | 'rate_limited' | 'network' | 'timeout' | 'not_found' | 'bad_response' | 'aborted'
+   */
+  constructor(provider, code, message, { status = null, retryAfter = null } = {}) {
+    super(message);
+    this.name = 'ByokError';
+    this.provider = provider;
+    this.code = code;
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+}
+
+const NAMES = { tmdb: 'TMDB', tvdb: 'TVDB', fanart: 'Fanart.tv', kitsu: 'Kitsu', cinemeta: 'Cinemeta' };
+
+/** Combine the caller's abort signal (navigation) with a timeout. */
+function withTimeout(signal, ms) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(new DOMException('timeout', 'TimeoutError')), ms);
+  const onAbort = () => ac.abort(signal.reason);
+  if (signal) {
+    if (signal.aborted) ac.abort(signal.reason);
+    else signal.addEventListener('abort', onAbort, { once: true });
+  }
+  return {
+    signal: ac.signal,
+    done: () => { clearTimeout(timer); signal?.removeEventListener('abort', onAbort); },
+    timedOut: () => ac.signal.aborted && ac.signal.reason?.name === 'TimeoutError',
+  };
+}
+
+/**
+ * One provider request. Maps failures to ByokError codes. The URL (which may hold an
+ * api_key) is never put in an error or logged.
+ */
+export async function providerFetch(provider, url, { fetch: f, signal, timeoutMs = 8000, method = 'GET', headers = {}, body } = {}) {
+  const name = NAMES[provider] ?? provider;
+  const t = withTimeout(signal, timeoutMs);
+  let res;
+  try {
+    res = await f(url, {
+      method,
+      headers: { Accept: 'application/json', ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}), ...headers },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: t.signal,
+      referrerPolicy: 'no-referrer',
+      credentials: 'omit',
+    });
+  } catch (e) {
+    if (t.timedOut()) throw new ByokError(provider, 'timeout', `${name} did not answer in time.`);
+    if (signal?.aborted) throw new ByokError(provider, 'aborted', `${name} request cancelled.`);
+    throw new ByokError(provider, 'network', `Could not reach ${name}.`);
+  } finally {
+    t.done();
+  }
+  if (res.status === 401 || res.status === 403) throw new ByokError(provider, 'invalid_key', `${name} rejected the key.`, { status: res.status });
+  if (res.status === 429) {
+    const retryAfter = Number(res.headers?.get?.('Retry-After')) || null;
+    throw new ByokError(provider, 'rate_limited', `${name} rate limit reached. Try again ${retryAfter ? `in ${retryAfter} seconds` : 'in a minute'}.`, { status: 429, retryAfter });
+  }
+  if (res.status === 404) throw new ByokError(provider, 'not_found', `${name} has no record for this title.`, { status: 404 });
+  if (!res.ok) throw new ByokError(provider, 'bad_response', `${name} answered ${res.status}.`, { status: res.status });
+  try {
+    return await res.json();
+  } catch {
+    throw new ByokError(provider, 'bad_response', `${name} sent something that is not JSON.`, { status: res.status });
+  }
+}
+
+/** Query string from an object, skipping empty values. */
+export function qs(params) {
+  const s = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) if (v !== undefined && v !== null && v !== '') s.set(k, String(v));
+  const out = s.toString();
+  return out ? `?${out}` : '';
+}

package/src/byok/index.d.ts

@@ -0,0 +1,80 @@
+import type { ByokError, ByokProvider, CacheStorage, KeyCheck, ProviderErrorInfo, Title, TitleEpisode, TitleSummary } from '../index.js';
+
+export { ByokError } from '../index.js';
+
+export function providerFetch(provider: ByokProvider | string, url: string, options?: {
+  fetch?: typeof fetch; signal?: AbortSignal; timeoutMs?: number; method?: string; headers?: Record<string, string>; body?: unknown;
+}): Promise<any>;
+export function qs(params: Record<string, unknown>): string;
+
+export const DEFAULT_PREFIX: string;
+export const TTL_MS: number;
+export function keySignature(keys?: { tmdb?: string; tvdb?: string; fanart?: string }): string;
+export function memoryStorage(options?: { maxItems?: number }): CacheStorage & { clear(): void; readonly length: number };
+export interface ByokCache {
+  get(kind: string, id: string, signature: string): any | Promise<any>;
+  set(kind: string, id: string, signature: string, data: unknown): void | Promise<void>;
+}
+export function createByokCache(options?: { storage?: CacheStorage; prefix?: string; now?: () => number; ttl?: number }): ByokCache;
+
+export interface ByokKeys { tmdb?: string; tvdb?: string; tvdbPin?: string; fanart?: string }
+
+export const TMDB_IMAGE: string;
+export function isV4Token(key: string): boolean;
+export function createTmdb(options: { key: string; fetch?: typeof fetch; timeoutMs?: number }): {
+  kind: 'v3' | 'v4';
+  check(signal?: AbortSignal): Promise<any>;
+  findByImdb(imdbId: string, signal?: AbortSignal): Promise<any>;
+  tv(id: string, signal?: AbortSignal): Promise<any>;
+  movie(id: string, signal?: AbortSignal): Promise<any>;
+  season(id: string, season: number, signal?: AbortSignal): Promise<any>;
+  search(query: string, options?: { type?: 'tv' | 'movie'; year?: number }, signal?: AbortSignal): Promise<any>;
+};
+export function normalizeTmdb(json: any, type: 'tv' | 'movie'): any;
+export function tmdbTvPeople(data: any): { cast: Array<{ name: string; character: string | null; profile_path: string | null }>; directors: string[]; writers: string[] };
+export function tmdbMoviePeople(data: any): { cast: Array<{ name: string; character: string | null; profile_path: string | null }>; directors: string[]; writers: string[] };
+export function normalizeTmdbSeason(json: any): Record<number, { name: string | null; overview: string | null; thumbnail: string | null; released: string | null }>;
+
+export function forgetTvdbTokens(): void;
+export function createTvdb(options: { key: string; pin?: string; fetch?: typeof fetch; timeoutMs?: number }): {
+  check(signal?: AbortSignal): Promise<{ ok: true }>;
+  seriesExtended(id: string, signal?: AbortSignal): Promise<any>;
+  movieExtended(id: string, signal?: AbortSignal): Promise<any>;
+  episodes(id: string, season: number, signal?: AbortSignal): Promise<any>;
+  allEpisodes(id: string, options?: { order?: string; lang?: string; signal?: AbortSignal }): Promise<any[]>;
+  translation(id: string, options?: { lang?: string; kind?: 'series' | 'movie' }, signal?: AbortSignal): Promise<any>;
+  artworks(id: string, signal?: AbortSignal): Promise<any>;
+  searchRemoteId(remoteId: string, signal?: AbortSignal): Promise<any>;
+};
+/** "S{season}E{number}" → TVDB absolute number. */
+export function episodeAbsoluteMap(episodes: any[]): Record<string, number>;
+/** Best poster (English, textless, score), background (textless first) and logo (English or textless only). */
+export function pickTvdbArt(artworks: any[], options?: { movie?: boolean; fallbackPoster?: string | null }): { poster: string | null; background: string | null; logo: string | null };
+export function normalizeTvdb(json: any): any;
+export function normalizeTvdbEpisodes(json: any, season: number): Record<number, { name: string | null; overview: string | null; thumbnail: string | null; released: string | null }>;
+
+export const FANART_CHECK_TVDB_ID: string;
+export function createFanart(options: { key: string; fetch?: typeof fetch; timeoutMs?: number }): {
+  check(signal?: AbortSignal): Promise<any>;
+  tv(tvdbId: string, signal?: AbortSignal): Promise<any>;
+  movie(tmdbId: string, signal?: AbortSignal): Promise<any>;
+};
+/** English, then textless, then (unless textOnly) anything; ties by likes. */
+export function bestFanart(images: Array<{ url: string; lang?: string; likes?: string }>, options?: { textOnly?: boolean }): string | null;
+export function fanartTarget(title: Pick<Title, 'type' | 'ids'>): { kind: 'tv' | 'movie'; id: string } | null;
+export function normalizeFanart(json: any, kind: 'tv' | 'movie'): { poster: string | null; background: string | null; logo: string | null } | null;
+
+export interface ByokSources { tmdb: any; tvdb: any; fanart: any; similar: TitleSummary[]; ids?: Title['ids'] }
+export function isGenericEpisodeName(name: string | null | undefined, number?: number): boolean;
+export function mergeTitle(server: Title, sources?: Partial<ByokSources>): { title: Title; filled: Record<string, ByokProvider> };
+export function mergeEpisodes(episodes: TitleEpisode[], sources: Array<[ByokProvider, Record<number, any>]>): { episodes: TitleEpisode[]; filledBy: Set<ByokProvider> };
+export function providerList(filled: Record<string, string>): string;
+
+export function fetchSources(title: Pick<Title, 'id' | 'type' | 'ids'>, keys: ByokKeys, options?: {
+  fetch?: typeof fetch; findTitle?: (ref: string) => Promise<TitleSummary | null>; signal?: AbortSignal;
+}): Promise<{ sources: ByokSources; errors: ProviderErrorInfo[] }>;
+export function fetchEpisodeFills(title: Pick<Title, 'type' | 'ids'>, season: number, keys: ByokKeys, options?: {
+  fetch?: typeof fetch; signal?: AbortSignal; ids?: Partial<Title['ids']>;
+}): Promise<{ fills: Array<[ByokProvider, Record<number, any>]>; errors: ProviderErrorInfo[] }>;
+export function checkKey(provider: ByokProvider, keys: ByokKeys, options?: { fetch?: typeof fetch; signal?: AbortSignal }): Promise<Omit<KeyCheck, 'state'> & { state: 'connected' | 'invalid' | 'rate_limited' | 'error' }>;
+export function isTransient(error: { code?: string } | null | undefined): boolean;

package/src/byok/index.js

@@ -0,0 +1,13 @@
+// Low-level BYOK building blocks: provider clients, normalizers, the merge and the cache.
+// The Client uses these when it is given provider keys; apps that drive their own UI state
+// (the web app's React hooks) use them directly.
+export { ByokError, providerFetch, qs } from './http.js';
+export { createByokCache, keySignature, memoryStorage, DEFAULT_PREFIX, TTL_MS } from './cache.js';
+export { createTmdb, isV4Token, normalizeTmdb, normalizeTmdbSeason, tmdbMoviePeople, tmdbTvPeople, TMDB_IMAGE } from './tmdb.js';
+export { createTvdb, episodeAbsoluteMap, forgetTvdbTokens, normalizeTvdb, normalizeTvdbEpisodes, pickTvdbArt } from './tvdb.js';
+export { bestFanart, createFanart, fanartTarget, normalizeFanart, FANART_CHECK_TVDB_ID } from './fanart.js';
+export { isGenericEpisodeName, mergeEpisodes, mergeTitle, providerList } from './merge.js';
+export { checkKey, fetchEpisodeFills, fetchSources } from './enrich.js';
+
+/** Errors that may pass on their own; results fetched around them are not cached. */
+export const isTransient = (e) => ['network', 'timeout', 'rate_limited', 'bad_response'].includes(e?.code);

package/src/byok/merge.js

@@ -0,0 +1,107 @@
+// Merge provider data fetched with the caller's own keys into the API's Title. Pure.
+// Rules (contract, BYOK): never overwrite a field the server filled; fill gaps in the order
+// TMDB -> TVDB, artwork TMDB -> TVDB -> Fanart.tv; ratings are never merged, each provider
+// only fills its own card.
+
+const empty = (v) => v === null || v === undefined || v === '' || (Array.isArray(v) && v.length === 0);
+
+/** "Episode 5", "Episode 085": placeholder names worth replacing with a real one. */
+export function isGenericEpisodeName(name, number) {
+  if (empty(name)) return true;
+  const m = /^episode\s+0*(\d+)$/i.exec(String(name).trim());
+  return Boolean(m) && (number === undefined || Number(m[1]) === Number(number));
+}
+
+/**
+ * server: the Title from GET /v1/titles/:id.
+ * sources: { tmdb, tvdb, fanart } normalized payloads (any may be null); similar: TitleSummary[]
+ * resolved from TMDB recommendations.
+ * Returns { title, filled: { field: provider } }.
+ */
+export function mergeTitle(server, { tmdb = null, tvdb = null, fanart = null, similar = [] } = {}) {
+  const title = {
+    ...server,
+    ratings: { ...(server.ratings ?? {}) },
+    cast: [...(server.cast ?? [])],
+    seasons: (server.seasons ?? []).map((s) => ({ ...s })),
+    similar: [...(server.similar ?? [])],
+  };
+  const filled = {};
+  const take = (field, order) => {
+    if (!empty(title[field])) return;
+    for (const [provider, src] of order) {
+      if (src && !empty(src[field])) { title[field] = src[field]; filled[field] = provider; return; }
+    }
+  };
+
+  for (const f of ['description', 'genres', 'runtime', 'status', 'country', 'certification', 'directors', 'writers']) take(f, [['tmdb', tmdb], ['tvdb', tvdb]]);
+  for (const f of ['poster', 'background', 'logo']) take(f, [['tmdb', tmdb], ['tvdb', tvdb], ['fanart', fanart]]);
+
+  // Own rating cards only.
+  if (empty(title.ratings.tmdb) && tmdb?.rating?.value) {
+    title.ratings.tmdb = { value: tmdb.rating.value, votes: tmdb.rating.votes ?? null };
+    filled['ratings.tmdb'] = 'tmdb';
+  }
+  if (empty(title.ratings.tvdb) && Number.isFinite(tvdb?.score)) {
+    title.ratings.tvdb = { value: null, votes: null, score: tvdb.score };
+    filled['ratings.tvdb'] = 'tvdb';
+  }
+
+  // Cast: take a provider's list when the server has none; otherwise only add missing photos.
+  if (!title.cast.length) {
+    const src = tmdb?.cast?.length ? ['tmdb', tmdb.cast] : tvdb?.cast?.length ? ['tvdb', tvdb.cast] : null;
+    if (src) { title.cast = src[1].map((c) => ({ ...c })); filled.cast = src[0]; }
+  } else {
+    const byName = new Map();
+    for (const [p, list] of [['tvdb', tvdb?.cast], ['tmdb', tmdb?.cast]]) for (const c of list ?? []) if (c.photo) byName.set(c.name.toLowerCase(), [p, c.photo]);
+    title.cast = title.cast.map((c) => {
+      if (c.photo || !c.name) return c;
+      const hit = byName.get(c.name.toLowerCase());
+      if (!hit) return c;
+      filled['cast.photo'] = filled['cast.photo'] ?? hit[0];
+      return { ...c, photo: hit[1] };
+    });
+  }
+
+  for (const s of title.seasons) {
+    if (!empty(s.poster)) continue;
+    const p = tmdb?.seasonPosters?.[s.season] ? ['tmdb', tmdb.seasonPosters[s.season]] : tvdb?.seasonPosters?.[s.season] ? ['tvdb', tvdb.seasonPosters[s.season]] : null;
+    if (p) { s.poster = p[1]; filled['seasons.poster'] = filled['seasons.poster'] ?? p[0]; }
+  }
+
+  // Similar: the server's own first, then TMDB recommendations that resolved to our titles.
+  const seen = new Set([server.id, ...title.similar.map((t) => t.id)]);
+  const extra = similar.filter((t) => t && !seen.has(t.id) && seen.add(t.id));
+  if (extra.length) { title.similar = [...title.similar, ...extra].slice(0, 12); filled.similar = 'tmdb'; }
+
+  return { title, filled };
+}
+
+/**
+ * Fill episode rows from provider episode maps ({ [episodeNumber]: { name, overview, thumbnail, released } }),
+ * in order of preference. Returns { episodes, filledBy: Set<provider> }.
+ */
+export function mergeEpisodes(episodes, sources) {
+  const filledBy = new Set();
+  const out = episodes.map((ep) => {
+    const row = { ...ep };
+    for (const [provider, map] of sources) {
+      const f = map?.[ep.episode];
+      if (!f) continue;
+      if (isGenericEpisodeName(row.name, ep.episode) && !empty(f.name) && !isGenericEpisodeName(f.name, ep.episode)) { row.name = f.name; filledBy.add(provider); }
+      if (empty(row.overview) && !empty(f.overview)) { row.overview = f.overview; filledBy.add(provider); }
+      if (empty(row.thumbnail) && !empty(f.thumbnail)) { row.thumbnail = f.thumbnail; filledBy.add(provider); }
+      if (empty(row.released) && !empty(f.released)) { row.released = f.released; filledBy.add(provider); }
+    }
+    return row;
+  });
+  return { episodes: out, filledBy };
+}
+
+/** "TMDB and TVDB" from the providers that actually filled something. */
+export function providerList(filled) {
+  const names = { tmdb: 'TMDB', tvdb: 'TVDB', fanart: 'Fanart.tv' };
+  const list = [...new Set(Object.values(filled))].map((p) => names[p] ?? p);
+  if (list.length <= 1) return list.join('');
+  return `${list.slice(0, -1).join(', ')} and ${list[list.length - 1]}`;
+}

package/src/byok/tmdb.js

@@ -0,0 +1,123 @@
+// TMDB v3, called from the caller's process. A v3 API key travels as ?api_key=; a v4 read access token
+// (a JWT) travels as Authorization: Bearer. The shape of the key decides which.
+import { ByokError, providerFetch, qs } from './http.js';
+
+const BASE = 'https://api.themoviedb.org/3';
+export const TMDB_IMAGE = 'https://image.tmdb.org/t/p';
+
+/** v4 read tokens are JWTs ("eyJ…" with two dots); v3 keys are 32 hex characters. */
+export function isV4Token(key) {
+  const k = String(key ?? '').trim();
+  return k.split('.').length === 3 && k.startsWith('eyJ');
+}
+
+export function createTmdb({ key, fetch: f = globalThis.fetch.bind(globalThis), timeoutMs } = {}) {
+  const k = String(key ?? '').trim();
+  if (!k) throw new ByokError('tmdb', 'invalid_key', 'No TMDB key set.');
+  const v4 = isV4Token(k);
+
+  function get(path, params = {}, signal) {
+    const url = `${BASE}${path}${qs(v4 ? params : { ...params, api_key: k })}`;
+    return providerFetch('tmdb', url, { fetch: f, signal, timeoutMs, headers: v4 ? { Authorization: `Bearer ${k}` } : {} });
+  }
+
+  return {
+    kind: v4 ? 'v4' : 'v3',
+    /** Cheap call that succeeds only with a valid key. */
+    check: (signal) => get('/authentication', {}, signal),
+    findByImdb: (imdbId, signal) => get(`/find/${encodeURIComponent(imdbId)}`, { external_source: 'imdb_id' }, signal),
+    tv: (id, signal) => get(`/tv/${encodeURIComponent(id)}`, { append_to_response: 'aggregate_credits,recommendations,external_ids,content_ratings,images', include_image_language: 'en,null' }, signal),
+    movie: (id, signal) => get(`/movie/${encodeURIComponent(id)}`, { append_to_response: 'credits,recommendations,external_ids,release_dates,images', include_image_language: 'en,null' }, signal),
+    season: (id, season, signal) => get(`/tv/${encodeURIComponent(id)}/season/${encodeURIComponent(season)}`, {}, signal),
+    /** GET /search/tv or /search/movie; `year` narrows by first air / release year. */
+    search: (query, { type = 'tv', year } = {}, signal) => get(`/search/${type === 'movie' ? 'movie' : 'tv'}`, {
+      query, ...(year ? { [type === 'movie' ? 'year' : 'first_air_date_year']: year } : {}),
+    }, signal),
+  };
+}
+
+const uniqueNames = (list) => [...new Set(list.filter(Boolean))];
+const SERIES_DIRECTOR_JOBS = new Set(['Series Director', 'Chief Director', 'Supervising Director']);
+
+/** A film's people from `credits`. Pure. */
+export function tmdbMoviePeople(data) {
+  const crew = data?.credits?.crew ?? [];
+  return {
+    cast: (data?.credits?.cast ?? []).map((c) => ({ name: c.name, character: c.character || null, profile_path: c.profile_path ?? null })),
+    directors: uniqueNames(crew.filter((c) => c.job === 'Director').map((c) => c.name)),
+    writers: uniqueNames(crew.filter((c) => c.department === 'Writing').map((c) => c.name)),
+  };
+}
+
+/**
+ * A series' people from aggregate_credits (the whole run). `credits` covers only the
+ * latest season and never lists a TV director, since directors are credited per episode.
+ * Director: the series-level credit when there is one, else a "Director" credited on at
+ * least half the run; the one-episode directors are not the show's. Pure.
+ */
+export function tmdbTvPeople(data) {
+  const agg = data?.aggregate_credits;
+  if (!agg) return { ...tmdbMoviePeople(data), directors: [], writers: uniqueNames((data?.created_by ?? []).map((c) => c.name)) };
+  const total = data.number_of_episodes || 0;
+  const jobsOf = (person) => (person.jobs ?? []).map((j) => ({ job: j.job, episodes: j.episode_count || 0 }));
+  const credited = (pred) => (agg.crew ?? [])
+    .flatMap((p) => jobsOf(p).filter(pred).map((j) => ({ name: p.name, episodes: j.episodes })))
+    .sort((a, b) => b.episodes - a.episodes);
+  const series = credited((j) => SERIES_DIRECTOR_JOBS.has(j.job));
+  const regular = total ? credited((j) => j.job === 'Director' && j.episodes * 2 >= total) : [];
+  return {
+    cast: (agg.cast ?? []).map((c) => ({ name: c.name, character: c.roles?.[0]?.character || null, profile_path: c.profile_path ?? null })),
+    directors: uniqueNames((series.length ? series : regular).map((d) => d.name)).slice(0, 3),
+    writers: uniqueNames([
+      ...(data.created_by ?? []).map((c) => c.name),
+      ...(agg.crew ?? []).filter((p) => p.department === 'Writing')
+        .sort((a, b) => (b.total_episode_count || 0) - (a.total_episode_count || 0)).map((p) => p.name),
+    ]).slice(0, 5),
+  };
+}
+
+const img = (path, size) => (path ? `${TMDB_IMAGE}/${size}${path}` : null);
+
+/** TMDB tv or movie details -> the fields our Title uses. Pure. */
+export function normalizeTmdb(json, type) {
+  if (!json) return null;
+  const movie = type === 'movie';
+  const people = movie ? tmdbMoviePeople(json) : tmdbTvPeople(json);
+  const cast = people.cast.slice(0, 24).map((c) => ({ name: c.name, character: c.character, photo: img(c.profile_path, 'w185') }));
+  const logos = json.images?.logos ?? [];
+  const logo = (logos.find((l) => l.iso_639_1 === 'en') ?? logos.find((l) => !l.iso_639_1))?.file_path;
+  const runtime = movie ? json.runtime : json.episode_run_time?.[0];
+  const usRating = movie
+    ? json.release_dates?.results?.find((r) => r.iso_3166_1 === 'US')?.release_dates?.find((d) => d.certification)?.certification
+    : json.content_ratings?.results?.find((r) => r.iso_3166_1 === 'US')?.rating;
+  return {
+    tmdbId: String(json.id),
+    imdbId: json.external_ids?.imdb_id ?? json.imdb_id ?? null,
+    tvdbId: json.external_ids?.tvdb_id ? String(json.external_ids.tvdb_id) : null,
+    name: json.name ?? json.title ?? null,
+    description: json.overview || null,
+    genres: (json.genres ?? []).map((g) => g.name),
+    poster: img(json.poster_path, 'w500'),
+    background: img(json.backdrop_path, 'w1280'),
+    logo: img(logo, 'w500'),
+    directors: people.directors,
+    writers: people.writers,
+    runtime: runtime ? `${runtime} min` : null,
+    status: json.status || null,
+    country: json.production_countries?.[0]?.name ?? json.origin_country?.[0] ?? null,
+    certification: usRating || null,
+    rating: json.vote_count ? { value: Math.round(json.vote_average * 10) / 10, votes: json.vote_count } : null,
+    cast,
+    seasonPosters: Object.fromEntries((json.seasons ?? []).filter((s) => s.poster_path).map((s) => [s.season_number, img(s.poster_path, 'w342')])),
+    recommendations: (json.recommendations?.results ?? []).slice(0, 10).map((r) => ({ tmdbId: String(r.id), type: r.media_type === 'movie' || movie ? 'movie' : 'tv', name: r.name ?? r.title })),
+  };
+}
+
+/** TMDB season -> episode fills keyed by episode number. */
+export function normalizeTmdbSeason(json) {
+  const out = {};
+  for (const e of json?.episodes ?? []) {
+    out[e.episode_number] = { name: e.name || null, overview: e.overview || null, thumbnail: img(e.still_path, 'w300'), released: e.air_date ? `${e.air_date}T00:00:00.000Z` : null };
+  }
+  return out;
+}

package/src/byok/tvdb.js

@@ -0,0 +1,165 @@
+// TVDB v4, called from the caller's process. POST /login with the key (and optional
+// subscriber PIN) returns a bearer token, kept in memory for this process (or tab) and reused; a 401 later means the token
+// expired, so the client logs in once more and retries.
+import { ByokError, providerFetch, qs } from './http.js';
+
+const BASE = 'https://api4.thetvdb.com/v4';
+const MAX_EPISODE_PAGES = 25; // ~12,500 episodes at TVDB's 500 per page
+// hash(key, pin) -> Promise<token>; memory only, never persisted, never keyed by the raw key.
+const tokens = new Map();
+
+/** FNV-1a, enough to key the token map without holding the key itself as a map key. */
+function slotOf(key, pin) {
+  let h = 0x811c9dc5;
+  for (const ch of `${key}\u0000${pin}`) {
+    h ^= ch.codePointAt(0);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return `${h.toString(36)}:${key.length}:${pin.length}`;
+}
+
+export function forgetTvdbTokens() {
+  tokens.clear();
+}
+
+export function createTvdb({ key, pin = '', fetch: f = globalThis.fetch.bind(globalThis), timeoutMs } = {}) {
+  const k = String(key ?? '').trim();
+  const p = String(pin ?? '').trim();
+  if (!k) throw new ByokError('tvdb', 'invalid_key', 'No TVDB key set.');
+  const slot = slotOf(k, p);
+
+  function login(signal, fresh = false) {
+    if (fresh) tokens.delete(slot);
+    if (!tokens.has(slot)) {
+      const pending = providerFetch('tvdb', `${BASE}/login`, {
+        fetch: f, signal, timeoutMs, method: 'POST', body: p ? { apikey: k, pin: p } : { apikey: k },
+      }).then((d) => {
+        const token = d?.data?.token;
+        if (!token) throw new ByokError('tvdb', 'bad_response', 'TVDB did not return a token.');
+        return token;
+      });
+      // A failed login must not be cached.
+      pending.catch(() => tokens.delete(slot));
+      tokens.set(slot, pending);
+    }
+    return tokens.get(slot);
+  }
+
+  async function get(path, params = {}, signal) {
+    const run = async (fresh) => {
+      const token = await login(signal, fresh);
+      return providerFetch('tvdb', `${BASE}${path}${qs(params)}`, { fetch: f, signal, timeoutMs, headers: { Authorization: `Bearer ${token}` } });
+    };
+    try {
+      return await run(false);
+    } catch (e) {
+      if (e instanceof ByokError && e.code === 'invalid_key' && e.status === 401) return run(true);
+      throw e;
+    }
+  }
+
+  const enc = encodeURIComponent;
+  return {
+    check: async (signal) => { await login(signal, true); return { ok: true }; },
+    seriesExtended: (id, signal) => get(`/series/${enc(id)}/extended`, { meta: 'translations' }, signal),
+    movieExtended: (id, signal) => get(`/movies/${enc(id)}/extended`, { meta: 'translations' }, signal),
+    episodes: (id, season, signal) => get(`/series/${enc(id)}/episodes/default/eng`, { page: 0, season }, signal),
+    /** English (or `lang`) name, overview and aliases of a series or movie. */
+    translation: (id, { lang = 'eng', kind = 'series' } = {}, signal) => get(`/${kind === 'movie' ? 'movies' : 'series'}/${enc(id)}/translations/${enc(lang)}`, {}, signal),
+    artworks: (id, signal) => get(`/series/${enc(id)}/artworks`, {}, signal),
+    /** IMDb id → TVDB search hits. */
+    searchRemoteId: (remoteId, signal) => get(`/search/remoteid/${enc(remoteId)}`, {}, signal),
+    /**
+     * Every episode of an order ('official', 'default', 'absolute', 'dvd'), all pages, names
+     * and overviews in `lang` (the language-suffixed endpoint translates in bulk; the
+     * /extended episode list never does). Episodes keep absoluteNumber.
+     */
+    async allEpisodes(id, { order = 'official', lang = 'eng', signal } = {}) {
+      const out = [];
+      for (let page = 0; page < MAX_EPISODE_PAGES; page++) {
+        const body = await get(`/series/${enc(id)}/episodes/${enc(order)}/${enc(lang)}`, { page }, signal);
+        const eps = body?.data?.episodes ?? [];
+        out.push(...eps);
+        if (!eps.length || !body?.links?.next) break;
+      }
+      return out;
+    },
+  };
+}
+
+/**
+ * "S{season}E{number}" → TVDB absolute number. TVDB's absoluteNumber already accounts for
+ * specials interleaved into the run, so it beats summing season lengths. Pure.
+ */
+export function episodeAbsoluteMap(episodes) {
+  const out = {};
+  for (const ep of episodes ?? []) {
+    if (!ep?.seasonNumber || !ep.number || !ep.absoluteNumber) continue;
+    out[`S${ep.seasonNumber}E${ep.number}`] = ep.absoluteNumber;
+  }
+  return out;
+}
+
+// Artwork type ids: series poster/background/clear logo, then the movie ones.
+const ART_TYPES = { series: { poster: 2, background: 3, logo: 23 }, movie: { poster: 14, background: 15, logo: 25 } };
+
+/**
+ * TVDB's best poster, background and logo. Posters prefer English, then textless, then
+ * the highest score; backgrounds prefer textless; logos are English or textless only (a
+ * logo is the title as text). Pure.
+ */
+export function pickTvdbArt(artworks, { movie = false, fallbackPoster = null } = {}) {
+  const types = ART_TYPES[movie ? 'movie' : 'series'];
+  const list = artworks ?? [];
+  const best = (type, langs) => {
+    const rank = (a) => {
+      const i = langs.indexOf(a.language ?? null);
+      return i === -1 ? langs.length : i;
+    };
+    return list
+      .filter((a) => a.type === type && a.image && (langs.includes(a.language ?? null) || langs.includes('*')))
+      .sort((a, b) => (rank(a) - rank(b)) || ((b.score || 0) - (a.score || 0)))[0]?.image ?? null;
+  };
+  return {
+    poster: best(types.poster, ['eng', null, '*']) ?? fallbackPoster ?? null,
+    background: best(types.background, [null, 'eng', '*']),
+    logo: best(types.logo, ['eng', null]),
+  };
+}
+
+/** TVDB series extended -> the fields our Title uses. Pure. */
+export function normalizeTvdb(json) {
+  const d = json?.data;
+  if (!d) return null;
+  const eng = (list) => list?.find((t) => t.language === 'eng');
+  const art = pickTvdbArt(d.artworks, { fallbackPoster: d.image ?? null });
+  const posters = {};
+  for (const s of d.seasons ?? []) if (s.type?.type === 'official' && s.image && !(s.number in posters)) posters[s.number] = s.image;
+  return {
+    tvdbId: String(d.id),
+    name: eng(d.translations?.nameTranslations)?.name ?? null,
+    description: eng(d.translations?.overviewTranslations)?.overview ?? null,
+    genres: (d.genres ?? []).map((g) => g.name),
+    poster: art.poster,
+    background: art.background,
+    logo: art.logo,
+    runtime: d.averageRuntime ? `${d.averageRuntime} min` : null,
+    status: d.status?.name ?? null,
+    country: d.originalCountry ? d.originalCountry.toUpperCase() : null,
+    // TVDB has no user rating; its "score" is a popularity count, shown as such.
+    score: Number.isFinite(d.score) ? d.score : null,
+    cast: (d.characters ?? []).filter((c) => c.peopleType === 'Actor').slice(0, 24)
+      .map((c) => ({ name: c.personName, character: c.name || null, photo: c.personImgURL || c.image || null })),
+    seasonPosters: posters,
+  };
+}
+
+/** TVDB episodes page -> episode fills keyed by episode number, for one season. */
+export function normalizeTvdbEpisodes(json, season) {
+  const out = {};
+  for (const e of json?.data?.episodes ?? []) {
+    if (e.seasonNumber !== season) continue;
+    out[e.number] = { name: e.name || null, overview: e.overview || null, thumbnail: e.image || null, released: e.aired ? `${e.aired}T00:00:00.000Z` : null };
+  }
+  return out;
+}

package/src/cache.js

@@ -0,0 +1,82 @@
+// Response cache for API (and keyless provider) answers. Hits and misses are both cached;
+// misses (null, [], a 404) for a shorter time so a new entry shows up soon.
+//
+// `cache` option:
+//   undefined          in memory, ttlMs 1 h, missTtlMs 5 min, max 5000 items
+//   false | 0          off
+//   { ttlMs, missTtlMs, max }   in memory with those limits (ttlMs 0 turns it off)
+//   store              your own: { get(key), set(key, value, ttlMs), delete?(key), clear?() },
+//                      sync or async. Values are JSON-serialisable; expiry is the store's job.
+
+export const DEFAULT_TTL_MS = 60 * 60 * 1000;
+export const DEFAULT_MISS_TTL_MS = 5 * 60 * 1000;
+export const DEFAULT_MAX = 5000;
+
+const isStore = (o) => o && typeof o.get === 'function' && typeof o.set === 'function';
+
+/** Bounded in-memory store with per-item expiry (oldest evicted first). */
+export function memoryStore({ max = DEFAULT_MAX, now = () => Date.now() } = {}) {
+  const map = new Map();
+  return {
+    get(key) {
+      const hit = map.get(key);
+      if (!hit) return undefined;
+      if (hit.expires <= now()) { map.delete(key); return undefined; }
+      return hit.value;
+    },
+    set(key, value, ttlMs) {
+      map.delete(key);
+      map.set(key, { value, expires: now() + ttlMs });
+      if (map.size > max) map.delete(map.keys().next().value);
+    },
+    delete(key) { map.delete(key); },
+    clear() { map.clear(); },
+    get size() { return map.size; },
+  };
+}
+
+/** A missing answer: cached for missTtlMs instead of ttlMs. */
+export const isMiss = (v) => v === null || v === undefined || (Array.isArray(v) && v.length === 0)
+  || (Array.isArray(v?.results) && v.results.length === 0);
+
+/**
+ * Normalise the option into { get(key) → Promise<{ value } | null>, set(key, value), clear() }.
+ * Values are wrapped so a cached null (a miss) differs from "not cached".
+ */
+export function createResponseCache(option, { cacheTtlMs } = {}) {
+  let ttlMs = DEFAULT_TTL_MS;
+  let missTtlMs = DEFAULT_MISS_TTL_MS;
+  let store;
+  if (cacheTtlMs !== undefined && option === undefined) option = cacheTtlMs ? { ttlMs: Number(cacheTtlMs) } : false;
+  if (option === false || option === 0 || option === null) return disabled();
+  if (isStore(option)) {
+    store = option;
+  } else {
+    const o = option ?? {};
+    if (o.ttlMs !== undefined) ttlMs = Number(o.ttlMs);
+    if (o.missTtlMs !== undefined) missTtlMs = Number(o.missTtlMs);
+    else missTtlMs = Math.min(missTtlMs, ttlMs);
+    if (!ttlMs) return disabled();
+    store = isStore(o.store) ? o.store : memoryStore({ max: o.max ?? DEFAULT_MAX });
+  }
+  return {
+    async get(key) {
+      try {
+        const hit = await store.get(key);
+        return hit && typeof hit === 'object' && 'v' in hit ? { value: hit.v } : null;
+      } catch {
+        return null;
+      }
+    },
+    async set(key, value) {
+      try { await store.set(key, { v: value }, isMiss(value) ? missTtlMs : ttlMs); } catch { /* a cache failure never fails a call */ }
+    },
+    async clear() {
+      try { await store.clear?.(); } catch { /* ignore */ }
+    },
+  };
+}
+
+function disabled() {
+  return { get: async () => null, set: async () => {}, clear: async () => {} };
+}