mcp-metacritic 1.2.0 → 2.0.0

package/dist/mc/client.js

@@ -1,5 +1,8 @@
+// src/config.ts
+import process from "process";
+
 // src/version.ts
-var PKG_VERSION = "1.2.0";
+var PKG_VERSION = "2.0.0";
 var REPO_URL = "https://github.com/smeet666/mcp-metacritic";
 
 // src/config.ts
@@ -23,7 +26,9 @@ 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;
+  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}`);
@@ -44,7 +49,9 @@ function warn(message) {
 }
 function readInterval(env) {
   const raw = env.MC_MIN_INTERVAL_MS;
-  if (raw === void 0 || raw.trim() === "") return DEFAULTS.minIntervalMs;
+  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`);
@@ -133,7 +140,9 @@ var TtlLruCache = class {
   store = /* @__PURE__ */ new Map();
   get(key) {
     const entry = this.store.get(key);
-    if (!entry) return void 0;
+    if (!entry) {
+      return void 0;
+    }
     if (Date.now() >= entry.expiresAt) {
       this.store.delete(key);
       return void 0;
@@ -143,12 +152,16 @@ var TtlLruCache = class {
     return entry.value;
   }
   set(key, value) {
-    if (this.maxEntries <= 0 || this.ttlMs <= 0) return;
+    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;
+      if (oldest.done) {
+        break;
+      }
       this.store.delete(oldest.value);
     }
   }
@@ -163,7 +176,7 @@ var TtlLruCache = class {
 // src/errors.ts
 var McError = class extends Error {
   constructor(code, message, details = {}) {
-    super(message);
+    super(message, details.cause === void 0 ? void 0 : { cause: details.cause });
     this.code = code;
     this.details = details;
     this.name = "McError";
@@ -193,11 +206,11 @@ function rateLimited(url, retryAfterMs) {
     }
   );
 }
-function parseFailure(url, what) {
+function parseFailure(url, what, cause) {
   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}` }
+    { url, hint: `Please report this, with the request you made, at ${ISSUES_URL}`, cause }
   );
 }
 function upstreamError(url, status) {
@@ -265,10 +278,14 @@ var RateLimiter = class {
     this.intervalMs = Math.max(this.baseIntervalMs, Math.floor(this.intervalMs * 0.75));
   }
   async waitForSlot() {
-    if (this.intervalMs === 0 || this.lastStart === 0) return;
+    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);
+    if (remaining > 0) {
+      await sleep(remaining);
+    }
   }
 };
 function sleep(ms) {
@@ -283,10 +300,57 @@ 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));
 }
+function readAnswer(url, status, body, retryAfterMs, ownGuessMs) {
+  if (status === 429 || status === 503 || status === 403) {
+    return {
+      kind: "again",
+      error: rateLimited(url, retryAfterMs ?? ownGuessMs),
+      // A server that says when to come back knows better than our own guess.
+      waitMs: retryAfterMs,
+      penalise: true,
+      because: `refused with ${status}`
+    };
+  }
+  if (status >= 500) {
+    return {
+      kind: "again",
+      error: upstreamError(url, status),
+      waitMs: null,
+      penalise: false,
+      because: `status ${status}`
+    };
+  }
+  if (status === 404) {
+    return { kind: "refused", error: notFound(url, "that request") };
+  }
+  if (status >= 400) {
+    return { kind: "refused", error: upstreamError(url, status) };
+  }
+  const trimmed = body.trim();
+  if (trimmed === "") {
+    return {
+      kind: "again",
+      error: rateLimited(url, ownGuessMs),
+      waitMs: null,
+      penalise: true,
+      because: "empty body, treated as a refusal"
+    };
+  }
+  if (!(trimmed.startsWith("{") || trimmed.startsWith("["))) {
+    return {
+      kind: "again",
+      error: parseFailure(url, "the body is not JSON"),
+      waitMs: retryAfterMs,
+      penalise: true,
+      because: "non-JSON body"
+    };
+  }
+  return { kind: "usable" };
+}
 async function fetchText(url, deps) {
   const { config, limiter, logger } = deps;
   const doFetch = deps.fetchImpl ?? fetch;
-  return limiter.schedule(async () => {
+  return await limiter.schedule(async () => {
     let lastError;
     let askedWaitMs = null;
     for (let attempt = 0; attempt <= config.maxRetries; attempt += 1) {
@@ -317,33 +381,17 @@ async function fetchText(url, deps) {
         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;
+      const verdict = readAnswer(url, status, body, retryAfterMs, backoffDelay(attempt));
+      if (verdict.kind === "refused") {
+        throw verdict.error;
       }
-      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`);
+      if (verdict.kind === "again") {
+        if (verdict.penalise) {
+          limiter.penalize();
+          logger.info(`${verdict.because} on ${url}, interval now ${limiter.currentIntervalMs}ms`);
+        }
+        askedWaitMs = verdict.waitMs;
+        lastError = verdict.error;
         continue;
       }
       limiter.relax();
@@ -353,15 +401,23 @@ async function fetchText(url, deps) {
   });
 }
 function parseRetryAfter(raw) {
-  if (!raw) return null;
+  if (!raw) {
+    return null;
+  }
   const seconds = Number(raw.trim());
-  if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1e3);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.round(seconds * 1e3);
+  }
   const when = Date.parse(raw);
-  if (Number.isNaN(when)) return null;
+  if (Number.isNaN(when)) {
+    return null;
+  }
   return Math.max(0, when - Date.now());
 }
 function asTransportError(error, url) {
-  if (error instanceof McError) return error;
+  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.", {
@@ -419,10 +475,14 @@ var FIELD = {
 };
 
 // src/mc/urls.ts
+var SLUG = /^[a-z0-9][a-z0-9-]*$/i;
+var IMDB_ID = /^tt\d+$/;
 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));
+    if (value !== void 0 && value !== "") {
+      query.set(key, String(value));
+    }
   }
   const suffix = query.toString();
   return suffix ? `${API_BASE}${path}?${suffix}` : `${API_BASE}${path}`;
@@ -432,7 +492,7 @@ function checkSlug(slug) {
   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)) {
+  if (!SLUG.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."
@@ -475,7 +535,7 @@ function reviewsUrl(options) {
 }
 function watchUrl(imdbId, kind) {
   const trimmed = imdbId.trim();
-  if (!/^tt\d+$/.test(trimmed)) {
+  if (!IMDB_ID.test(trimmed)) {
     throw invalidInput(
       `"${imdbId}" is not an IMDb id.`,
       "IMDb ids look like tt0133093. get_title returns one as imdb_id."
@@ -494,38 +554,51 @@ function bucketFor(sentiment) {
 }
 
 // src/mc/parse.ts
+var ABSOLUTE_URL = /^https?:\/\//i;
 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");
+  } catch (cause) {
+    throw parseFailure(url, "the body is not valid JSON", cause);
+  }
+  if (!isObject(body)) {
+    throw parseFailure(url, "the body is not an object");
   }
-  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);
+    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");
+  if (!isObject(data)) {
+    throw parseFailure(url, "the response carries no data object");
+  }
   return data;
 }
 var str = (value) => {
-  if (typeof value !== "string") return null;
+  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 === "number" && Number.isFinite(value)) {
+    return value;
+  }
   if (typeof value === "string") {
     const parsed = Number(value);
-    if (Number.isFinite(parsed)) return parsed;
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
   }
   return null;
 };
@@ -539,18 +612,28 @@ var aggregate = (value) => {
 };
 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";
+  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;
+  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;
+  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 : {};
@@ -571,11 +654,15 @@ function toSummary(node) {
 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");
+  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 (row) {
+      titles.push(row);
+    }
   }
   if (items.length > 0 && titles.length === 0) {
     throw parseFailure(url, `${items.length} rows but none could be read`);
@@ -588,35 +675,51 @@ function parseTitlePage(raw, url, what) {
 }
 function toCompanies(value) {
   const source = isObject(value) ? value.companies : value;
-  if (!Array.isArray(source)) return [];
+  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;
+    if (!name) {
+      continue;
+    }
     const key = name.toLowerCase();
-    if (seen.has(key)) continue;
+    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 [];
+  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);
+    if (name) {
+      out.push(name);
+    }
   }
   return out;
 }
 function toAwards(value) {
-  if (!Array.isArray(value)) return [];
+  if (!Array.isArray(value)) {
+    return [];
+  }
   const out = [];
   for (const node of value) {
-    if (!isObject(node)) continue;
+    if (!isObject(node)) {
+      continue;
+    }
     const ceremony = str(node.awardEvent);
-    if (!ceremony) continue;
+    if (!ceremony) {
+      continue;
+    }
     out.push({
       ceremony,
       wins: intOf(node.wins),
@@ -628,10 +731,14 @@ function toAwards(value) {
 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");
+  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");
+  if (id === null || !title) {
+    throw parseFailure(url, "the entry has no id or no title");
+  }
   const critic = isObject(item.criticScoreSummary) ? item.criticScoreSummary : {};
   return {
     id,
@@ -659,9 +766,13 @@ function parseDetail(raw, url, kind, slug) {
 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");
+  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");
+  if (max === null) {
+    throw parseFailure(url, "the score carries no scale");
+  }
   return {
     score: aggregate(item.score),
     max,
@@ -674,7 +785,9 @@ function parseScore(raw, url, what) {
 }
 function reviewBucket(data, url, sentiment) {
   const item = data[FIELD.item];
-  if (!isObject(item)) throw parseFailure(url, "the response carries no reviews object");
+  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`);
@@ -686,10 +799,14 @@ function parseCriticReviews(raw, url, what, sentiment) {
   const bucket = reviewBucket(data, url, sentiment);
   const reviews = [];
   for (const node of bucket) {
-    if (!isObject(node)) continue;
+    if (!isObject(node)) {
+      continue;
+    }
     const quote = str(node.quote);
     const publication = str(node.publicationName);
-    if (!quote || !publication) continue;
+    if (!(quote && publication)) {
+      continue;
+    }
     reviews.push({
       quote,
       score: num(node.score),
@@ -713,9 +830,13 @@ function parseUserReviews(raw, url, what, sentiment) {
   const bucket = reviewBucket(data, url, sentiment);
   const reviews = [];
   for (const node of bucket) {
-    if (!isObject(node)) continue;
+    if (!isObject(node)) {
+      continue;
+    }
     const quote = str(node.quote);
-    if (!quote) continue;
+    if (!quote) {
+      continue;
+    }
     reviews.push({ quote, score: num(node.score), date: str(node.date) });
   }
   if (bucket.length > 0 && reviews.length === 0) {
@@ -728,10 +849,14 @@ function parseUserReviews(raw, url, what, sentiment) {
   };
 }
 function unwrapLink(link) {
-  if (!link) return null;
+  if (!link) {
+    return null;
+  }
   try {
     const target = new URL(link).searchParams.get("r");
-    if (target && /^https?:\/\//i.test(target)) return target;
+    if (target && ABSOLUTE_URL.test(target)) {
+      return target;
+    }
   } catch {
   }
   return link;
@@ -739,14 +864,22 @@ function unwrapLink(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");
+  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;
+    if (!Array.isArray(value)) {
+      continue;
+    }
     for (const node of value) {
-      if (!isObject(node)) continue;
+      if (!isObject(node)) {
+        continue;
+      }
       const provider = str(node.providerName);
-      if (!provider) continue;
+      if (!provider) {
+        continue;
+      }
       offers.push({ provider, kind: group, url: unwrapLink(str(node.link)) });
     }
   }
@@ -754,8 +887,9 @@ function parseOffers(raw, url, what) {
 }
 
 // src/mc/client.ts
+var BROWSER_IDENTITY = /mozilla\/|applewebkit|chrome\/|safari\/|gecko/i;
 function withGuarantees(config) {
-  const userAgent = /mozilla\/|applewebkit|chrome\/|safari\/|gecko/i.test(config.userAgent) ? `${config.userAgent} ${DEFAULT_USER_AGENT}` : config.userAgent;
+  const userAgent = BROWSER_IDENTITY.test(config.userAgent) ? `${config.userAgent} ${DEFAULT_USER_AGENT}` : config.userAgent;
   return {
     ...config,
     userAgent,
@@ -797,7 +931,7 @@ var McClient = class {
    */
   async search(query, limit, offset) {
     const url = searchUrl(query, limit, offset);
-    return this.fetchParsed(
+    return await this.fetchParsed(
       url,
       this.catalogueCache,
       (body) => parseTitlePage(body, url, `the query "${query}"`)
@@ -805,7 +939,7 @@ var McClient = class {
   }
   async browse(options) {
     const url = browseUrl(options);
-    return this.fetchParsed(
+    return await this.fetchParsed(
       url,
       this.catalogueCache,
       (body) => parseTitlePage(body, url, `that ${options.kind} listing`)
@@ -814,7 +948,7 @@ var McClient = class {
   async getDetail(kind, slug) {
     const url = detailUrl(kind, slug);
     const clean = slug.trim();
-    return this.fetchParsed(
+    return await this.fetchParsed(
       url,
       this.catalogueCache,
       (body) => parseDetail(body, url, kind, clean)
@@ -822,7 +956,7 @@ var McClient = class {
   }
   async getScore(kind, slug, source) {
     const url = scoreUrl(kind, slug, source);
-    return this.fetchParsed(
+    return await this.fetchParsed(
       url,
       this.scoresCache,
       (body) => parseScore(body, url, `the ${source} score of ${kind} "${slug}"`)
@@ -830,7 +964,7 @@ var McClient = class {
   }
   async getCriticReviews(options) {
     const url = reviewsUrl({ ...options, source: "critic" });
-    return this.fetchParsed(
+    return await this.fetchParsed(
       url,
       this.scoresCache,
       (body) => parseCriticReviews(
@@ -844,7 +978,7 @@ var McClient = class {
   }
   async getUserReviews(options) {
     const url = reviewsUrl({ ...options, source: "user" });
-    return this.fetchParsed(
+    return await this.fetchParsed(
       url,
       this.scoresCache,
       (body) => parseUserReviews(
@@ -858,7 +992,7 @@ var McClient = class {
   }
   async getWatchOffers(imdbId, kind) {
     const url = watchUrl(imdbId, kind);
-    return this.fetchParsed(
+    return await this.fetchParsed(
       url,
       this.scoresCache,
       (body) => parseOffers(body, url, `streaming offers for ${imdbId}`)