mcp-metacritic 1.0.0

package/dist/mc/client.js

@@ -0,0 +1,889 @@
+// src/version.ts
+var PKG_VERSION = "1.0.0";
+var REPO_URL = "https://github.com/smeet666/mcp-metacritic";
+
+// src/config.ts
+var DEFAULT_USER_AGENT = `mcp-metacritic v${PKG_VERSION} (${REPO_URL})`;
+var DEFAULTS = {
+  minIntervalMs: 1e3,
+  timeoutMs: 15e3,
+  maxRetries: 3,
+  // A catalogue entry moves when a title is edited, which is rare, so a day is
+  // safe. The cache lives in memory and dies with the process, so this is a
+  // ceiling on one session rather than a stored copy of the site.
+  cacheTtlMs: 24 * 60 * 60 * 1e3,
+  // Scores and reviews move as reviews come in, especially around a release,
+  // so they get their own much shorter lifetime.
+  scoresCacheTtlMs: 60 * 60 * 1e3,
+  cacheMaxEntries: 200,
+  logLevel: "error"
+};
+var MIN_ALLOWED_INTERVAL_MS = 500;
+var MAX_ALLOWED_INTERVAL_MS = 6e4;
+var LOG_LEVELS = ["silent", "error", "info", "debug"];
+function readNumber(name, env, range) {
+  const raw = env[name];
+  if (raw === void 0 || raw.trim() === "") return range.fallback;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) {
+    warn(`${name}="${raw}" is not a number, using ${range.fallback}`);
+    return range.fallback;
+  }
+  const rounded = Math.round(parsed);
+  if (rounded < range.min || rounded > range.max) {
+    warn(
+      `${name}=${raw} is outside the accepted range ${range.min}-${range.max} and was ignored; using ${range.fallback}`
+    );
+    return range.fallback;
+  }
+  return rounded;
+}
+function warn(message) {
+  process.stderr.write(`[mcp-metacritic] ${message}
+`);
+}
+function readInterval(env) {
+  const raw = env.MC_MIN_INTERVAL_MS;
+  if (raw === void 0 || raw.trim() === "") return DEFAULTS.minIntervalMs;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) {
+    warn(`MC_MIN_INTERVAL_MS="${raw}" is not a number, using ${DEFAULTS.minIntervalMs}ms`);
+    return DEFAULTS.minIntervalMs;
+  }
+  const rounded = Math.round(parsed);
+  if (rounded < MIN_ALLOWED_INTERVAL_MS) {
+    warn(
+      `MC_MIN_INTERVAL_MS=${raw} is below the ${MIN_ALLOWED_INTERVAL_MS}ms floor and was ignored; using ${DEFAULTS.minIntervalMs}ms. Metacritic publishes no rate limit, so this client sets its own.`
+    );
+    return DEFAULTS.minIntervalMs;
+  }
+  if (rounded > MAX_ALLOWED_INTERVAL_MS) {
+    warn(
+      `MC_MIN_INTERVAL_MS=${raw} exceeds the ${MAX_ALLOWED_INTERVAL_MS}ms ceiling; using ${MAX_ALLOWED_INTERVAL_MS}ms.`
+    );
+    return MAX_ALLOWED_INTERVAL_MS;
+  }
+  return rounded;
+}
+function loadConfig(env = process.env) {
+  const rawUserAgent = env.MC_USER_AGENT?.trim();
+  const rawLogLevel = env.MC_LOG_LEVEL?.trim().toLowerCase();
+  let logLevel = DEFAULTS.logLevel;
+  if (rawLogLevel) {
+    if (LOG_LEVELS.includes(rawLogLevel)) {
+      logLevel = rawLogLevel;
+    } else {
+      warn(`MC_LOG_LEVEL="${rawLogLevel}" is unknown, using "${DEFAULTS.logLevel}"`);
+    }
+  }
+  return {
+    userAgent: rawUserAgent || DEFAULT_USER_AGENT,
+    minIntervalMs: readInterval(env),
+    timeoutMs: readNumber("MC_TIMEOUT_MS", env, {
+      min: 1e3,
+      max: 12e4,
+      fallback: DEFAULTS.timeoutMs
+    }),
+    maxRetries: readNumber("MC_MAX_RETRIES", env, {
+      min: 0,
+      max: 10,
+      fallback: DEFAULTS.maxRetries
+    }),
+    cacheTtlMs: readNumber("MC_CACHE_TTL_MS", env, {
+      min: 0,
+      max: 7 * 24 * 60 * 60 * 1e3,
+      fallback: DEFAULTS.cacheTtlMs
+    }),
+    scoresCacheTtlMs: readNumber("MC_SCORES_CACHE_TTL_MS", env, {
+      min: 0,
+      max: 24 * 60 * 60 * 1e3,
+      fallback: DEFAULTS.scoresCacheTtlMs
+    }),
+    cacheMaxEntries: readNumber("MC_CACHE_MAX_ENTRIES", env, {
+      min: 0,
+      max: 1e4,
+      fallback: DEFAULTS.cacheMaxEntries
+    }),
+    logLevel
+  };
+}
+var LEVEL_RANK = { silent: 0, error: 1, info: 2, debug: 3 };
+function createLogger(level) {
+  const emit = (at, message) => {
+    if (LEVEL_RANK[level] >= LEVEL_RANK[at]) {
+      process.stderr.write(`[mcp-metacritic] ${message}
+`);
+    }
+  };
+  return {
+    error: (message) => emit("error", message),
+    info: (message) => emit("info", message),
+    debug: (message) => emit("debug", message)
+  };
+}
+
+// src/mc/cache.ts
+var TtlLruCache = class {
+  constructor(maxEntries, ttlMs) {
+    this.maxEntries = maxEntries;
+    this.ttlMs = ttlMs;
+  }
+  maxEntries;
+  ttlMs;
+  store = /* @__PURE__ */ new Map();
+  get(key) {
+    const entry = this.store.get(key);
+    if (!entry) return void 0;
+    if (Date.now() >= entry.expiresAt) {
+      this.store.delete(key);
+      return void 0;
+    }
+    this.store.delete(key);
+    this.store.set(key, entry);
+    return entry.value;
+  }
+  set(key, value) {
+    if (this.maxEntries <= 0 || this.ttlMs <= 0) return;
+    this.store.delete(key);
+    this.store.set(key, { value, expiresAt: Date.now() + this.ttlMs });
+    while (this.store.size > this.maxEntries) {
+      const oldest = this.store.keys().next();
+      if (oldest.done) break;
+      this.store.delete(oldest.value);
+    }
+  }
+  get size() {
+    return this.store.size;
+  }
+  clear() {
+    this.store.clear();
+  }
+};
+
+// src/errors.ts
+var McError = class extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "McError";
+  }
+  code;
+  details;
+};
+var ISSUES_URL = "https://github.com/smeet666/mcp-metacritic/issues";
+function notFound(url, what) {
+  return new McError("not_found", `Metacritic has no entry for ${what}.`, {
+    url,
+    status: 404,
+    hint: "Use search_titles to find an entry, then pass its slug and kind to this tool."
+  });
+}
+function invalidInput(message, hint) {
+  return new McError("invalid_input", message, hint ? { hint } : {});
+}
+function rateLimited(url, retryAfterMs) {
+  return new McError(
+    "rate_limited",
+    "Metacritic is refusing requests from this client for now. This does NOT mean the title is missing.",
+    {
+      url,
+      retryAfterMs,
+      hint: `Wait about ${Math.ceil(retryAfterMs / 1e3)} seconds, then call the same tool again with the same arguments. If it keeps happening, raise MC_MIN_INTERVAL_MS.`
+    }
+  );
+}
+function parseFailure(url, what) {
+  return new McError(
+    "parse_failure",
+    `Metacritic answered, but the response did not have the expected shape (${what}).`,
+    { url, hint: `Please report this, with the request you made, at ${ISSUES_URL}` }
+  );
+}
+function upstreamError(url, status) {
+  return new McError("network_error", `Metacritic returned HTTP ${status}.`, {
+    url,
+    status,
+    ...status >= 500 ? { hint: "This is a problem on Metacritic's side. Try again shortly." } : {}
+  });
+}
+
+// src/mc/rateLimiter.ts
+var DEFAULT_MAX_INTERVAL_MS = 1e4;
+var RateLimiter = class {
+  baseIntervalMs;
+  maxIntervalMs;
+  intervalMs;
+  /** Tail of the queue: each task chains onto the previous one. */
+  tail = Promise.resolve();
+  lastStart = 0;
+  constructor(options) {
+    this.baseIntervalMs = Math.max(0, options.minIntervalMs);
+    this.maxIntervalMs = Math.max(
+      this.baseIntervalMs,
+      options.maxIntervalMs ?? DEFAULT_MAX_INTERVAL_MS
+    );
+    this.intervalMs = this.baseIntervalMs;
+  }
+  get currentIntervalMs() {
+    return this.intervalMs;
+  }
+  /**
+   * Queue a task. Tasks run in call order, one at a time.
+   *
+   * A task may send several requests, since the retry loop lives inside its
+   * slot. It must call `beforeRequest` around each of them: the pacing is
+   * measured between requests, and stamping only the start of the task would
+   * let the next one follow a long retry chain's final request immediately.
+   */
+  schedule(task) {
+    const run = this.tail.then(async () => task());
+    this.tail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+  /**
+   * Wait for this request's slot, then claim it.
+   *
+   * Called once per upstream request rather than once per task, so every
+   * request is paced from the previous one whether or not they belong to the
+   * same retry chain.
+   */
+  async beforeRequest() {
+    await this.waitForSlot();
+    this.lastStart = Date.now();
+  }
+  /** Called after the site signals it is under load. */
+  penalize() {
+    const next = this.intervalMs === 0 ? 250 : this.intervalMs * 2;
+    this.intervalMs = Math.min(this.maxIntervalMs, next);
+  }
+  /** Called after a success, so a single hiccup does not slow things down forever. */
+  relax() {
+    this.intervalMs = Math.max(this.baseIntervalMs, Math.floor(this.intervalMs * 0.75));
+  }
+  async waitForSlot() {
+    if (this.intervalMs === 0 || this.lastStart === 0) return;
+    const elapsed = Date.now() - this.lastStart;
+    const remaining = Math.min(this.intervalMs, this.intervalMs - elapsed);
+    if (remaining > 0) await sleep(remaining);
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/mc/http.ts
+var BACKOFF_BASE_MS = 2e3;
+var BACKOFF_FACTOR = 2;
+var BACKOFF_MAX_MS = 2e4;
+function backoffDelay(attempt, random = Math.random) {
+  const capped = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * BACKOFF_FACTOR ** attempt);
+  return Math.round(capped * (0.5 + random() * 0.5));
+}
+async function fetchText(url, deps) {
+  const { config, limiter, logger } = deps;
+  const doFetch = deps.fetchImpl ?? fetch;
+  return limiter.schedule(async () => {
+    let lastError;
+    let askedWaitMs = null;
+    for (let attempt = 0; attempt <= config.maxRetries; attempt += 1) {
+      if (attempt > 0) {
+        const delay = askedWaitMs ?? backoffDelay(attempt - 1);
+        askedWaitMs = null;
+        logger.info(`retry ${attempt}/${config.maxRetries} in ${delay}ms for ${url}`);
+        await sleep(Math.min(delay, BACKOFF_MAX_MS));
+      }
+      let status;
+      let body;
+      let retryAfterMs = null;
+      try {
+        await limiter.beforeRequest();
+        const response = await doFetch(url, {
+          headers: {
+            "User-Agent": config.userAgent,
+            Accept: "application/json,*/*;q=0.8"
+          },
+          redirect: "follow",
+          signal: AbortSignal.timeout(config.timeoutMs)
+        });
+        status = response.status;
+        retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
+        body = await response.text();
+      } catch (error) {
+        lastError = asTransportError(error, url);
+        logger.debug(`${lastError.code} for ${url}: ${lastError.message}`);
+        continue;
+      }
+      if (status === 429 || status === 503 || status === 403) {
+        limiter.penalize();
+        askedWaitMs = retryAfterMs;
+        lastError = rateLimited(url, retryAfterMs ?? backoffDelay(attempt));
+        logger.info(
+          `refused on ${url} with ${status}, interval now ${limiter.currentIntervalMs}ms`
+        );
+        continue;
+      }
+      if (status >= 500) {
+        lastError = upstreamError(url, status);
+        continue;
+      }
+      if (status === 404) throw notFound(url, "that request");
+      if (status >= 400) throw upstreamError(url, status);
+      const trimmed = body.trim();
+      if (trimmed === "") {
+        limiter.penalize();
+        lastError = rateLimited(url, backoffDelay(attempt));
+        logger.info(`empty body on ${url}, treating as a refusal`);
+        continue;
+      }
+      if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+        limiter.penalize();
+        lastError = parseFailure(url, "the body is not JSON");
+        askedWaitMs = retryAfterMs;
+        logger.info(`non-JSON body on ${url}, retrying`);
+        continue;
+      }
+      limiter.relax();
+      return body;
+    }
+    throw lastError ?? new McError("network_error", `Could not fetch ${url}.`, { url });
+  });
+}
+function parseRetryAfter(raw) {
+  if (!raw) return null;
+  const seconds = Number(raw.trim());
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1e3);
+  const when = Date.parse(raw);
+  if (Number.isNaN(when)) return null;
+  return Math.max(0, when - Date.now());
+}
+function asTransportError(error, url) {
+  if (error instanceof McError) return error;
+  const name = error instanceof Error ? error.name : "";
+  if (name === "TimeoutError" || name === "AbortError") {
+    return new McError("timeout", "Metacritic did not answer in time.", {
+      url,
+      hint: "Raise MC_TIMEOUT_MS if this happens often on a slow connection."
+    });
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return new McError("network_error", `Could not reach Metacritic: ${message}`, { url });
+}
+
+// src/mc/paths.ts
+var API_BASE = "https://backend.metacritic.com";
+var SITE_BASE = "https://www.metacritic.com";
+var API_SEGMENT = {
+  movie: "movies",
+  show: "shows",
+  game: "games"
+};
+var SITE_SEGMENT = {
+  movie: "movie",
+  show: "tv",
+  game: "game"
+};
+var MCO_TYPE_ID = {
+  show: 1,
+  movie: 2,
+  game: 13
+};
+var SEARCH_TYPE = {
+  movie: "movie",
+  show: "show",
+  game: "game-title"
+};
+var SORT_BY = {
+  score: "-metaScore",
+  recent: "-releaseDate",
+  popular: "-popularityCount"
+};
+var COMPONENT = {
+  product: { componentName: "product", componentType: "Product" },
+  criticStats: { componentName: "critic-score-summary", componentType: "MetaScoreSummary" },
+  userStats: { componentName: "user-score-summary", componentType: "MetaScoreSummary" },
+  criticReviews: { componentName: "critic-reviews", componentType: "ProductReviewsSummary" },
+  userReviews: { componentName: "user-reviews", componentType: "ProductReviewsSummary" }
+};
+var FIELD = {
+  data: "data",
+  errors: "errors",
+  item: "item",
+  items: "items",
+  totalResults: "totalResults",
+  /** Reviews arrive pre-sorted into these buckets, which is the sentiment filter. */
+  reviewBuckets: { all: "default", positive: "positive", neutral: "neutral", negative: "negative" }
+};
+
+// src/mc/urls.ts
+function build(path, params) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== void 0 && value !== "") query.set(key, String(value));
+  }
+  const suffix = query.toString();
+  return suffix ? `${API_BASE}${path}?${suffix}` : `${API_BASE}${path}`;
+}
+function checkSlug(slug) {
+  const trimmed = slug.trim();
+  if (trimmed === "") {
+    throw invalidInput("The slug is empty.", "Take it from a search_titles result.");
+  }
+  if (!/^[a-z0-9][a-z0-9-]*$/i.test(trimmed)) {
+    throw invalidInput(
+      `"${slug}" does not look like a Metacritic slug.`,
+      "Slugs are lowercase words joined by hyphens, such as the-matrix. Use search_titles to get one."
+    );
+  }
+  return trimmed;
+}
+function searchUrl(query, limit, offset) {
+  const trimmed = query.trim();
+  if (trimmed === "") {
+    throw invalidInput("The search query is empty.", "Pass a title or part of one.");
+  }
+  return build(`/finder/metacritic/search/${encodeURIComponent(trimmed)}/web`, { limit, offset });
+}
+function browseUrl(options) {
+  return build("/finder/metacritic/web", {
+    sortBy: SORT_BY[options.sort],
+    mcoTypeId: MCO_TYPE_ID[options.kind],
+    genres: options.genre,
+    limit: options.limit,
+    offset: options.offset
+  });
+}
+function detailUrl(kind, slug) {
+  return build(`/${API_SEGMENT[kind]}/metacritic/${checkSlug(slug)}/web`, COMPONENT.product);
+}
+function scoreUrl(kind, slug, source) {
+  const component = source === "critic" ? COMPONENT.criticStats : COMPONENT.userStats;
+  return build(
+    `/reviews/metacritic/${source}/${API_SEGMENT[kind]}/${checkSlug(slug)}/stats/web`,
+    component
+  );
+}
+function reviewsUrl(options) {
+  const component = options.source === "critic" ? COMPONENT.criticReviews : COMPONENT.userReviews;
+  return build(
+    `/reviews/metacritic/${options.source}/${API_SEGMENT[options.kind]}/${checkSlug(options.slug)}/summary/web`,
+    component
+  );
+}
+function watchUrl(imdbId, kind) {
+  const trimmed = imdbId.trim();
+  if (!/^tt\d+$/.test(trimmed)) {
+    throw invalidInput(
+      `"${imdbId}" is not an IMDb id.`,
+      "IMDb ids look like tt0133093. get_title returns one as imdb_id."
+    );
+  }
+  return build("/justwatch/metacritic/offersByIMDbId", {
+    id: trimmed,
+    type: kind === "show" ? "show" : "movie"
+  });
+}
+function titlePageUrl(kind, slug) {
+  return `${SITE_BASE}/${SITE_SEGMENT[kind]}/${slug}/`;
+}
+function bucketFor(sentiment) {
+  return sentiment === "all" ? "default" : sentiment;
+}
+
+// src/mc/parse.ts
+var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function envelope(raw, url, what) {
+  let body;
+  try {
+    body = JSON.parse(raw);
+  } catch {
+    throw parseFailure(url, "the body is not valid JSON");
+  }
+  if (!isObject(body)) throw parseFailure(url, "the body is not an object");
+  const errors = body[FIELD.errors];
+  if (Array.isArray(errors) && errors.length > 0) {
+    const first = isObject(errors[0]) ? errors[0] : {};
+    if (first.code === 404) throw notFound(url, what);
+    throw parseFailure(
+      url,
+      `the site reported ${String(first.reason ?? first.code ?? "an error")}`
+    );
+  }
+  const data = body[FIELD.data];
+  if (!isObject(data)) throw parseFailure(url, "the response carries no data object");
+  return data;
+}
+var str = (value) => {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+};
+var num = (value) => {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+};
+var intOf = (value) => {
+  const parsed = num(value);
+  return parsed === null ? null : Math.trunc(parsed);
+};
+function kindOf(value) {
+  const type = str(value);
+  if (type === SEARCH_TYPE.movie) return "movie";
+  if (type === SEARCH_TYPE.show) return "show";
+  if (type === SEARCH_TYPE.game) return "game";
+  return null;
+}
+function toSummary(node) {
+  if (!isObject(node)) return null;
+  const id = intOf(node.id);
+  const slug = str(node.slug);
+  const title = str(node.title);
+  const kind = kindOf(node.type);
+  if (id === null || !slug || !title || !kind) return null;
+  const critic = isObject(node.criticScoreSummary) ? node.criticScoreSummary : {};
+  const userSummary = isObject(node.userScoreSummary) ? node.userScoreSummary : {};
+  const userObject = isObject(node.userScore) ? node.userScore : {};
+  const userScore = num(userSummary.score) ?? num(userObject.score) ?? num(node.userScore);
+  return {
+    id,
+    kind,
+    title,
+    slug,
+    year: intOf(node.premiereYear),
+    releaseDate: str(node.releaseDate),
+    rating: str(node.rating),
+    metascore: num(critic.score),
+    userScore,
+    sourceUrl: titlePageUrl(kind, slug)
+  };
+}
+function parseTitlePage(raw, url, what) {
+  const data = envelope(raw, url, what);
+  const items = data[FIELD.items];
+  if (!Array.isArray(items)) throw parseFailure(url, "the response carries no items array");
+  const titles = [];
+  for (const node of items) {
+    const row = toSummary(node);
+    if (row) titles.push(row);
+  }
+  if (items.length > 0 && titles.length === 0) {
+    throw parseFailure(url, `${items.length} rows but none could be read`);
+  }
+  return {
+    titles,
+    totalResults: intOf(data[FIELD.totalResults]) ?? titles.length,
+    itemCount: items.length
+  };
+}
+function toCompanies(value) {
+  const source = isObject(value) ? value.companies : value;
+  if (!Array.isArray(source)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const node of source) {
+    const name = isObject(node) ? str(node.name) : str(node);
+    if (!name) continue;
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ name, id: isObject(node) ? intOf(node.id) : null });
+  }
+  return out;
+}
+function toStringList(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const node of value) {
+    const name = isObject(node) ? str(node.name) : str(node);
+    if (name) out.push(name);
+  }
+  return out;
+}
+function toAwards(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const node of value) {
+    if (!isObject(node)) continue;
+    const ceremony = str(node.awardEvent);
+    if (!ceremony) continue;
+    out.push({
+      ceremony,
+      wins: intOf(node.wins),
+      nominations: intOf(node.nominations)
+    });
+  }
+  return out;
+}
+function parseDetail(raw, url, kind, slug) {
+  const data = envelope(raw, url, `${kind} "${slug}"`);
+  const item = data[FIELD.item];
+  if (!isObject(item)) throw parseFailure(url, "the response carries no item object");
+  const id = intOf(item.id);
+  const title = str(item.title);
+  if (id === null || !title) throw parseFailure(url, "the entry has no id or no title");
+  const critic = isObject(item.criticScoreSummary) ? item.criticScoreSummary : {};
+  return {
+    id,
+    kind,
+    title,
+    slug,
+    year: intOf(item.premiereYear),
+    releaseDate: str(item.releaseDate),
+    rating: str(item.rating),
+    metascore: num(critic.score),
+    userScore: null,
+    sourceUrl: titlePageUrl(kind, slug),
+    description: str(item.description),
+    tagline: str(item.tagline),
+    genres: toStringList(item.genres),
+    duration: intOf(item.duration),
+    imdbId: str(item.imdbId),
+    networks: toStringList(item.networks),
+    production: toCompanies(item.production),
+    awards: toAwards(item.awards),
+    criticScoreDetail: null,
+    userScoreDetail: null
+  };
+}
+function parseScore(raw, url, what) {
+  const data = envelope(raw, url, what);
+  const item = data[FIELD.item];
+  if (!isObject(item)) throw parseFailure(url, "the response carries no score object");
+  const max = num(item.max);
+  if (max === null) throw parseFailure(url, "the score carries no scale");
+  return {
+    score: num(item.score),
+    max,
+    reviewCount: intOf(item.reviewCount),
+    positiveCount: intOf(item.positiveCount),
+    neutralCount: intOf(item.neutralCount),
+    negativeCount: intOf(item.negativeCount),
+    sentiment: str(item.sentiment)
+  };
+}
+function reviewBucket(data, url, sentiment) {
+  const item = data[FIELD.item];
+  if (!isObject(item)) throw parseFailure(url, "the response carries no reviews object");
+  const bucket = item[bucketFor(sentiment)];
+  if (!Array.isArray(bucket)) {
+    throw parseFailure(url, `there is no "${bucketFor(sentiment)}" group of reviews`);
+  }
+  return bucket;
+}
+function parseCriticReviews(raw, url, what, sentiment) {
+  const data = envelope(raw, url, what);
+  const bucket = reviewBucket(data, url, sentiment);
+  const reviews = [];
+  for (const node of bucket) {
+    if (!isObject(node)) continue;
+    const quote = str(node.quote);
+    const publication = str(node.publicationName);
+    if (!quote || !publication) continue;
+    reviews.push({
+      quote,
+      score: num(node.score),
+      publication,
+      author: str(node.author),
+      url: str(node.url),
+      date: str(node.date)
+    });
+  }
+  if (bucket.length > 0 && reviews.length === 0) {
+    throw parseFailure(url, `${bucket.length} reviews but none could be read`);
+  }
+  return {
+    reviews,
+    totalResults: intOf(data[FIELD.totalResults]) ?? reviews.length,
+    itemCount: bucket.length
+  };
+}
+function parseUserReviews(raw, url, what, sentiment) {
+  const data = envelope(raw, url, what);
+  const bucket = reviewBucket(data, url, sentiment);
+  const reviews = [];
+  for (const node of bucket) {
+    if (!isObject(node)) continue;
+    const quote = str(node.quote);
+    if (!quote) continue;
+    reviews.push({ quote, score: num(node.score), date: str(node.date) });
+  }
+  if (bucket.length > 0 && reviews.length === 0) {
+    throw parseFailure(url, `${bucket.length} reviews but none could be read`);
+  }
+  return {
+    reviews,
+    totalResults: intOf(data[FIELD.totalResults]) ?? reviews.length,
+    itemCount: bucket.length
+  };
+}
+function unwrapLink(link) {
+  if (!link) return null;
+  try {
+    const target = new URL(link).searchParams.get("r");
+    if (target && /^https?:\/\//i.test(target)) return target;
+  } catch {
+  }
+  return link;
+}
+function parseOffers(raw, url, what) {
+  const data = envelope(raw, url, what);
+  const item = data[FIELD.item];
+  if (!isObject(item)) throw parseFailure(url, "the response carries no offers object");
+  const offers = [];
+  for (const [group, value] of Object.entries(item)) {
+    if (!Array.isArray(value)) continue;
+    for (const node of value) {
+      if (!isObject(node)) continue;
+      const provider = str(node.providerName);
+      if (!provider) continue;
+      offers.push({ provider, kind: group, url: unwrapLink(str(node.link)) });
+    }
+  }
+  return offers;
+}
+
+// src/mc/client.ts
+function withGuarantees(config) {
+  const userAgent = /mozilla\/|applewebkit|chrome\/|safari\/|gecko/i.test(config.userAgent) ? `${config.userAgent} ${DEFAULT_USER_AGENT}` : config.userAgent;
+  return {
+    ...config,
+    userAgent,
+    minIntervalMs: Math.max(MIN_ALLOWED_INTERVAL_MS, config.minIntervalMs)
+  };
+}
+var McClient = class {
+  config;
+  logger;
+  limiter;
+  /**
+   * Two caches, because the two kinds of data age at different speeds. A
+   * catalogue entry changes when someone edits it, which is rare. A score moves
+   * every time a review lands, which around a release is constantly.
+   */
+  catalogueCache;
+  scoresCache;
+  fetchImpl;
+  constructor(options = {}) {
+    this.config = withGuarantees(options.config ?? loadConfig());
+    this.logger = options.logger ?? createLogger(this.config.logLevel);
+    this.limiter = new RateLimiter({ minIntervalMs: this.config.minIntervalMs });
+    this.catalogueCache = new TtlLruCache(
+      this.config.cacheMaxEntries,
+      this.config.cacheTtlMs
+    );
+    this.scoresCache = new TtlLruCache(
+      this.config.cacheMaxEntries,
+      this.config.scoresCacheTtlMs
+    );
+    this.fetchImpl = options.fetchImpl;
+  }
+  /**
+   * Search across films, shows and games.
+   *
+   * The return type carries rows only. The upstream response embeds artwork
+   * variants on every match, and dropping them here rather than in a tool means
+   * they have no path out of this layer.
+   */
+  async search(query, limit, offset) {
+    const url = searchUrl(query, limit, offset);
+    return this.fetchParsed(
+      url,
+      this.catalogueCache,
+      (body) => parseTitlePage(body, url, `the query "${query}"`)
+    );
+  }
+  async browse(options) {
+    const url = browseUrl(options);
+    return this.fetchParsed(
+      url,
+      this.catalogueCache,
+      (body) => parseTitlePage(body, url, `that ${options.kind} listing`)
+    );
+  }
+  async getDetail(kind, slug) {
+    const url = detailUrl(kind, slug);
+    const clean = slug.trim();
+    return this.fetchParsed(
+      url,
+      this.catalogueCache,
+      (body) => parseDetail(body, url, kind, clean)
+    );
+  }
+  async getScore(kind, slug, source) {
+    const url = scoreUrl(kind, slug, source);
+    return this.fetchParsed(
+      url,
+      this.scoresCache,
+      (body) => parseScore(body, url, `the ${source} score of ${kind} "${slug}"`)
+    );
+  }
+  async getCriticReviews(options) {
+    const url = reviewsUrl({ ...options, source: "critic" });
+    return this.fetchParsed(
+      url,
+      this.scoresCache,
+      (body) => parseCriticReviews(
+        body,
+        url,
+        `reviews of ${options.kind} "${options.slug}"`,
+        options.sentiment
+      ),
+      options.sentiment
+    );
+  }
+  async getUserReviews(options) {
+    const url = reviewsUrl({ ...options, source: "user" });
+    return this.fetchParsed(
+      url,
+      this.scoresCache,
+      (body) => parseUserReviews(
+        body,
+        url,
+        `reviews of ${options.kind} "${options.slug}"`,
+        options.sentiment
+      ),
+      options.sentiment
+    );
+  }
+  async getWatchOffers(imdbId, kind) {
+    const url = watchUrl(imdbId, kind);
+    return this.fetchParsed(
+      url,
+      this.scoresCache,
+      (body) => parseOffers(body, url, `streaming offers for ${imdbId}`)
+    );
+  }
+  /**
+   * Fetch, parse, then cache. In that order: a response that could not be read
+   * is never stored, so a bad minute upstream cannot be replayed from memory
+   * for the rest of the cache lifetime.
+   */
+  async fetchParsed(url, cache, parse, variant = "") {
+    const key = variant ? `${url}#${variant}` : url;
+    const hit = cache.get(key);
+    if (hit !== void 0) {
+      this.logger.debug(`cache hit ${key}`);
+      return { data: hit, cached: true };
+    }
+    const body = await fetchText(url, {
+      config: this.config,
+      limiter: this.limiter,
+      logger: this.logger,
+      ...this.fetchImpl ? { fetchImpl: this.fetchImpl } : {}
+    });
+    const data = parse(body);
+    cache.set(key, data);
+    return { data, cached: false };
+  }
+};
+export {
+  McClient
+};
+//# sourceMappingURL=client.js.map