@vanomarb/animap 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,269 @@
-# Temporary Holding Version
+# AniMap
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The JavaScript client for AniMap, the anime id mapping API. AniMap maps
+anime-database entries (Kitsu, MyAnimeList, AniList, AniDB: one entry per season
+or part) to series databases (TVDB, TMDB, IMDb), with season and episode ranges,
+and serves whole titles in Cinemeta format:
+
+    kitsu:44607 episode 7  ⇄  tvdb:342329 S1E85  ⇄  tt8948436 S1E85
+
+The client can also fill titles with data from TMDB, TVDB and Fanart.tv using
+**your own keys, inside your own process**. It has no dependencies, ships as ESM
+with TypeScript types, and runs on Node 18+ and in browsers.
+
+## Install
+
+```sh
+npm install @vanomarb/animap
+```
+
+## API key
+
+Every request to the API needs a key (`amk_live_…`). Ask the operator of the
+server you use; an admin creates keys on the web UI's Admin page or with
+`POST /v1/keys`. The secret is shown once.
+
+## Quickstart
+
+```js
+import { Client } from '@vanomarb/animap';
+
+const client = new Client({ apiKey: process.env.ANIMAP_KEY, baseUrl: 'https://animap.example.com' });
+
+await client.toSeries('kitsu:44607', 7, { target: 'imdb' });
+// { provider: 'imdb', id: 'tt8948436', season: 1, episode: 85, span: 1, source: 'anibridge', confidence: 'inferred' }
+
+const title = await client.title('kitsu:44607');   // the whole show, id "tt8948436"
+```
+
+`AniMap` and `AniMapError` are the same classes as `Client` and
+`ClientError`; use whichever reads better:
+
+```js
+import { AniMap } from '@vanomarb/animap';
+const animap = new AniMap({ apiKey: process.env.ANIMAP_KEY, baseUrl: 'https://animap.example.com' });
+```
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `apiKey` | required | Sent as `X-API-Key`. |
+| `baseUrl` | required | API origin; a trailing `/v1` is fine. |
+| `timeoutMs` | `10000` | Per API attempt. |
+| `retry` | `{ max: 1, maxWaitMs: 10000 }` | Retries network errors, 429 (after `Retry-After`, at most `maxWaitMs`) and 502–504. `false`: one attempt. |
+| `breaker` | `{ threshold: 5, cooldownMs: 30000 }` | Per API key. See [Failures](#failures-and-fallbacks). `false` turns it off. |
+| `cache` | 1 h hits, 5 min misses, 5000 items | `{ ttlMs, missTtlMs, max }`, your own store (below), or `false`. |
+| `fetch` | global `fetch` | Used for the API and every provider. |
+| `providers` | none | Provider keys and keyless providers, see [BYOK](#bring-your-own-keys-byok). |
+| `providerCache` | in memory | Where provider results are kept (7 days). |
+| `providerTimeoutMs` | `8000` | Per provider request. |
+| `onProviderError` | none | `(error) => void` for each provider failure. |
+
+A cache store is any object with `get(key)` and `set(key, value, ttlMs)`, and
+optionally `delete(key)` and `clear()`. The methods can be synchronous or return
+promises, so a Redis adapter works. Values are JSON-serialisable.
+
+## Failures and fallbacks
+
+`null` (or `[]`) means **the API answered and does not know it**. If the API
+**could not answer**, the call throws a `ClientError` with code `unavailable` and
+a `reason`: `network_error`, `timeout`, `rate_limited`, `server_error` or
+`circuit_open`. Use the second case to fall back to another source:
+
+```js
+import { ClientError } from '@vanomarb/animap';
+
+try {
+  const entry = await client.entry('kitsu:44607');   // null: unknown entry
+} catch (err) {
+  if (err instanceof ClientError && err.code === 'unavailable') { /* use your own data */ }
+  else throw err;
+}
+```
+
+**Circuit breaker.** After `threshold` consecutive failures for one API key
+(network errors, timeouts, 5xx, 429), the client stops calling the API for
+`cooldownMs`. During that time calls throw at once with reason `circuit_open`
+and `retryAfterMs`. A 429 opens the circuit straight away, for its
+`Retry-After`. Pauses never last longer than 5 minutes. `client.pausedFor`
+gives the milliseconds remaining.
+
+The other codes are the server's (`unauthorized`, `forbidden`, `not_found`,
+`bad_request`, with `details` on validation errors) and client-side ones
+(`missing_api_key`, `missing_base_url`, `invalid_ref`, `invalid_argument`,
+`invalid_response`). The client checks refs before sending anything.
+
+## One client, many API keys
+
+```js
+const forUser = client.withApiKey(userKey);   // shares cache, providers and breaker map
+```
+
+Use this when your users bring their own API key. Breaker state is kept per key.
+
+## Refs
+
+`kitsu:44607`, `mal:42496`, `anilist:129347`, `anidb:16201`, `tvdb:342329`,
+`tmdb:76572`, and IMDb ids bare (`tt8948436`; `imdb:tt8948436` also works).
+Title methods also take a title id and `tmdb:movie:<id>`.
+
+## Entries and mapping
+
+```js
+await client.entry('kitsu:44607');                  // Entry | null
+await client.lookup(['kitsu:44607', 'mal:1']);      // Map<ref as given, Entry | null>, batches of 100
+await client.toSeries('kitsu:44607', 7, { target: 'tvdb' });
+// { provider, id, season, episode, span, source, confidence } | null
+await client.fromSeries('tt8948436', 1, 85);        // [{ entry, ids, episode, source, confidence }]
+await client.series('tvdb:342329', { season: 1 });  // { series, title, images, seasons: [{ season, length, rows, issues }] }
+await client.search('soul land', { limit: 5 });     // EntrySummary[]
+await client.issues({ entry: 'kitsu:44607', type: 'count' }); // { results: Issue[], next }
+await client.history('anilist:129347');             // Revision[], newest first
+```
+
+An Entry has `id`, `ids`, `title`, `titles`, `format`, `episodes`, `year`,
+`tags`, `score`, `series` (`tvdb`/`tmdb`/`imdb`), `images` and `ranges`. A range
+maps entry episodes `from`–`to` to `targetFrom`–`targetTo` of `season` (`0` =
+specials, `null` = absolute numbering). `ratio` is the number of target episodes
+per entry episode.
+
+```js
+import { alignToEntry } from '@vanomarb/animap';
+alignToEntry(entry.ranges, 'cinemeta');   // { season: 1, offset: 78, end: 91, target: 'imdb' } | null
+```
+
+`alignToEntry` gives where a 1:1 entry sits in a series: series episode = entry
+episode + `offset`. A target with no 1:1 range of its own borrows another
+target's.
+
+## Titles
+
+A title is a whole show or film, with a Cinemeta-format id: `tt…`, else
+`kitsu:<id>`, `tmdb:<id>`, `tvdb:<id>`.
+
+```js
+await client.title('kitsu:44607');            // Title | null (enriched when you set provider keys)
+await client.title('tt8948436', { enrich: false });
+await client.titleEpisodes('tt8948436', { season: 1 });
+// { season: 1, seasons: [1, 0], episodes: [{ season, episode, name, overview, released, thumbnail, runtime, rating, mapped }] }
+await client.titles({ q: 'soul land', type: 'series', genre: 'Action', sort: 'popular', limit: 24 });
+// { results: TitleSummary[], total, next } — pass `next` back as `cursor`
+await client.trending({ limit: 12 });         // TitleSummary[]
+await client.activity({ limit: 20 });         // recent mapping edits
+await client.stats();                         // { titles, entries, mappedEpisodes, ranges, sources, importedAt }
+await client.genres();                        // [{ name, count }]
+await client.meta();                          // dataset build and import info
+await client.me();                            // the API key in use
+```
+
+A Title has `name`, `originalName`, `description`, `genres`, `year`,
+`releaseInfo`, `released`, `status`, `runtime`, `country`, `certification`,
+`poster`, `background`, `logo`, `ratings` (one per source, never merged),
+`cast`, `directors`, `writers`, `seasons`, `entries` (each with its best range),
+`coverage`, `similar` and `provenance` (which source filled each field).
+
+## Bring your own keys (BYOK)
+
+```js
+const client = new Client({
+  apiKey, baseUrl,
+  providers: {
+    tmdb: { key: process.env.TMDB_KEY },                  // v3 key or v4 read token
+    tvdb: { key: process.env.TVDB_KEY, pin: process.env.TVDB_PIN },
+    fanart: { key: process.env.FANART_KEY },
+  },
+  providerCache: localStorage,                            // in a browser; in memory by default
+});
+```
+
+**Your keys stay in your process.** The client calls TMDB, TVDB and Fanart.tv
+itself, from your server or the user's browser. A key goes only to its own
+provider, never to the mapping API, and never into logs, error messages or the
+cache. Without provider keys the client behaves exactly as if BYOK did not exist.
+
+`title()` and `titleEpisodes()` fill **only what the API left empty**:
+
+| Field | Filled from |
+|---|---|
+| description, genres, runtime, status, country, certification, directors, writers | TMDB, then TVDB |
+| poster, background, logo | TMDB, then TVDB, then Fanart.tv |
+| `ratings.tmdb` / `ratings.tvdb` | TMDB's own rating, TVDB's own score (each provider only its own card) |
+| cast | TMDB, then TVDB, when the API has none; otherwise only missing photos |
+| season posters | TMDB, then TVDB |
+| `similar` | TMDB recommendations that exist in the catalogue, after the API's own |
+| episode names (placeholders such as "Episode 5"), overviews, stills, air dates | TMDB, then TVDB |
+
+`provenance` names the provider of every filled field. Results are cached for
+7 days per title, keyed by which providers have keys, never by the keys
+themselves. Failures that may pass on their own (network, rate limit) are not
+cached. A provider failure never fails the call: it is passed to
+`onProviderError`, and `enrichTitle()` returns it in `errors`.
+
+```js
+const { title, filled, errors } = await client.enrichTitle(apiTitle);
+const { episodes, filledBy } = await client.enrichEpisodes(apiTitle, 1, rows);
+await client.checkProvider('tvdb');   // { state: 'connected' | 'invalid' | 'rate_limited' | 'error' | 'missing', message }
+```
+
+### Provider clients
+
+To work with raw provider data, use the provider clients. Each returns the
+provider's own JSON. The last argument of every method is an optional
+`AbortSignal`. A provider without a key is `null`.
+
+```js
+client.providers.tmdb.series('76572');          // /tv/{id} + aggregate_credits, recommendations, external_ids, content_ratings, images
+client.providers.tmdb.movie('129');             // /movie/{id} + credits, recommendations, external_ids, release_dates, images
+client.providers.tmdb.season('76572', 1);       // /tv/{id}/season/{n}
+client.providers.tmdb.findByImdb('tt8948436');  // /find/{imdb}
+client.providers.tmdb.search('Soul Land', { type: 'tv', year: 2018 });
+
+client.providers.tvdb.series('342329');         // /series/{id}/extended (translations)
+client.providers.tvdb.movie('1');               // /movies/{id}/extended
+client.providers.tvdb.allEpisodes('342329');    // every page, English names, absoluteNumber kept
+client.providers.tvdb.episodes('342329', 1);    // one season, first page
+client.providers.tvdb.translation('342329');    // English name, overview, aliases
+client.providers.tvdb.artworks('342329');
+client.providers.tvdb.searchRemoteId('tt8948436');
+
+client.providers.fanart.series('342329');       // by TVDB id
+client.providers.fanart.movie('129');           // by TMDB id
+```
+
+TVDB logs in once per key and PIN and keeps the token in memory. If a token
+expires (401), the client logs in again and retries.
+
+The **keyless** Kitsu and Cinemeta clients are on by default. They go through
+the response cache. Turn one off with `providers: { kitsu: false }`.
+
+```js
+await client.providers.kitsu.anime('44607');
+// { id, titles: { canonical, en, romaji, native, synonyms, abbreviated }, status, startDate, endDate,
+//   episodeCount, subtype, posterImage, coverImage, averageRating (0–100), rating (0–10), userCount, categories, … } | null
+await client.providers.kitsu.episodes('44607');       // [{ number, seasonNumber, title, airdate, thumbnail, … }]
+await client.providers.kitsu.relationships('42037');  // [{ role: 'prequel' | 'sequel' | 'side_story' | …, id, subtype, … }]
+await client.providers.kitsu.search('soul land');
+await client.providers.cinemeta.meta('tt8948436', 'series');   // raw Cinemeta meta with videos, or null
+await client.providers.cinemeta.find('tt0119698');             // { type, meta }, trying the other type too
+```
+
+Some Kitsu quirks are handled for you:
+- Genres come from Kitsu's categories; its `genres` field is always empty.
+- Missing titles do not break anything.
+- `airdate` stays `null` until Kitsu knows the real date. Kitsu's `createdAt`, set when an episode is only planned, is never used as an air date.
+
+### Building blocks
+
+The `@vanomarb/animap/byok` entry exports the pieces behind all this, for
+apps that manage their own state, such as React hooks:
+- clients: `createTmdb`, `createTvdb`, `createFanart`
+- normalizers: `normalizeTmdb`, `normalizeTvdb`, `normalizeFanart`, `tmdbTvPeople`, `pickTvdbArt`, `bestFanart`, `episodeAbsoluteMap`
+- merge: `mergeTitle`, `mergeEpisodes`
+- fetching and key checks: `fetchSources`, `fetchEpisodeFills`, `checkKey`
+- cache: `createByokCache`, `memoryStorage`
+- errors: `ByokError`
+
+## Licence
+
+MIT

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@vanomarb/animap",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "AniMap client: map Kitsu, MAL, AniList and AniDB entries to TVDB, TMDB and IMDb seasons and episodes, read titles and episodes, and enrich them in-process with your own TMDB, TVDB and Fanart.tv keys.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./byok": {
+      "types": "./src/byok/index.d.ts",
+      "default": "./src/byok/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "keywords": [
+    "anidb",
+    "anilist",
+    "animap",
+    "anime",
+    "cinemeta",
+    "fanart",
+    "imdb",
+    "kitsu",
+    "mapping",
+    "myanimelist",
+    "stremio",
+    "tmdb",
+    "tvdb"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false
+}

package/src/align.js

@@ -0,0 +1,46 @@
+// Where an entry sits inside a series, for 1:1 numbering: series episode = entry episode +
+// offset, in `season`, up to `end`. Pure.
+//
+// A target without a 1:1 range borrows another's slice, because aligning episode N to E N
+// and running the tail to the season's end is worse: Soul Land part 3 has TVDB and IMDb
+// ranges but no TMDB one, and would otherwise come out as all 264 episodes. Cinemeta
+// numbers like IMDb. Where numberings truly drift apart a caller should check air dates.
+
+const BORROW_ORDER = {
+  imdb: ['imdb', 'tvdb', 'tmdb'],
+  cinemeta: ['imdb', 'tvdb', 'tmdb'],
+  tvdb: ['tvdb', 'imdb', 'tmdb'],
+  tmdb: ['tmdb', 'tvdb', 'imdb'],
+};
+
+/** Manual ranges for a target replace that target's imported ones (contract). */
+function effective(ranges) {
+  const manual = new Set(ranges.filter((r) => r.source === 'manual').map((r) => r.target));
+  return manual.size ? ranges.filter((r) => r.source === 'manual' || !manual.has(r.target)) : ranges;
+}
+
+/** Per target, the first 1:1 range by entry episode → { season, offset, end, from, to }. */
+export function slicesFromRanges(ranges) {
+  const out = {};
+  for (const r of [...effective(ranges ?? [])].sort((a, b) => a.from - b.from)) {
+    if (out[r.target] || Number(r.ratio) !== 1) continue;
+    out[r.target] = { season: r.season ?? null, offset: r.targetFrom - r.from, end: r.targetTo, from: r.from, to: r.to };
+  }
+  return out;
+}
+
+/**
+ * ranges: an Entry's ranges. target: 'tvdb' | 'tmdb' | 'imdb' | 'cinemeta'.
+ * Returns { season, offset, end, target } (target = the slice actually used, which may be
+ * borrowed), or null when the entry has no 1:1 range at all.
+ */
+export function alignToEntry(ranges, target) {
+  const order = BORROW_ORDER[target];
+  if (!order) throw new TypeError(`target must be one of ${Object.keys(BORROW_ORDER).join(', ')}`);
+  const slices = slicesFromRanges(ranges);
+  for (const t of order) {
+    const s = slices[t];
+    if (s) return { season: s.season, offset: s.offset, end: s.end, target: t };
+  }
+  return null;
+}

package/src/breaker.js

@@ -0,0 +1,38 @@
+// Circuit breaker per API key: after `threshold` consecutive failures (network errors,
+// timeouts, 5xx, 429) the client stops calling the API for a cooldown and fails fast with
+// code "unavailable", reason "circuit_open". A 429 opens it at once for its Retry-After.
+// The cooldown is at least `cooldownMs`, honours Retry-After, and is capped at 5 minutes.
+
+export const MAX_COOLDOWN_MS = 5 * 60 * 1000;
+
+export function createBreakers({ threshold = 5, cooldownMs = 30_000, maxCooldownMs = MAX_COOLDOWN_MS, now = () => Date.now() } = {}) {
+  const states = new Map();
+  const state = (key) => {
+    if (!states.has(key)) states.set(key, { failures: 0, openUntil: 0 });
+    return states.get(key);
+  };
+  return {
+    /** Milliseconds until the API may be called again for this key; 0 when closed. */
+    openFor(key) {
+      const s = states.get(key);
+      return s ? Math.max(0, s.openUntil - now()) : 0;
+    },
+    success(key) {
+      states.delete(key);
+    },
+    /** `retryAfterMs` comes from a 429; it opens the breaker immediately. */
+    failure(key, retryAfterMs) {
+      const s = state(key);
+      s.failures++;
+      if (retryAfterMs !== undefined && retryAfterMs !== null) {
+        s.openUntil = now() + Math.min(Math.max(retryAfterMs, 1000), maxCooldownMs);
+      } else if (s.failures >= threshold) {
+        s.openUntil = now() + Math.min(cooldownMs, maxCooldownMs);
+      }
+    },
+  };
+}
+
+export function disabledBreakers() {
+  return { openFor: () => 0, success() {}, failure() {} };
+}

package/src/byok/cache.js

@@ -0,0 +1,66 @@
+// Cache of what the provider keys fetched (TMDB/TVDB/Fanart.tv), so a quota is spent once
+// a week per title. Keyed by title and by WHICH providers have keys, never by the key
+// itself. Storage is pluggable: anything with getItem/setItem/removeItem, synchronous
+// (localStorage) or returning promises (a Redis or file adapter). Clock is injected.
+
+export const DEFAULT_PREFIX = 'byok.v1';
+export const TTL_MS = 7 * 24 * 3600 * 1000;
+
+/** "tmdb+tvdb" from the keys that are set; '' when none. */
+export function keySignature(keys = {}) {
+  return ['tmdb', 'tvdb', 'fanart'].filter((p) => String(keys[p] ?? '').trim()).join('+');
+}
+
+/** A Storage-like object in memory, bounded so a long-running process does not grow forever. */
+export function memoryStorage({ maxItems = 2000 } = {}) {
+  const map = new Map();
+  return {
+    getItem: (k) => (map.has(k) ? map.get(k) : null),
+    setItem: (k, v) => {
+      map.delete(k);
+      map.set(k, String(v));
+      if (map.size > maxItems) map.delete(map.keys().next().value);
+    },
+    removeItem: (k) => { map.delete(k); },
+    clear: () => map.clear(),
+    get length() { return map.size; },
+  };
+}
+
+const isPromise = (v) => v && typeof v.then === 'function';
+
+/**
+ * get() and set() return plain values for a synchronous storage and promises for an
+ * asynchronous one, so `await` works either way. Storage failures never throw.
+ */
+export function createByokCache({ storage = memoryStorage(), prefix = DEFAULT_PREFIX, now = () => Date.now(), ttl = TTL_MS } = {}) {
+  const slot = (kind, id, sig) => `${prefix}:${kind}:${id}:${sig}`;
+  const read = (key, raw) => {
+    if (!raw) return null;
+    const v = JSON.parse(raw);
+    if (!v || now() - v.at > ttl) {
+      try { const r = storage.removeItem(key); if (isPromise(r)) r.catch(() => {}); } catch { /* ignore */ }
+      return null;
+    }
+    return v.data;
+  };
+  return {
+    get(kind, id, sig) {
+      const key = slot(kind, id, sig);
+      try {
+        const raw = storage.getItem(key);
+        if (isPromise(raw)) return raw.then((r) => read(key, r)).catch(() => null);
+        return read(key, raw);
+      } catch {
+        return null;
+      }
+    },
+    set(kind, id, sig, data) {
+      try {
+        const r = storage.setItem(slot(kind, id, sig), JSON.stringify({ at: now(), data }));
+        if (isPromise(r)) return r.catch(() => {});
+      } catch { /* storage full: skip caching, the caller still works */ }
+      return undefined;
+    },
+  };
+}

package/src/byok/enrich.js

@@ -0,0 +1,99 @@
+// Fetch what the caller's own provider keys can add to a title. Dependencies are injected
+// (fetch for the providers, findTitle for the mapping API) so tests can drive it.
+import { ByokError } from './http.js';
+import { createTmdb, normalizeTmdb, normalizeTmdbSeason } from './tmdb.js';
+import { createTvdb, normalizeTvdb, normalizeTvdbEpisodes } from './tvdb.js';
+import { createFanart, fanartTarget, normalizeFanart } from './fanart.js';
+
+const has = (v) => String(v ?? '').trim().length > 0;
+
+function errorOf(e, provider) {
+  if (e instanceof ByokError) return { provider: e.provider, code: e.code, message: e.message };
+  return { provider, code: 'bad_response', message: 'Unexpected response.' };
+}
+
+/**
+ * keys: { tmdb, tvdb, tvdbPin, fanart }.
+ * findTitle(ref) -> TitleSummary | null, resolving a provider id to one of our titles.
+ * Returns { sources: { tmdb, tvdb, fanart, similar }, errors: [] } with normalized payloads.
+ */
+export async function fetchSources(title, keys, { fetch, findTitle, signal } = {}) {
+  const errors = [];
+  const sources = { tmdb: null, tvdb: null, fanart: null, similar: [] };
+  const movie = title.type === 'movie';
+  const ids = { ...(title.ids ?? {}) };
+
+  if (has(keys.tmdb)) {
+    try {
+      const tmdb = createTmdb({ key: keys.tmdb, fetch });
+      let id = ids.tmdb;
+      if (!id && ids.imdb) {
+        const found = await tmdb.findByImdb(ids.imdb, signal);
+        id = String((movie ? found.movie_results : found.tv_results)?.[0]?.id ?? '') || null;
+      }
+      if (id) {
+        sources.tmdb = normalizeTmdb(await (movie ? tmdb.movie(id, signal) : tmdb.tv(id, signal)), movie ? 'movie' : 'tv');
+        ids.tmdb = id;
+        if (!ids.tvdb && sources.tmdb?.tvdbId) ids.tvdb = sources.tmdb.tvdbId;
+      }
+    } catch (e) { errors.push(errorOf(e, 'tmdb')); }
+  }
+
+  const later = [];
+  if (has(keys.tvdb) && !movie && ids.tvdb) {
+    later.push((async () => {
+      try {
+        const tvdb = createTvdb({ key: keys.tvdb, pin: keys.tvdbPin, fetch });
+        sources.tvdb = normalizeTvdb(await tvdb.seriesExtended(ids.tvdb, signal));
+      } catch (e) { errors.push(errorOf(e, 'tvdb')); }
+    })());
+  }
+  const target = fanartTarget({ ...title, ids });
+  if (has(keys.fanart) && target) {
+    later.push((async () => {
+      try {
+        const fan = createFanart({ key: keys.fanart, fetch });
+        sources.fanart = normalizeFanart(await (target.kind === 'movie' ? fan.movie(target.id, signal) : fan.tv(target.id, signal)), target.kind);
+      } catch (e) { errors.push(errorOf(e, 'fanart')); }
+    })());
+  }
+  if (findTitle && sources.tmdb?.recommendations?.length) {
+    later.push((async () => {
+      const recs = sources.tmdb.recommendations.slice(0, 8);
+      const hits = await Promise.all(recs.map((r) => findTitle(`tmdb:${r.tmdbId}`).catch(() => null)));
+      sources.similar = hits.filter(Boolean);
+    })());
+  }
+  await Promise.all(later);
+  sources.ids = ids;
+  return { sources, errors };
+}
+
+/** Episode fills for one season: TMDB first, then TVDB. */
+export async function fetchEpisodeFills(title, season, keys, { fetch, signal, ids: knownIds } = {}) {
+  const ids = { ...(title.ids ?? {}), ...(knownIds ?? {}) };
+  const fills = [];
+  const errors = [];
+  if (has(keys.tmdb) && ids.tmdb && title.type !== 'movie') {
+    try { fills.push(['tmdb', normalizeTmdbSeason(await createTmdb({ key: keys.tmdb, fetch }).season(ids.tmdb, season, signal))]); } catch (e) { errors.push(errorOf(e, 'tmdb')); }
+  }
+  if (has(keys.tvdb) && ids.tvdb && title.type !== 'movie') {
+    try { fills.push(['tvdb', normalizeTvdbEpisodes(await createTvdb({ key: keys.tvdb, pin: keys.tvdbPin, fetch }).episodes(ids.tvdb, season, signal), season)]); } catch (e) { errors.push(errorOf(e, 'tvdb')); }
+  }
+  return { fills, errors };
+}
+
+/** Settings "Check": one cheap call to the provider itself. -> { state, message } */
+export async function checkKey(provider, keys, { fetch, signal } = {}) {
+  try {
+    if (provider === 'tmdb') await createTmdb({ key: keys.tmdb, fetch }).check(signal);
+    else if (provider === 'tvdb') await createTvdb({ key: keys.tvdb, pin: keys.tvdbPin, fetch }).check(signal);
+    else if (provider === 'fanart') await createFanart({ key: keys.fanart, fetch }).check(signal);
+    return { state: 'connected', message: null };
+  } catch (e) {
+    const err = errorOf(e, provider);
+    if (err.code === 'invalid_key') return { state: 'invalid', message: err.message };
+    if (err.code === 'rate_limited') return { state: 'rate_limited', message: err.message };
+    return { state: 'error', message: err.message };
+  }
+}

package/src/byok/fanart.js

@@ -0,0 +1,49 @@
+// Fanart.tv v3, called from the caller's process. The key travels as ?api_key=. Series are looked up by
+// their TVDB id, films by their TMDB id.
+import { ByokError, providerFetch, qs } from './http.js';
+
+const BASE = 'https://webservice.fanart.tv/v3';
+// A title Fanart.tv certainly knows (TVDB 81189, Breaking Bad), for checking a key.
+export const FANART_CHECK_TVDB_ID = '81189';
+
+export function createFanart({ key, fetch: f = globalThis.fetch.bind(globalThis), timeoutMs } = {}) {
+  const k = String(key ?? '').trim();
+  if (!k) throw new ByokError('fanart', 'invalid_key', 'No Fanart.tv key set.');
+  const get = (path, signal) => providerFetch('fanart', `${BASE}${path}${qs({ api_key: k })}`, { fetch: f, signal, timeoutMs });
+  return {
+    check: (signal) => get(`/tv/${FANART_CHECK_TVDB_ID}`, signal),
+    tv: (tvdbId, signal) => get(`/tv/${encodeURIComponent(tvdbId)}`, signal),
+    movie: (tmdbId, signal) => get(`/movies/${encodeURIComponent(tmdbId)}`, signal),
+  };
+}
+
+/** Which Fanart.tv lookup a title needs: TVDB id for series, TMDB id for films. */
+export function fanartTarget(title) {
+  if (title?.type === 'movie') return title.ids?.tmdb ? { kind: 'movie', id: title.ids.tmdb } : null;
+  return title?.ids?.tvdb ? { kind: 'tv', id: title.ids.tvdb } : null;
+}
+
+/**
+ * The best image of one kind: English first, then textless ("00" or empty), then anything
+ * for posters and backgrounds. Logos are English or textless only: a logo is the title as
+ * text. Ties go to the most-liked image. Pure.
+ */
+export function bestFanart(images, { textOnly = false } = {}) {
+  const rank = (img) => {
+    const lang = img.lang || '';
+    if (lang === 'en') return 0;
+    if (lang === '00' || lang === '') return 1;
+    return textOnly ? Infinity : 2;
+  };
+  return (images ?? [])
+    .filter((img) => img?.url && Number.isFinite(rank(img)))
+    .sort((a, b) => (rank(a) - rank(b)) || ((parseInt(b.likes, 10) || 0) - (parseInt(a.likes, 10) || 0)))[0]?.url ?? null;
+}
+
+/** Fanart.tv response -> poster, background and logo (HD logos and plain logos pooled). Pure. */
+export function normalizeFanart(json, kind) {
+  if (!json) return null;
+  return kind === 'movie'
+    ? { poster: bestFanart(json.movieposter), background: bestFanart(json.moviebackground), logo: bestFanart([...(json.hdmovielogo ?? []), ...(json.movielogo ?? [])], { textOnly: true }) }
+    : { poster: bestFanart(json.tvposter), background: bestFanart(json.showbackground), logo: bestFanart([...(json.hdtvlogo ?? []), ...(json.clearlogo ?? [])], { textOnly: true }) };
+}