@vanomarb/animap 1.0.0 → 1.0.1

package/README.md

@@ -117,7 +117,7 @@ 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.search('soul land', { limit: 5 });     // EntrySummary[]; { live: false } = cached only
 await client.issues({ entry: 'kitsu:44607', type: 'count' }); // { results: Issue[], next }
 await client.history('anilist:129347');             // Revision[], newest first
 ```
@@ -149,6 +149,7 @@ 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.titles({ q: 'tmdb:76572', live: false }); // an id is a lookup; live: false = server cache only, no upstream call
 await client.trending({ limit: 12 });         // TitleSummary[]
 await client.activity({ limit: 20 });         // recent mapping edits
 await client.stats();                         // { titles, entries, mappedEpisodes, ranges, sources, importedAt }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vanomarb/animap",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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",

package/src/client.js

@@ -256,11 +256,13 @@ export class Client {
   }
 
   /** Entry search by title, alias or id. Returns EntrySummary[]. */
-  async search(query, { limit } = {}) {
+  /** `live: false`: the server answers from its cache only, with no upstream call. */
+  async search(query, { limit, live } = {}) {
     if (typeof query !== 'string' || !query.trim()) throw new ClientError('invalid_argument', 'search() needs a non-empty query');
     optionalInt(limit, 'limit', 1);
     const params = new URLSearchParams({ q: query.trim() });
     if (limit !== undefined) params.set('limit', String(limit));
+    if (live === false) params.set('live', '0');
     const body = await this.#cached(`search:${params}`, () => this.#request('GET', `/v1/search?${params}`));
     return body.results ?? [];
   }
@@ -356,7 +358,7 @@ export class Client {
    * Browse or search titles. `q` matches names, aliases and any id.
    * Returns { results: TitleSummary[], total, next }; pass `next` back as `cursor`.
    */
-  async titles({ q, type, format, year, genre, mapped, issues, sort, cursor, limit } = {}) {
+  async titles({ q, type, format, year, genre, mapped, issues, sort, cursor, limit, live } = {}) {
     optionalInt(year, 'year', 0);
     optionalInt(limit, 'limit', 1);
     const params = new URLSearchParams();
@@ -364,6 +366,7 @@ export class Client {
       if (v !== undefined && v !== null && v !== '') params.set(k, String(v).trim());
     }
     if (issues) params.set('issues', '1');
+    if (live === false) params.set('live', '0');
     const qs = params.toString() ? `?${params}` : '';
     return this.#cached(`titles:${qs}`, () => this.#request('GET', `/v1/titles${qs}`));
   }
@@ -439,7 +442,9 @@ export class Client {
     const core = this.#core;
     const cached = await core.providerCache.get('title', server.id, core.sig);
     if (cached) return { sources: cached, errors: [] };
-    const findTitle = async (ref) => (await this.titles({ q: ref, limit: 1 })).results?.[0] ?? null;
+    // Recommendations resolve from the server's cache only: a similar title nobody has
+    // opened yet is left out rather than resolved live, eight times per title.
+    const findTitle = async (ref) => (await this.titles({ q: ref, limit: 1, live: false })).results?.[0] ?? null;
     const { sources, errors } = await fetchSources(server, core.keys, { fetch: core.fetch, findTitle, signal });
     this.#report(errors);
     if (!errors.some(isTransient) && !errors.some((e) => e.code === 'aborted')) {

package/src/index.d.ts

@@ -48,6 +48,9 @@ export interface Images {
 }
 
 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. */
@@ -151,11 +154,23 @@ export interface TitleSeason {
   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>" or an entry id. */
+  /** 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;
@@ -173,7 +188,9 @@ 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[];
@@ -223,7 +240,7 @@ export interface TitleEpisodes {
 }
 
 export interface TitlesQuery {
-  /** Names, aliases and any id (an anime ref resolves to its title). */
+  /** Names and aliases; an id (tt…, tmdb:N, kitsu:N, …) is a lookup of that id. */
   q?: string;
   type?: TitleType;
   format?: Format;
@@ -236,6 +253,8 @@ export interface TitlesQuery {
   /** `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 {
@@ -567,7 +586,7 @@ export class Client {
   /** 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 }): Promise<EntrySummary[]>;
+  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. */