@vanomarb/animap 0.0.0-stage → 1.0.1

package/src/index.d.ts

@@ -0,0 +1,635 @@
+export type AnimeProvider = 'kitsu' | 'mal' | 'anilist' | 'anidb';
+export type SeriesProvider = 'tvdb' | 'tmdb' | 'imdb';
+export type Format = 'tv' | 'ona' | 'ova' | 'movie' | 'special' | 'music' | 'unknown';
+export type RangeSource = 'manual' | 'anibridge' | 'scudlee' | 'fribb' | 'derived';
+export type Confidence = 'verified' | 'inferred' | 'derived';
+
+export interface Range {
+  target: SeriesProvider;
+  targetId: string;
+  /** 0 = specials, null = absolute numbering. */
+  season: number | null;
+  /** Entry episodes, 1-based, inclusive. */
+  from: number;
+  to: number;
+  /** Target episodes in `season`, inclusive. */
+  targetFrom: number;
+  targetTo: number;
+  /** Target episodes per entry episode. */
+  ratio: number;
+  source: RangeSource;
+  confidence: Confidence;
+}
+
+export interface Entry {
+  /** First present of anilist, mal, anidb, kitsu, as a ref. */
+  id: string;
+  ids: Record<AnimeProvider, string | null>;
+  title: string;
+  titles: string[];
+  format: Format;
+  episodes: number | null;
+  year: number | null;
+  /** Up to 12 lower-case genre-like tags, genres first. Optional: older datasets lack it. */
+  tags?: string[];
+  /** 0–10, one decimal; null when unknown. Optional: older datasets lack it. */
+  score?: number | null;
+  series: { tvdb: string | null; tmdb: string | null; imdb: string | null };
+  images: Images;
+  ranges: Range[];
+  updatedAt: string;
+}
+
+/** Artwork URLs, each null when unknown. `cover` may 404; fall back to the poster. */
+export interface Images {
+  poster: string | null;
+  thumb: string | null;
+  cover: string | null;
+}
+
+export type EntrySummary = Omit<Entry, 'ranges'> & {
+  names: Names;
+  /** On search() results: the Cinemeta-format id of the entry's title, null when none is cached. */
+  titleId?: string | null;
+  rangeCount: number;
+  issueCount: number;
+  /** Targets the entry has effective ranges for, in the order tvdb, tmdb, imdb. */
+  targets: SeriesProvider[];
+};
+
+export interface Issue {
+  id: string;
+  type: 'overlap' | 'gap' | 'count' | 'unmapped' | 'conflict';
+  target?: SeriesProvider;
+  targetId?: string;
+  season?: number | null;
+  from?: number;
+  to?: number;
+  entries: string[];
+  message: string;
+}
+
+export interface SeriesResponse {
+  series: { provider: SeriesProvider; id: string };
+  /** Most common title among the series' entries. */
+  title: string | null;
+  images: Images | null;
+  /** Ordered 1, 2, …, then 0 (specials), then null (absolute). */
+  seasons: Array<{
+    season: number | null;
+    /** Known season length, or null. */
+    length: number | null;
+    rows: Array<{ entry: EntrySummary; range: Range }>;
+    issues: Issue[];
+  }>;
+}
+
+export interface SeriesEpisode {
+  provider: SeriesProvider;
+  id: string;
+  season: number | null;
+  episode: number;
+  /** Target episodes covered by the entry episode (ratio > 1). */
+  span: number;
+  source: RangeSource;
+  confidence: Confidence;
+}
+
+export interface EntryEpisode {
+  /** Entry id, e.g. "anilist:129347". */
+  entry: string;
+  ids: Record<AnimeProvider, string | null>;
+  episode: number;
+  source: RangeSource;
+  confidence: Confidence;
+}
+
+export interface Meta {
+  builtAt: string | null;
+  importedAt: string | null;
+  counts: { entries: number; ranges: number; issues: number };
+  sources: Record<string, { version: string | null; fetchedAt: string | null; count: number }>;
+}
+
+export interface Revision {
+  id: string;
+  at: string;
+  keyName: string;
+  kind: 'ranges' | 'ids';
+  target?: SeriesProvider | null;
+  before: unknown;
+  after: unknown;
+  note?: string | null;
+}
+
+export interface ApiKeyInfo {
+  id: string;
+  name: string;
+  role: 'read' | 'admin';
+  rateLimit: number;
+  createdAt: string;
+}
+
+// ---- Titles (Cinemeta-format ids) -------------------------------------------------------
+
+export type TitleType = 'series' | 'movie';
+
+export interface Rating {
+  /** 0–10, or null (TVDB has no user rating; its popularity count is `score`). */
+  value: number | null;
+  votes: number | null;
+  score?: number;
+}
+
+export interface CastMember {
+  name: string;
+  character: string | null;
+  photo: string | null;
+}
+
+export interface TitleSeason {
+  season: number | null;
+  episodes: number | null;
+  mappedEpisodes: number | null;
+  poster: string | null;
+}
+
+/** A title's name in three forms; each null when unknown. */
+export interface Names {
+  /** English only (the `name` rule). */
+  english: string | null;
+  /** Kitsu's romanisation (en_jp, en_cn or en_kr). */
+  romaji: string | null;
+  /** ja_jp, zh_cn or ko_kr. */
+  native: string | null;
+}
+
+export interface TitleSummary {
+  /** Cinemeta-format id: "tt…", else "kitsu:<id>", "tmdb:<id>", "tvdb:<id>", then "mal:", "anilist:" or "anidb:". */
+  id: string;
+  type: TitleType;
+  /** names.english, else names.romaji. */
+  name: string | null;
+  names: Names;
+  year: string | null;
+  format: Format;
+  poster: string | null;
+  background: string | null;
+  genres: string[];
+  episodes: number | null;
+  mappedEpisodes: number | null;
+  providers: Partial<Record<AnimeProvider | SeriesProvider, boolean>>;
+  entryCount: number;
+  issueCount: number;
+  rating: number | null;
+}
+
+export interface Title {
+  id: string;
+  type: TitleType;
+  ids: Record<SeriesProvider | AnimeProvider, string | null>;
+  /** names.english, else names.romaji. */
+  name: string | null;
+  names: Names;
+  originalName: string | null;
+  description: string | null;
+  genres: string[];
+  year: string | null;
+  releaseInfo: string | null;
+  released: string | null;
+  status: string | null;
+  runtime: string | null;
+  country: string | null;
+  certification: string | null;
+  format: Format;
+  poster: string | null;
+  background: string | null;
+  logo: string | null;
+  /** Each source keeps its own rating; never merged. */
+  ratings: Partial<Record<'imdb' | 'tmdb' | 'tvdb' | 'kitsu', Rating | null>>;
+  cast: CastMember[];
+  directors: string[];
+  writers: string[];
+  seasons: TitleSeason[];
+  entries: Array<EntrySummary & { range: Range | null }>;
+  coverage: { episodes: number | null; mappedEpisodes: number | null };
+  similar: TitleSummary[];
+  /** Field → source that filled it (cinemeta, kitsu, aniscraper, and tmdb/tvdb/fanart when enriched in-process). */
+  provenance: Record<string, string>;
+  layers: Record<string, string>;
+  enrichedAt: string | null;
+}
+
+export interface TitleEpisode {
+  season: number;
+  episode: number;
+  name: string | null;
+  overview: string | null;
+  released: string | null;
+  thumbnail: string | null;
+  runtime: string | null;
+  rating: number | null;
+  mapped: EntryEpisode[];
+}
+
+export interface TitleEpisodes {
+  season: number | null;
+  /** Every season with episodes, ordered 1, 2, …, then 0. */
+  seasons: number[];
+  episodes: TitleEpisode[];
+}
+
+export interface TitlesQuery {
+  /** Names and aliases; an id (tt…, tmdb:N, kitsu:N, …) is a lookup of that id. */
+  q?: string;
+  type?: TitleType;
+  format?: Format;
+  year?: number;
+  genre?: string;
+  mapped?: 'full' | 'partial' | 'none';
+  /** Only titles with mapping issues. */
+  issues?: boolean;
+  sort?: 'popular' | 'updated' | 'title' | 'year';
+  /** `next` from the previous page. */
+  cursor?: string;
+  limit?: number;
+  /** false: the server answers from its cache only, with no upstream call. */
+  live?: boolean;
+}
+
+export interface TitlesPage {
+  results: TitleSummary[];
+  total: number;
+  next: string | null;
+}
+
+export interface ActivityItem {
+  at: string;
+  kind: 'ranges' | 'ids';
+  title: TitleSummary | null;
+  entry: string;
+  /** e.g. "Mapped episodes 1–13 to TVDB S1 E79–91". */
+  summary: string;
+  keyName: string;
+}
+
+export interface Stats {
+  titles: number;
+  entries: number;
+  mappedEpisodes: number;
+  ranges: number;
+  sources: string[];
+  importedAt: string | null;
+}
+
+// ---- BYOK ---------------------------------------------------------------------------------
+
+export type ByokProvider = 'tmdb' | 'tvdb' | 'fanart';
+
+export interface ProviderKeys {
+  /** TMDB v3 API key or v4 read access token (detected by shape). */
+  tmdb?: string | { key: string };
+  /** TVDB v4 key, with the subscriber PIN when the key needs one. */
+  tvdb?: string | { key: string; pin?: string };
+  fanart?: string | { key: string };
+}
+
+/** Anything Storage-like; methods may be synchronous (localStorage) or return promises. */
+export interface CacheStorage {
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<void>;
+  removeItem(key: string): void | Promise<void>;
+}
+
+export type ByokErrorCode = 'invalid_key' | 'rate_limited' | 'network' | 'timeout' | 'not_found' | 'bad_response' | 'aborted';
+
+export class ByokError extends Error {
+  constructor(provider: ByokProvider | string, code: ByokErrorCode, message: string, options?: { status?: number | null; retryAfter?: number | null });
+  name: 'ByokError';
+  provider: ByokProvider | string;
+  code: ByokErrorCode;
+  status: number | null;
+  /** Seconds, on rate_limited. */
+  retryAfter: number | null;
+}
+
+export interface ProviderErrorInfo {
+  provider: ByokProvider;
+  code: ByokErrorCode;
+  message: string;
+}
+
+export interface KeyCheck {
+  state: 'connected' | 'invalid' | 'rate_limited' | 'error' | 'missing';
+  message: string | null;
+}
+
+/** Raw provider calls (provider JSON, not normalized). Every method takes an optional AbortSignal last. */
+export interface Providers {
+  tmdb: null | {
+    /** 'v3' (api_key) or 'v4' (Bearer token), from the key's shape. */
+    kind: 'v3' | 'v4';
+    check(signal?: AbortSignal): Promise<unknown>;
+    /** GET /find/{imdbId}?external_source=imdb_id */
+    findByImdb(imdbId: string, signal?: AbortSignal): Promise<any>;
+    /** GET /tv/{id} with aggregate_credits, recommendations, external_ids, content_ratings. */
+    series(tmdbId: string, signal?: AbortSignal): Promise<any>;
+    /** GET /movie/{id} with credits, recommendations, external_ids, release_dates. */
+    movie(tmdbId: string, signal?: AbortSignal): Promise<any>;
+    /** GET /tv/{id}/season/{n} */
+    season(tmdbId: string, season: number, signal?: AbortSignal): Promise<any>;
+    /** GET /search/tv or /search/movie. */
+    search(query: string, options?: { type?: 'tv' | 'movie'; year?: number }, signal?: AbortSignal): Promise<any>;
+  };
+  tvdb: null | {
+    /** Logs in (POST /login); resolves when the key works. */
+    check(signal?: AbortSignal): Promise<{ ok: true }>;
+    /** GET /series/{id}/extended?meta=translations */
+    series(tvdbId: string, signal?: AbortSignal): Promise<any>;
+    /** GET /movies/{id}/extended?meta=translations */
+    movie(tvdbId: string, signal?: AbortSignal): Promise<any>;
+    /** GET /series/{id}/episodes/default/eng?season={n} (first page) */
+    episodes(tvdbId: string, season: number, signal?: AbortSignal): Promise<any>;
+    /** Every page of /series/{id}/episodes/{order}/{lang}: names and overviews translated, absoluteNumber kept. */
+    allEpisodes(tvdbId: string, options?: { order?: 'official' | 'default' | 'absolute' | 'dvd'; lang?: string; signal?: AbortSignal }): Promise<any[]>;
+    /** GET /series|movies/{id}/translations/{lang} (English by default). */
+    translation(tvdbId: string, options?: { lang?: string; kind?: 'series' | 'movie' }, signal?: AbortSignal): Promise<any>;
+    /** GET /series/{id}/artworks; pick with pickTvdbArt from the "/byok" entry. */
+    artworks(tvdbId: string, signal?: AbortSignal): Promise<any>;
+    /** GET /search/remoteid/{id} (an IMDb id → TVDB hits). */
+    searchRemoteId(remoteId: string, signal?: AbortSignal): Promise<any>;
+  };
+  fanart: null | {
+    check(signal?: AbortSignal): Promise<unknown>;
+    /** GET /tv/{tvdbId} */
+    series(tvdbId: string, signal?: AbortSignal): Promise<any>;
+    /** GET /movies/{tmdbId} */
+    movie(tmdbId: string, signal?: AbortSignal): Promise<any>;
+  };
+  /** Keyless; null when turned off. Results go through the response cache. */
+  kitsu: null | {
+    /** One anime with labelled titles and categories; null when Kitsu has no such id. */
+    anime(kitsuId: string, signal?: AbortSignal): Promise<KitsuAnime | null>;
+    /** Every episode sorted by number (default at most 500). */
+    episodes(kitsuId: string, options?: { max?: number; signal?: AbortSignal }): Promise<KitsuEpisode[]>;
+    /** Media relationships with the destination's subtype. */
+    relationships(kitsuId: string, signal?: AbortSignal): Promise<KitsuRelationship[]>;
+    /** Text search in Kitsu's relevance order (limit 1–20, default 5). */
+    search(text: string, options?: { limit?: number; signal?: AbortSignal }): Promise<KitsuAnime[]>;
+  };
+  /** Keyless; null when turned off. Results go through the response cache. */
+  cinemeta: null | {
+    /** The raw Cinemeta meta (videos included), or null when Cinemeta has none of that type. */
+    meta(imdbId: string, type?: TitleType, signal?: AbortSignal): Promise<any | null>;
+    /** `type` first, then the other: { type, meta } or null. */
+    find(imdbId: string, type?: TitleType, signal?: AbortSignal): Promise<{ type: TitleType; meta: any } | null>;
+  };
+}
+
+export interface KitsuAnime {
+  id: string;
+  slug: string | null;
+  titles: {
+    canonical: string | null;
+    /** en, else en_us */
+    en: string | null;
+    /** en_jp, else en_cn, else en_kr */
+    romaji: string | null;
+    /** ja_jp, else zh_cn, else ko_kr */
+    native: string | null;
+    /** Every other titles.* value. */
+    synonyms: string[];
+    /** abbreviatedTitles */
+    abbreviated: string[];
+  };
+  synopsis: string | null;
+  /** TV, ONA, OVA, movie, special, music */
+  subtype: string | null;
+  showType: string | null;
+  /** current, finished, tba, unreleased, upcoming */
+  status: string | null;
+  startDate: string | null;
+  endDate: string | null;
+  nextRelease: string | null;
+  episodeCount: number | null;
+  episodeLength: number | null;
+  ageRating: string | null;
+  nsfw: boolean | null;
+  posterImage: Record<string, any> | null;
+  coverImage: Record<string, any> | null;
+  youtubeVideoId: string | null;
+  /** Kitsu's 0–100 average. */
+  averageRating: number | null;
+  /** 0–10, one decimal. */
+  rating: number | null;
+  userCount: number | null;
+  popularityRank: number | null;
+  /** Kitsu's genres (the `genres` attribute is always empty). */
+  categories: string[];
+}
+
+export interface KitsuEpisode {
+  number: number;
+  seasonNumber: number;
+  relativeNumber: number | null;
+  title: string | null;
+  titles: Record<string, string>;
+  synopsis: string | null;
+  /** The real air date, or null; Kitsu's createdAt (set when an episode is only planned) is never used. */
+  airdate: string | null;
+  length: number | null;
+  thumbnail: string | null;
+}
+
+export interface KitsuRelationship {
+  /** prequel, sequel, side_story, parent_story, alternative_setting, spinoff, summary, full_story, character, other, … */
+  role: string | null;
+  id: string;
+  type: string;
+  subtype: string | null;
+  title: string | null;
+  titles: Record<string, string>;
+  episodeCount: number | null;
+  status: string | null;
+  startDate: string | null;
+}
+
+/** Your own store for API answers; sync or async. Values are JSON-serialisable. */
+export interface ResponseStore {
+  get(key: string): unknown | Promise<unknown>;
+  set(key: string, value: unknown, ttlMs: number): void | Promise<void>;
+  delete?(key: string): void | Promise<void>;
+  clear?(): void | Promise<void>;
+}
+
+export interface ClientOptions {
+  apiKey: string;
+  /** API origin, e.g. "https://animap.example.com"; a trailing "/v1" is accepted. */
+  baseUrl: string;
+  /**
+   * Cache for API answers and keyless provider results. Default: in memory, 1 h for hits,
+   * 5 min for misses, 5000 items. false turns it off; a store replaces the memory one.
+   */
+  cache?: false | { ttlMs?: number; missTtlMs?: number; max?: number; store?: ResponseStore } | ResponseStore;
+  /** @deprecated Use cache: { ttlMs }. */
+  cacheTtlMs?: number | false;
+  /** Retries of network errors, 429 (after Retry-After, at most maxWaitMs) and 502–504. Default { max: 1, maxWaitMs: 10000 }. */
+  retry?: false | { max?: number; maxWaitMs?: number };
+  /** Per API key: after `threshold` consecutive failures, pause `cooldownMs` (a 429 pauses for its Retry-After; cap 5 min). Default { threshold: 5, cooldownMs: 30000 }. */
+  breaker?: false | { threshold?: number; cooldownMs?: number };
+  /** fetch implementation, for the API and the providers; defaults to the global fetch. */
+  fetch?: typeof fetch;
+  /** Per-attempt API timeout in ms (default 10000). */
+  timeoutMs?: number;
+  /**
+   * Your own provider keys (only ever sent to that provider), and the keyless Kitsu and
+   * Cinemeta clients (on by default; false turns one off).
+   */
+  providers?: ProviderKeys & {
+    kitsu?: boolean | { baseUrl?: string; timeoutMs?: number };
+    cinemeta?: boolean | { baseUrl?: string; timeoutMs?: number };
+  };
+  /** Where provider results are cached for 7 days (default: in memory). */
+  providerCache?: CacheStorage;
+  /** Provider request timeout in ms (default 8000). */
+  providerTimeoutMs?: number;
+  /** Called for every provider failure; the call that triggered it still succeeds. */
+  onProviderError?: (error: ByokError) => void;
+}
+
+/** Same as ClientOptions. */
+export type AniMapOptions = ClientOptions;
+
+export type ErrorCode =
+  | 'unauthorized' | 'forbidden' | 'not_found' | 'bad_request'
+  /** The API could not answer: see `reason`. Fall back to another source. */
+  | 'unavailable'
+  | 'missing_api_key' | 'missing_base_url' | 'invalid_ref' | 'invalid_argument' | 'invalid_response';
+
+export type UnavailableReason = 'network_error' | 'timeout' | 'rate_limited' | 'server_error' | 'circuit_open';
+
+export class ClientError extends Error {
+  constructor(code: ErrorCode | string, message: string, status?: number | null, extra?: { details?: unknown; reason?: UnavailableReason; retryAfterMs?: number });
+  name: 'ClientError';
+  code: ErrorCode | string;
+  /** HTTP status, or null when there was no response. */
+  status: number | null;
+  /** `error.details` from the server, when present. */
+  details?: unknown;
+  /** With code "unavailable". */
+  reason?: UnavailableReason;
+  /** With reason "rate_limited" or "circuit_open": how long to wait. */
+  retryAfterMs?: number;
+}
+
+export interface ParsedRef {
+  kind: 'anime' | 'series';
+  provider: AnimeProvider | SeriesProvider;
+  id: string;
+  /** Normalised ref: "kitsu:44607", "tvdb:342329", "tt8948436". */
+  ref: string;
+}
+
+/** Parse and normalise a ref; throws ClientError "invalid_ref". */
+export function parseRef(ref: string): ParsedRef;
+
+/** Normalise a title id or ref ("tt…", "kitsu:44607", "tvdb:342329", "tmdb:movie:129"); throws "invalid_ref". */
+export function parseTitleRef(ref: string): string;
+
+/** Retry-After header → milliseconds to wait, capped at 10 s. */
+export function retryAfterMs(header: string | null | undefined, now?: number): number;
+
+export { createByokCache, memoryStorage, mergeTitle, mergeEpisodes } from './byok/index.js';
+
+/** In-memory response store with per-item expiry. */
+export function memoryStore(options?: { max?: number; now?: () => number }): ResponseStore & { readonly size: number };
+
+export interface Slice {
+  season: number | null;
+  /** series episode = entry episode + offset */
+  offset: number;
+  /** Last series episode of the slice. */
+  end: number;
+  /** The target whose range was used (may be borrowed). */
+  target: SeriesProvider;
+}
+
+/**
+ * Where an entry sits in a series for 1:1 numbering. A target without a 1:1 range borrows
+ * another's (imdb/cinemeta: imdb, tvdb, tmdb; tvdb: tvdb, imdb, tmdb; tmdb: tmdb, tvdb, imdb).
+ */
+export function alignToEntry(ranges: Range[], target: SeriesProvider | 'cinemeta'): Slice | null;
+/** Per target, the first 1:1 range by entry episode. */
+export function slicesFromRanges(ranges: Range[]): Partial<Record<SeriesProvider, { season: number | null; offset: number; end: number; from: number; to: number }>>;
+
+export class Client {
+  constructor(options: ClientOptions);
+
+  /** A client for another API key that shares this one's cache, providers and breaker map (the breaker state is per key). */
+  withApiKey(apiKey: string): Client;
+  /** Milliseconds until the API is called again for this key after repeated failures; 0 when available. */
+  readonly pausedFor: number;
+
+  /** Provider clients: tmdb/tvdb/fanart with your keys (null without one), keyless kitsu/cinemeta (null when off). */
+  readonly providers: Providers;
+  /** Providers with a key, e.g. ['tmdb', 'tvdb']. */
+  readonly enrichment: ByokProvider[];
+
+  /** Entry for an anime ref ("kitsu:44607"), or null when unknown. */
+  entry(ref: string): Promise<Entry | null>;
+  /** Entries for many anime refs (sent in batches of 100), keyed by the refs as given. */
+  lookup(refs: string[]): Promise<Map<string, Entry | null>>;
+  /** Series episode for an entry episode, or null when unmapped. */
+  toSeries(ref: string, episode: number, options?: { target?: SeriesProvider }): Promise<SeriesEpisode | null>;
+  /** Entry episodes for a series episode ("tt8948436", 1, 85). */
+  fromSeries(ref: string, season: number, episode: number): Promise<EntryEpisode[]>;
+  /** Every mapped entry of a series ("tvdb:342329"), grouped by season. */
+  series(ref: string, options?: { season?: number }): Promise<SeriesResponse>;
+  /** Entry search by title, alias or id. */
+  search(query: string, options?: { limit?: number; /** false: the server's cache only, no upstream call. */ live?: boolean }): Promise<EntrySummary[]>;
+  /** Mapping issues, optionally for one entry and one type. */
+  issues(options?: { type?: Issue['type']; entry?: string; cursor?: string; limit?: number }): Promise<{ results: Issue[]; next: string | null }>;
+  /** Edit history of an entry, newest first. */
+  history(ref: string): Promise<Revision[]>;
+
+  /** A title by id or any ref; enriched from your provider keys unless `enrich: false`. */
+  title(ref: string, options?: { enrich?: boolean; signal?: AbortSignal }): Promise<Title | null>;
+  /** Fill a Title from the configured providers (never overwrites what the API filled). */
+  enrichTitle(title: Title, options?: { signal?: AbortSignal }): Promise<{
+    title: Title;
+    filled: Record<string, ByokProvider>;
+    errors: ProviderErrorInfo[];
+    ids: Title['ids'] | null;
+  }>;
+  /** Episodes of one season (the first when omitted); enriched from TMDB/TVDB unless `enrich: false`. */
+  titleEpisodes(ref: string, options?: { season?: number; enrich?: boolean; signal?: AbortSignal }): Promise<TitleEpisodes | null>;
+  /** Fill episode rows of one season from TMDB, then TVDB. */
+  enrichEpisodes(title: Title, season: number, episodes: TitleEpisode[], options?: { signal?: AbortSignal }): Promise<{
+    episodes: TitleEpisode[];
+    filledBy: ByokProvider[];
+    errors: ProviderErrorInfo[];
+  }>;
+  /** Browse or search titles. */
+  titles(query?: TitlesQuery): Promise<TitlesPage>;
+  /** Kitsu's trending anime, resolved to titles. */
+  trending(options?: { limit?: number }): Promise<TitleSummary[]>;
+  /** Recent mapping edits. */
+  activity(options?: { limit?: number }): Promise<ActivityItem[]>;
+  /** Catalogue counts. */
+  stats(): Promise<Stats>;
+  /** The most common genres. */
+  genres(): Promise<Array<{ name: string; count: number }>>;
+
+  /** Dataset build/import times, counts and source versions. */
+  meta(): Promise<Meta>;
+  /** The API key in use. */
+  me(): Promise<ApiKeyInfo>;
+  /** Check a provider key against the provider itself. */
+  checkProvider(provider: ByokProvider): Promise<KeyCheck>;
+  /** Forget every cached API response (provider results stay in the provider cache). */
+  clearCache(): Promise<void>;
+}
+
+/** AniMap is Client; AniMapError is ClientError. */
+export { Client as AniMap, ClientError as AniMapError };
+export default Client;

package/src/index.js

@@ -0,0 +1,18 @@
+// AniMap client: the anime id mapping API, with optional in-process provider enrichment.
+// Zero dependencies; runs on Node >= 18 and in browsers (global fetch).
+
+import { Client } from './client.js';
+import { ClientError } from './errors.js';
+
+export { Client, retryAfterMs } from './client.js';
+export { ClientError } from './errors.js';
+export { parseRef, parseTitleRef } from './refs.js';
+export { alignToEntry, slicesFromRanges } from './align.js';
+export { memoryStore } from './cache.js';
+export { ByokError } from './byok/http.js';
+export { createByokCache, memoryStorage } from './byok/cache.js';
+export { mergeEpisodes, mergeTitle } from './byok/merge.js';
+
+// Brand-named aliases of the same classes.
+export { Client as AniMap, ClientError as AniMapError };
+export default Client;

package/src/providers/cinemeta.js

@@ -0,0 +1,32 @@
+// Cinemeta (keyless): Stremio's IMDb-based catalogue. Returns metas exactly as Cinemeta
+// serves them (videos included). A meta without a name means "not this type".
+import { providerFetch } from '../byok/http.js';
+
+export const CINEMETA_API = 'https://v3-cinemeta.strem.io';
+
+export function createCinemeta({ fetch, timeoutMs = 10_000, baseUrl = CINEMETA_API } = {}) {
+  async function meta(imdbId, type = 'series', signal) {
+    if (!/^tt\d+$/.test(String(imdbId))) return null;
+    if (type !== 'series' && type !== 'movie') throw new TypeError('type must be "series" or "movie"');
+    try {
+      const body = await providerFetch('cinemeta', `${baseUrl}/meta/${type}/${imdbId}.json`, { fetch, signal, timeoutMs });
+      return body?.meta?.name ? body.meta : null;
+    } catch (e) {
+      if (e.code === 'not_found') return null;
+      throw e;
+    }
+  }
+
+  return {
+    /** The raw meta for one type, or null. */
+    meta,
+    /** Try `type` first, then the other one: { type, meta } or null. */
+    async find(imdbId, type = 'series', signal) {
+      for (const t of type === 'movie' ? ['movie', 'series'] : ['series', 'movie']) {
+        const m = await meta(imdbId, t, signal);
+        if (m) return { type: t, meta: m };
+      }
+      return null;
+    },
+  };
+}