@vanomarb/animap 0.0.0-stage → 1.0.0

package/src/client.js

@@ -0,0 +1,573 @@
+// The API client. One shared core (response cache, breaker states, provider clients,
+// provider cache) per `new Client()`; `withApiKey()` makes light clients on the same core.
+
+import { ClientError, unavailable } from './errors.js';
+import { SERIES_PROVIDERS, animeRef, checkInt, optionalInt, parseTitleRef, seriesRef } from './refs.js';
+import { createResponseCache } from './cache.js';
+import { createBreakers, disabledBreakers } from './breaker.js';
+import { ByokError } from './byok/http.js';
+import { createByokCache, keySignature } from './byok/cache.js';
+import { createTmdb } from './byok/tmdb.js';
+import { createTvdb } from './byok/tvdb.js';
+import { createFanart } from './byok/fanart.js';
+import { mergeEpisodes, mergeTitle } from './byok/merge.js';
+import { checkKey, fetchEpisodeFills, fetchSources } from './byok/enrich.js';
+import { isTransient } from './byok/index.js';
+import { createKitsu } from './providers/kitsu.js';
+import { createCinemeta } from './providers/cinemeta.js';
+
+const BYOK_PROVIDERS = ['tmdb', 'tvdb', 'fanart'];
+const LOOKUP_BATCH = 100;
+const MAX_RETRY_AFTER_MS = 10_000;
+const NETWORK_RETRY_DELAY_MS = 250;
+const RETRYABLE_5XX = new Set([502, 503, 504]);
+const CORE = Symbol('core');
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Retry-After (seconds or HTTP date) → ms, uncapped; 1 s when absent or unreadable. */
+function parseRetryAfter(header, now = Date.now()) {
+  if (header === null || header === undefined || header === '') return 1000;
+  const seconds = Number(header);
+  const ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(header) - now;
+  return Number.isFinite(ms) && ms >= 0 ? ms : 1000;
+}
+
+/** Retry-After header (seconds or HTTP date) → milliseconds, capped at 10 s. */
+export function retryAfterMs(header, now = Date.now()) {
+  if (header === null || header === undefined || header === '') return 1000;
+  const seconds = Number(header);
+  let ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(header) - now;
+  if (!Number.isFinite(ms) || ms < 0) ms = 0;
+  return Math.min(ms, MAX_RETRY_AFTER_MS);
+}
+
+/** { tmdb: 'k' } or { tmdb: { key: 'k' } }, { tvdb: { key, pin } } → flat keys, '' when unset. */
+function providerKeys(providers = {}) {
+  const keyOf = (v) => String((typeof v === 'string' ? v : v?.key) ?? '').trim();
+  return {
+    tmdb: keyOf(providers.tmdb),
+    tvdb: keyOf(providers.tvdb),
+    tvdbPin: String((typeof providers.tvdb === 'object' ? providers.tvdb?.pin : '') ?? '').trim(),
+    fanart: keyOf(providers.fanart),
+  };
+}
+
+function codeForStatus(status) {
+  if (status === 400) return 'bad_request';
+  if (status === 401) return 'unauthorized';
+  if (status === 403) return 'forbidden';
+  if (status === 404) return 'not_found';
+  return 'bad_request';
+}
+
+function checkApiKey(apiKey) {
+  if (typeof apiKey !== 'string' || !apiKey.trim()) {
+    throw new ClientError('missing_api_key', 'An API key is required: new Client({ apiKey, baseUrl })');
+  }
+  return apiKey.trim();
+}
+
+function buildCore(options) {
+  const {
+    baseUrl, cache, cacheTtlMs, fetch, timeoutMs = 10_000, retry, breaker,
+    providers = {}, providerCache, providerTimeoutMs = 8000, onProviderError,
+  } = options;
+  if (typeof baseUrl !== 'string' || !/^https?:\/\//i.test(baseUrl)) {
+    throw new ClientError('missing_base_url', 'baseUrl must be the http(s) URL of the API');
+  }
+  // Wrapped so a browser's window.fetch is never called with the wrong `this`.
+  const f = fetch ? (...args) => fetch(...args) : (...args) => globalThis.fetch(...args);
+  const keys = providerKeys(providers);
+  const t = providerTimeoutMs;
+  const tmdb = keys.tmdb ? createTmdb({ key: keys.tmdb, fetch: f, timeoutMs: t }) : null;
+  const tvdb = keys.tvdb ? createTvdb({ key: keys.tvdb, pin: keys.tvdbPin, fetch: f, timeoutMs: t }) : null;
+  const fanart = keys.fanart ? createFanart({ key: keys.fanart, fetch: f, timeoutMs: t }) : null;
+  const keyless = (opt) => (opt === false ? null : typeof opt === 'object' && opt ? opt : {});
+  const kitsuOpt = keyless(providers.kitsu);
+  const cinemetaOpt = keyless(providers.cinemeta);
+
+  const core = {
+    baseUrl: baseUrl.replace(/\/+$/, '').replace(/\/v1$/, ''),
+    fetch: f,
+    timeoutMs,
+    retry: retry === false ? null : { max: retry?.max ?? 1, maxWaitMs: retry?.maxWaitMs ?? MAX_RETRY_AFTER_MS },
+    cache: createResponseCache(cache, { cacheTtlMs }),
+    breakers: breaker === false ? disabledBreakers() : createBreakers(breaker ?? {}),
+    keys,
+    sig: keySignature(keys),
+    providerCache: createByokCache(providerCache ? { storage: providerCache } : {}),
+    onProviderError: typeof onProviderError === 'function' ? onProviderError : null,
+  };
+
+  const cached = (key, load) => cachedIn(core.cache, key, load);
+  const kitsu = kitsuOpt && createKitsu({ fetch: f, timeoutMs: kitsuOpt.timeoutMs ?? 10_000, baseUrl: kitsuOpt.baseUrl });
+  const cinemeta = cinemetaOpt && createCinemeta({ fetch: f, timeoutMs: cinemetaOpt.timeoutMs ?? 10_000, baseUrl: cinemetaOpt.baseUrl });
+
+  core.providers = Object.freeze({
+    tmdb: tmdb && Object.freeze({
+      kind: tmdb.kind,
+      check: tmdb.check,
+      findByImdb: tmdb.findByImdb,
+      series: tmdb.tv,
+      movie: tmdb.movie,
+      season: tmdb.season,
+      search: tmdb.search,
+    }),
+    tvdb: tvdb && Object.freeze({
+      check: tvdb.check,
+      series: tvdb.seriesExtended,
+      movie: tvdb.movieExtended,
+      episodes: tvdb.episodes,
+      allEpisodes: tvdb.allEpisodes,
+      translation: tvdb.translation,
+      artworks: tvdb.artworks,
+      searchRemoteId: tvdb.searchRemoteId,
+    }),
+    fanart: fanart && Object.freeze({
+      check: fanart.check,
+      series: fanart.tv,
+      movie: fanart.movie,
+    }),
+    // Keyless ones go through the response cache: they are called often and change rarely.
+    kitsu: kitsu && Object.freeze({
+      anime: (id, signal) => cached(`kitsu:anime:${id}`, () => kitsu.anime(id, signal)),
+      episodes: (id, { max, signal } = {}) => cached(`kitsu:episodes:${id}:${max ?? ''}`, () => kitsu.episodes(id, { max, signal })),
+      relationships: (id, signal) => cached(`kitsu:relationships:${id}`, () => kitsu.relationships(id, signal)),
+      search: (text, { limit, signal } = {}) => cached(`kitsu:search:${String(text).toLowerCase()}:${limit ?? ''}`, () => kitsu.search(text, { limit, signal })),
+    }),
+    cinemeta: cinemeta && Object.freeze({
+      meta: (imdbId, type = 'series', signal) => cached(`cinemeta:${type}:${imdbId}`, () => cinemeta.meta(imdbId, type, signal)),
+      find: (imdbId, type = 'series', signal) => cached(`cinemeta:find:${type}:${imdbId}`, () => cinemeta.find(imdbId, type, signal)),
+    }),
+  });
+  return core;
+}
+
+async function cachedIn(cache, key, load) {
+  const hit = await cache.get(key);
+  if (hit) return hit.value;
+  const value = await load();
+  await cache.set(key, value);
+  return value;
+}
+
+export class Client {
+  #core;
+  #apiKey;
+
+  /**
+   * @param {object} options  see ClientOptions in index.d.ts
+   */
+  constructor(options = {}, internal = undefined) {
+    this.#apiKey = checkApiKey(options.apiKey);
+    this.#core = internal?.[CORE] ?? buildCore(options);
+  }
+
+  /** A client for another API key, sharing this one's cache, providers and breaker map. */
+  withApiKey(apiKey) {
+    return new Client({ apiKey }, { [CORE]: this.#core });
+  }
+
+  /**
+   * Provider clients: tmdb, tvdb, fanart (null without a key; raw provider JSON) and the
+   * keyless kitsu and cinemeta (null when disabled; normalized / raw Cinemeta metas).
+   */
+  get providers() {
+    return this.#core.providers;
+  }
+
+  /** Providers with a key, e.g. ['tmdb', 'tvdb']. */
+  get enrichment() {
+    return BYOK_PROVIDERS.filter((p) => this.#core.keys[p]);
+  }
+
+  // ---- Entries and mapping ------------------------------------------------------------
+
+  /** The entry for an anime ref, or null when the API does not know it. */
+  async entry(ref) {
+    const p = animeRef(ref);
+    return this.#cached(`entry:${p.ref}`, () => this.#orNull(this.#request('GET', `/v1/entries/${p.provider}/${p.id}`), (b) => b.entry));
+  }
+
+  /**
+   * Several entries at once, in batches of 100.
+   * Returns a Map keyed by the refs as given, each value an Entry or null.
+   */
+  async lookup(refs) {
+    if (!Array.isArray(refs)) throw new ClientError('invalid_argument', 'lookup() takes an array of anime refs');
+    const parsed = refs.map((r) => [r, animeRef(r)]);
+    const found = new Map();
+    const missing = [];
+    for (const [, p] of parsed) {
+      if (found.has(p.ref) || missing.includes(p.ref)) continue;
+      const hit = await this.#core.cache.get(`entry:${p.ref}`);
+      if (hit) found.set(p.ref, hit.value);
+      else missing.push(p.ref);
+    }
+    for (let i = 0; i < missing.length; i += LOOKUP_BATCH) {
+      const batch = missing.slice(i, i + LOOKUP_BATCH);
+      const body = await this.#request('POST', '/v1/entries/lookup', { refs: batch });
+      for (const ref of batch) {
+        const value = body.results?.[ref] ?? null;
+        found.set(ref, value);
+        await this.#core.cache.set(`entry:${ref}`, value);
+      }
+    }
+    return new Map(parsed.map(([input, p]) => [input, found.get(p.ref) ?? null]));
+  }
+
+  /**
+   * Translate an entry episode to a series episode.
+   * `target` picks tvdb, tmdb or imdb; without it the best match is returned.
+   * Returns { provider, id, season, episode, span, source, confidence } or null.
+   */
+  async toSeries(ref, episode, { target } = {}) {
+    const p = animeRef(ref);
+    checkInt(episode, 'episode', 1);
+    if (target !== undefined && !SERIES_PROVIDERS.includes(target)) {
+      throw new ClientError('invalid_argument', `target must be one of ${SERIES_PROVIDERS.join(', ')}`);
+    }
+    const body = await this.#episodes(`${p.ref}:${episode}`);
+    const hit = (body?.results ?? []).find((r) => !target || r.provider === target);
+    if (!hit) return null;
+    const { provider, id, season, episode: ep, span, source, confidence } = hit;
+    return { provider, id, season, episode: ep, span, source, confidence };
+  }
+
+  /**
+   * Translate a series episode back to the entries that contain it.
+   * Returns [{ entry, ids, episode, source, confidence }] (empty when none).
+   */
+  async fromSeries(ref, season, episode) {
+    const p = seriesRef(ref);
+    checkInt(season, 'season', 0);
+    checkInt(episode, 'episode', 1);
+    const body = await this.#episodes(`${p.ref}:${season}:${episode}`);
+    return body?.results ?? [];
+  }
+
+  /** Every mapped entry of a series, grouped by season. `season` narrows it to one. */
+  async series(ref, { season } = {}) {
+    const p = seriesRef(ref);
+    optionalInt(season, 'season', 0);
+    const qs = season === undefined || season === null ? '' : `?season=${season}`;
+    return this.#cached(`series:${p.ref}${qs}`, () => this.#request('GET', `/v1/series/${p.provider}/${p.id}${qs}`));
+  }
+
+  /** Entry search by title, alias or id. Returns EntrySummary[]. */
+  async search(query, { limit } = {}) {
+    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));
+    const body = await this.#cached(`search:${params}`, () => this.#request('GET', `/v1/search?${params}`));
+    return body.results ?? [];
+  }
+
+  /** Mapping issues; `entry` (an entry id or anime ref) and `type` filter them. */
+  async issues({ type, entry, cursor, limit } = {}) {
+    optionalInt(limit, 'limit', 1);
+    const params = new URLSearchParams();
+    if (type) params.set('type', type);
+    if (entry) params.set('entry', animeRef(entry).ref);
+    if (cursor) params.set('cursor', cursor);
+    if (limit !== undefined) params.set('limit', String(limit));
+    const qs = params.toString() ? `?${params}` : '';
+    return this.#cached(`issues:${qs}`, () => this.#request('GET', `/v1/issues${qs}`));
+  }
+
+  /** Edit history of an entry, newest first ([] when the entry is unknown). */
+  async history(ref) {
+    const p = animeRef(ref);
+    const body = await this.#orNull(this.#request('GET', `/v1/entries/${p.provider}/${p.id}/history`));
+    return body?.results ?? [];
+  }
+
+  // ---- Titles -------------------------------------------------------------------------
+
+  /**
+   * A whole show or film, by title id or any ref ("tt8948436", "kitsu:44607", "tvdb:342329").
+   * With provider keys, fields the API left empty are filled from TMDB, TVDB and Fanart.tv.
+   * Returns Title | null.
+   */
+  async title(ref, { enrich = true, signal } = {}) {
+    const server = await this.#serverTitle(ref);
+    if (!server || !enrich || !this.#core.sig) return server;
+    return (await this.enrichTitle(server, { signal })).title;
+  }
+
+  /**
+   * Fill a Title from the configured providers. Never overwrites a field the API filled.
+   * Returns { title, filled: { field: provider }, errors: [{ provider, code, message }], ids }.
+   * `title.provenance` also names the provider of every filled field.
+   */
+  async enrichTitle(server, { signal } = {}) {
+    if (!server || !this.#core.sig) return { title: server, filled: {}, errors: [], ids: server?.ids ?? null };
+    const { sources, errors } = await this.#sources(server, signal);
+    const { title, filled } = mergeTitle(server, sources);
+    if (Object.keys(filled).length) title.provenance = { ...(server.provenance ?? {}), ...filled };
+    return { title, filled, errors, ids: sources.ids ?? server.ids ?? null };
+  }
+
+  /**
+   * Episodes of one season of a title (the first season when `season` is omitted).
+   * With TMDB/TVDB keys, placeholder names and missing overviews, stills and air dates are
+   * filled. Returns { season, seasons, episodes } | null.
+   */
+  async titleEpisodes(ref, { season, enrich = true, signal } = {}) {
+    const id = parseTitleRef(ref);
+    optionalInt(season, 'season', 0);
+    const qs = season === undefined || season === null ? '' : `?season=${season}`;
+    const body = await this.#cached(`title-episodes:${id}${qs}`, () => this.#orNull(this.#request('GET', `/v1/titles/${id}/episodes${qs}`)));
+    const keys = this.#core.keys;
+    if (!body || !enrich || !(keys.tmdb || keys.tvdb) || body.season === null || !body.episodes?.length) return body;
+    const server = await this.#serverTitle(id);
+    if (!server) return body;
+    const { episodes } = await this.enrichEpisodes(server, body.season, body.episodes, { signal });
+    return { ...body, episodes };
+  }
+
+  /**
+   * Fill episode rows of one season from TMDB, then TVDB.
+   * Returns { episodes, filledBy: provider[], errors }.
+   */
+  async enrichEpisodes(title, season, episodes, { signal } = {}) {
+    const keys = this.#core.keys;
+    const sig = keySignature({ tmdb: keys.tmdb, tvdb: keys.tvdb });
+    if (!sig || !title || title.type === 'movie') return { episodes, filledBy: [], errors: [] };
+    const key = `${title.id}:${season}`;
+    let fills = await this.#core.providerCache.get('episodes', key, sig);
+    let errors = [];
+    if (!fills) {
+      // Ids found through TMDB (a TVDB id behind an IMDb-only title) come from the title sources.
+      const { sources } = await this.#sources(title, signal);
+      const res = await fetchEpisodeFills(title, season, keys, { fetch: this.#core.fetch, signal, ids: sources.ids });
+      fills = res.fills;
+      errors = res.errors;
+      this.#report(errors);
+      if (!errors.some(isTransient)) await this.#core.providerCache.set('episodes', key, sig, fills);
+    }
+    const merged = mergeEpisodes(episodes, fills);
+    return { episodes: merged.episodes, filledBy: [...merged.filledBy], errors };
+  }
+
+  /**
+   * 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 } = {}) {
+    optionalInt(year, 'year', 0);
+    optionalInt(limit, 'limit', 1);
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries({ q, type, format, year, genre, mapped, sort, cursor, limit })) {
+      if (v !== undefined && v !== null && v !== '') params.set(k, String(v).trim());
+    }
+    if (issues) params.set('issues', '1');
+    const qs = params.toString() ? `?${params}` : '';
+    return this.#cached(`titles:${qs}`, () => this.#request('GET', `/v1/titles${qs}`));
+  }
+
+  /** Kitsu's trending anime, resolved to titles. */
+  async trending({ limit } = {}) {
+    optionalInt(limit, 'limit', 1);
+    const qs = limit === undefined ? '' : `?limit=${limit}`;
+    const body = await this.#cached(`trending:${qs}`, () => this.#request('GET', `/v1/trending${qs}`));
+    return body.results ?? [];
+  }
+
+  /** Recent mapping edits. */
+  async activity({ limit } = {}) {
+    optionalInt(limit, 'limit', 1);
+    const qs = limit === undefined ? '' : `?limit=${limit}`;
+    const body = await this.#cached(`activity:${qs}`, () => this.#request('GET', `/v1/activity${qs}`));
+    return body.results ?? [];
+  }
+
+  /** Catalogue counts: { titles, entries, mappedEpisodes, ranges, sources, importedAt }. */
+  async stats() {
+    return this.#cached('stats', () => this.#request('GET', '/v1/stats'));
+  }
+
+  /** The most common genres: [{ name, count }]. */
+  async genres() {
+    const body = await this.#cached('genres', () => this.#request('GET', '/v1/genres'));
+    return body.results ?? [];
+  }
+
+  // ---- Service ------------------------------------------------------------------------
+
+  /** Dataset build and import times, counts and source versions. Not cached. */
+  async meta() {
+    return this.#request('GET', '/v1/meta');
+  }
+
+  /** The API key in use: { id, name, role, rateLimit, createdAt }. Not cached. */
+  async me() {
+    return (await this.#request('GET', '/v1/me')).key;
+  }
+
+  /**
+   * Check a provider key against the provider itself.
+   * Returns { state: 'connected' | 'invalid' | 'rate_limited' | 'error' | 'missing', message }.
+   */
+  async checkProvider(provider) {
+    if (!BYOK_PROVIDERS.includes(provider)) throw new ClientError('invalid_argument', `provider must be one of ${BYOK_PROVIDERS.join(', ')}`);
+    if (!this.#core.keys[provider]) return { state: 'missing', message: 'No key configured.' };
+    return checkKey(provider, this.#core.keys, { fetch: this.#core.fetch });
+  }
+
+  /** Milliseconds until the API is called again for this key after repeated failures; 0 when available. */
+  get pausedFor() {
+    return this.#core.breakers.openFor(this.#apiKey);
+  }
+
+  /** Forget every cached API response (provider results stay in the provider cache). */
+  async clearCache() {
+    await this.#core.cache.clear();
+  }
+
+  // ---- Internals ----------------------------------------------------------------------
+
+  #serverTitle(ref) {
+    const id = parseTitleRef(ref);
+    return this.#cached(`title:${id}`, () => this.#orNull(this.#request('GET', `/v1/titles/${id}`), (b) => b.title));
+  }
+
+  /** Normalized provider payloads for a title, cached per title and key signature. */
+  async #sources(server, signal) {
+    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;
+    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')) {
+      await core.providerCache.set('title', server.id, core.sig, sources);
+    }
+    return { sources, errors };
+  }
+
+  #report(errors) {
+    const handler = this.#core.onProviderError;
+    if (!handler) return;
+    for (const e of errors) {
+      try { handler(new ByokError(e.provider, e.code, e.message)); } catch { /* caller's handler */ }
+    }
+  }
+
+  // 404 means the ref is unknown: no translation.
+  #episodes(episodeRef) {
+    return this.#cached(`episodes:${episodeRef}`, () => this.#orNull(this.#request('GET', `/v1/episodes/${episodeRef}`)));
+  }
+
+  async #orNull(promise, pick = (b) => b) {
+    try {
+      return pick(await promise);
+    } catch (err) {
+      if (err.status === 404 && err.code === 'not_found') return null;
+      throw err;
+    }
+  }
+
+  #cached(key, load) {
+    return cachedIn(this.#core.cache, key, load);
+  }
+
+  async #request(method, path, body) {
+    const core = this.#core;
+    const apiKey = this.#apiKey;
+    const paused = core.breakers.openFor(apiKey);
+    if (paused > 0) {
+      throw unavailable('circuit_open', `The API failed repeatedly; calls resume in ${Math.ceil(paused / 1000)} s`, null, paused);
+    }
+    // Only these headers ever reach the API: provider keys stay with the provider clients.
+    const headers = { Accept: 'application/json', 'X-API-Key': apiKey };
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    const init = { method, headers, body: body === undefined ? undefined : JSON.stringify(body) };
+    const url = core.baseUrl + path;
+    const maxRetries = core.retry ? core.retry.max : 0;
+
+    for (let attempt = 0; ; attempt++) {
+      let res;
+      let text;
+      try {
+        ({ res, text } = await this.#attempt(url, init));
+      } catch (err) {
+        if (!err.timedOut && attempt < maxRetries) {
+          await sleep(NETWORK_RETRY_DELAY_MS * (attempt + 1));
+          continue;
+        }
+        core.breakers.failure(apiKey);
+        throw err.timedOut
+          ? unavailable('timeout', `Request to ${url} timed out after ${core.timeoutMs} ms`)
+          : unavailable('network_error', `Request to ${url} failed: ${err?.message ?? err}`);
+      }
+
+      if (res.status === 429) {
+        const wait = parseRetryAfter(res.headers.get('retry-after'));
+        if (attempt < maxRetries) {
+          await sleep(Math.min(wait, core.retry.maxWaitMs));
+          continue;
+        }
+        core.breakers.failure(apiKey, wait);
+        throw unavailable('rate_limited', this.#message(text, `Rate limited by ${url}`), 429, wait);
+      }
+      if (res.status >= 500) {
+        if (RETRYABLE_5XX.has(res.status) && attempt < maxRetries) {
+          await sleep(NETWORK_RETRY_DELAY_MS * (attempt + 1));
+          continue;
+        }
+        core.breakers.failure(apiKey);
+        throw unavailable('server_error', this.#message(text, `HTTP ${res.status} from ${url}`), res.status);
+      }
+
+      let data = null;
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          if (res.ok) {
+            core.breakers.failure(apiKey);
+            throw new ClientError('invalid_response', `Expected JSON from ${url}`, res.status);
+          }
+        }
+      }
+      core.breakers.success(apiKey);
+      if (res.ok) return data;
+      const err = data?.error ?? {};
+      throw new ClientError(
+        typeof err.code === 'string' ? err.code : codeForStatus(res.status),
+        typeof err.message === 'string' ? err.message : `HTTP ${res.status} from ${url}`,
+        res.status,
+        { details: err.details },
+      );
+    }
+  }
+
+  #message(text, fallback) {
+    try {
+      const m = JSON.parse(text)?.error?.message;
+      return typeof m === 'string' ? m : fallback;
+    } catch {
+      return fallback;
+    }
+  }
+
+  async #attempt(url, init) {
+    const ms = this.#core.timeoutMs;
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = ms > 0 ? setTimeout(() => { timedOut = true; controller.abort(); }, ms) : null;
+    try {
+      // The body is read here too, so the timeout covers a stalled download.
+      const res = await this.#core.fetch(url, { ...init, signal: controller.signal });
+      return { res, text: await res.text() };
+    } catch (err) {
+      if (timedOut) throw Object.assign(new Error('timeout'), { timedOut: true });
+      throw err;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+}

package/src/errors.js

@@ -0,0 +1,32 @@
+export class ClientError extends Error {
+  /**
+   * @param {string} code    server error code (unauthorized, forbidden, not_found, bad_request)
+   *                         or a client one: unavailable (the API could not answer: see
+   *                         `reason`), missing_api_key, missing_base_url, invalid_ref,
+   *                         invalid_argument, invalid_response
+   * @param {string} message
+   * @param {number|null} status  HTTP status, null when no response
+   * @param {object} [extra]  { details, reason, retryAfterMs }
+   */
+  constructor(code, message, status = null, extra = {}) {
+    super(message);
+    this.name = 'ClientError';
+    this.code = code;
+    this.status = status;
+    // Older call sites passed `details` as the fourth argument.
+    const opts = extra && typeof extra === 'object' && !Array.isArray(extra) && ('details' in extra || 'reason' in extra || 'retryAfterMs' in extra)
+      ? extra
+      : { details: extra };
+    if (opts.details !== undefined) this.details = opts.details;
+    if (opts.reason !== undefined) this.reason = opts.reason;
+    if (opts.retryAfterMs !== undefined) this.retryAfterMs = opts.retryAfterMs;
+  }
+}
+
+/**
+ * The API could not answer (as opposed to answering "not found"): `reason` is
+ * network_error | timeout | rate_limited | server_error | circuit_open.
+ */
+export function unavailable(reason, message, status = null, retryAfterMs) {
+  return new ClientError('unavailable', message, status, { reason, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}) });
+}