@vanomarb/animap 0.0.0-stage → 1.0.0

package/src/providers/kitsu.js

@@ -0,0 +1,175 @@
+// Kitsu (keyless), called from the caller's own process. Pitfalls handled here, learned
+// in production:
+// - genres live in the `categories` relationship; the `genres` attribute is always empty;
+// - `abbreviatedTitles` (and `titles`) can be missing or null;
+// - an episode's `createdAt` is set when the episode is merely planned, so it is never
+//   used as an air date: `airdate` is null until Kitsu knows the real one;
+// - media-relationships pages at 10 by default and only one side of a prequel/sequel link
+//   may exist (a later part may name no prequel while the earlier one names it as sequel).
+import { providerFetch, qs } from '../byok/http.js';
+
+export const KITSU_API = 'https://kitsu.app/api/edge';
+const PAGE = 20;
+const MAX_EPISODES = 500;
+const EPISODE_CONCURRENCY = 5;
+const MAX_RELATION_PAGES = 5;
+
+
+/** Kitsu anime record (+ included categories) → { id, titles: {…labelled}, … }. Pure. */
+export function normalizeKitsuAnime(data, included = []) {
+  if (!data?.attributes) return null;
+  const a = data.attributes;
+  const t = a.titles ?? {};
+  const abbreviated = [...new Set((a.abbreviatedTitles ?? []).filter((x) => typeof x === 'string' && x.trim()))];
+  // Donghua and Korean entries carry their romanised and native titles under en_cn/zh_cn
+  // and en_kr/ko_kr instead of en_jp/ja_jp.
+  const en = t.en ?? t.en_us ?? null;
+  const romaji = t.en_jp ?? t.en_cn ?? t.en_kr ?? null;
+  const native = t.ja_jp ?? t.zh_cn ?? t.ko_kr ?? null;
+  const labelled = [a.canonicalTitle, en, romaji, native].filter(Boolean);
+  const synonyms = [...new Set(Object.values(t).filter((v) => typeof v === 'string' && v && !labelled.includes(v)))];
+  const categoryIds = new Set((data.relationships?.categories?.data ?? []).map((c) => c.id));
+  const categories = included
+    .filter((i) => i.type === 'categories' && (categoryIds.size === 0 || categoryIds.has(i.id)))
+    .map((i) => i.attributes?.title)
+    .filter(Boolean);
+  const avg = a.averageRating === null || a.averageRating === undefined ? null : Number(a.averageRating);
+  return {
+    id: String(data.id),
+    slug: a.slug ?? null,
+    titles: {
+      canonical: a.canonicalTitle ?? null,
+      en,
+      romaji,
+      native,
+      synonyms,
+      abbreviated,
+    },
+    synopsis: a.synopsis || a.description || null,
+    subtype: a.subtype ?? null,
+    showType: a.showType ?? null,
+    status: a.status ?? null,
+    startDate: a.startDate ?? null,
+    endDate: a.endDate ?? null,
+    nextRelease: a.nextRelease ?? null,
+    episodeCount: a.episodeCount ?? null,
+    episodeLength: a.episodeLength ?? null,
+    ageRating: a.ageRating ?? null,
+    nsfw: a.nsfw ?? null,
+    posterImage: a.posterImage ?? null,
+    coverImage: a.coverImage ?? null,
+    youtubeVideoId: a.youtubeVideoId || null,
+    /** Kitsu's 0–100 average, as a number. */
+    averageRating: Number.isFinite(avg) ? avg : null,
+    /** The same on a 0–10 scale, one decimal. */
+    rating: Number.isFinite(avg) ? Math.round(avg) / 10 : null,
+    userCount: a.userCount ?? null,
+    popularityRank: a.popularityRank ?? null,
+    categories,
+  };
+}
+
+/** Kitsu episode → { number, seasonNumber, title, … }. Pure. */
+export function normalizeKitsuEpisode(a) {
+  return {
+    number: a.number,
+    seasonNumber: a.seasonNumber || 1,
+    relativeNumber: a.relativeNumber ?? null,
+    title: a.canonicalTitle || a.titles?.en || a.titles?.en_us || a.titles?.en_jp || null,
+    titles: a.titles ?? {},
+    synopsis: a.synopsis || a.description || null,
+    airdate: a.airdate || null,
+    length: a.length ?? null,
+    thumbnail: a.thumbnail?.original ?? null,
+  };
+}
+
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    while (next < items.length) {
+      const i = next++;
+      out[i] = await fn(items[i], i);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return out;
+}
+
+export function createKitsu({ fetch, timeoutMs = 10_000, baseUrl = KITSU_API } = {}) {
+  const get = (path, params, signal) => providerFetch('kitsu', `${baseUrl}${path}${qs(params ?? {})}`, {
+    fetch, signal, timeoutMs, headers: { Accept: 'application/vnd.api+json' },
+  });
+  const orNull = async (p) => {
+    try { return await p; } catch (e) { if (e.code === 'not_found') return null; throw e; }
+  };
+
+  return {
+    /** One anime with labelled titles and categories, or null when Kitsu has no such id. */
+    async anime(id, signal) {
+      const body = await orNull(get(`/anime/${encodeURIComponent(id)}`, { include: 'categories', 'fields[categories]': 'title' }, signal));
+      return body ? normalizeKitsuAnime(body.data, body.included ?? []) : null;
+    },
+
+    /**
+     * Every episode, sorted by number (at most `max`). The first page gives the total, the
+     * rest are fetched a few at a time; a failed page ends the list there.
+     */
+    async episodes(id, { max = MAX_EPISODES, signal } = {}) {
+      const page = (offset) => get('/episodes', { 'filter[media_id]': id, 'page[limit]': PAGE, 'page[offset]': offset, sort: 'number' }, signal);
+      const first = await orNull(page(0));
+      if (!first) return [];
+      const pages = [first.data ?? []];
+      const total = Math.min(Number(first.meta?.count) || 0, max);
+      if (first.links?.next && total > PAGE) {
+        const offsets = [];
+        for (let o = PAGE; o < total; o += PAGE) offsets.push(o);
+        const rest = await mapLimit(offsets, EPISODE_CONCURRENCY, (o) => page(o).then((r) => r.data ?? []).catch(() => null));
+        for (const p of rest) {
+          if (!p?.length) break;
+          pages.push(p);
+        }
+      }
+      return pages.flat().filter((e) => e.attributes?.number).map((e) => normalizeKitsuEpisode(e.attributes)).slice(0, max);
+    },
+
+    /**
+     * Media relationships of an anime: [{ role: 'prequel' | 'sequel' | 'side_story' | …,
+     * id, type, subtype, title, episodeCount, status, startDate }].
+     */
+    async relationships(id, signal) {
+      const out = [];
+      for (let p = 0; p < MAX_RELATION_PAGES; p++) {
+        const body = await get('/media-relationships', {
+          'filter[source_id]': id, 'filter[source_type]': 'Anime', include: 'destination', 'page[limit]': PAGE, 'page[offset]': p * PAGE,
+        }, signal);
+        const included = body.included ?? [];
+        for (const link of body.data ?? []) {
+          const dest = link.relationships?.destination?.data;
+          if (!dest?.id) continue;
+          const attrs = included.find((i) => i.id === dest.id && i.type === dest.type)?.attributes ?? {};
+          out.push({
+            role: link.attributes?.role ?? null,
+            id: String(dest.id),
+            type: dest.type,
+            subtype: attrs.subtype ?? null,
+            title: attrs.canonicalTitle ?? null,
+            titles: attrs.titles ?? {},
+            episodeCount: attrs.episodeCount ?? null,
+            status: attrs.status ?? null,
+            startDate: attrs.startDate ?? null,
+          });
+        }
+        if (!body.links?.next || (body.data ?? []).length < PAGE) break;
+      }
+      return out;
+    },
+
+    /** Text search, Kitsu's relevance order. */
+    async search(text, { limit = 5, signal } = {}) {
+      const body = await get('/anime', { 'filter[text]': text, 'page[limit]': Math.min(Math.max(1, limit), 20) }, signal);
+      return (body.data ?? []).map((d) => normalizeKitsuAnime(d)).filter(Boolean);
+    },
+  };
+}

package/src/refs.js

@@ -0,0 +1,58 @@
+import { ClientError } from './errors.js';
+
+export const ANIME_PROVIDERS = ['kitsu', 'mal', 'anilist', 'anidb'];
+export const SERIES_PROVIDERS = ['tvdb', 'tmdb', 'imdb'];
+
+/**
+ * Parse a ref. Accepts "kitsu:44607", "MAL:1", "tvdb:342329", "tt8948436" and
+ * "imdb:tt8948436" (normalised to the bare "tt8948436").
+ * Returns { kind: 'anime' | 'series', provider, id, ref }; throws invalid_ref.
+ */
+export function parseRef(input) {
+  const raw = typeof input === 'string' ? input.trim() : '';
+  const bad = () => new ClientError('invalid_ref', `"${input}" is not a ref such as kitsu:44607, tvdb:342329 or tt8948436`);
+  if (/^tt\d+$/i.test(raw)) return { kind: 'series', provider: 'imdb', id: raw.toLowerCase(), ref: raw.toLowerCase() };
+  const m = /^([a-z]+):(.+)$/i.exec(raw);
+  if (!m) throw bad();
+  const provider = m[1].toLowerCase();
+  const id = m[2];
+  if (provider === 'imdb') {
+    if (!/^tt\d+$/i.test(id)) throw bad();
+    return { kind: 'series', provider, id: id.toLowerCase(), ref: id.toLowerCase() };
+  }
+  if (!/^\d+$/.test(id) || /^0+$/.test(id)) throw bad();
+  const norm = String(BigInt(id)); // drops leading zeros without losing precision
+  if (ANIME_PROVIDERS.includes(provider)) return { kind: 'anime', provider, id: norm, ref: `${provider}:${norm}` };
+  if (SERIES_PROVIDERS.includes(provider)) return { kind: 'series', provider, id: norm, ref: `${provider}:${norm}` };
+  throw bad();
+}
+
+/** A title id or any ref that resolves to a title: "tt8948436", "kitsu:44607", "tvdb:342329", "tmdb:movie:129". */
+export function parseTitleRef(input) {
+  const raw = typeof input === 'string' ? input.trim() : '';
+  const movie = /^tmdb:movie:(\d+)$/i.exec(raw);
+  if (movie && !/^0+$/.test(movie[1])) return `tmdb:movie:${String(BigInt(movie[1]))}`;
+  return parseRef(input).ref;
+}
+
+export function animeRef(input) {
+  const p = parseRef(input);
+  if (p.kind !== 'anime') throw new ClientError('invalid_ref', `"${input}" is not an anime ref (kitsu, mal, anilist or anidb)`);
+  return p;
+}
+
+export function seriesRef(input) {
+  const p = parseRef(input);
+  if (p.kind !== 'series') throw new ClientError('invalid_ref', `"${input}" is not a series ref (tvdb, tmdb or imdb)`);
+  return p;
+}
+
+export function checkInt(value, name, min) {
+  if (!Number.isInteger(value) || value < min) {
+    throw new ClientError('invalid_argument', `${name} must be an integer >= ${min}, got ${value}`);
+  }
+}
+
+export function optionalInt(value, name, min) {
+  if (value !== undefined && value !== null) checkInt(value, name, min);
+}