anilink-api-wrapper 3.0.0 → 3.1.0

package/dist/AniLink.mjs

@@ -1,79 +1,128 @@
-import { randomInt, createHash, randomUUID } from 'node:crypto';
 import http from 'node:http';
 import https from 'node:https';
 import axios from 'axios';
+import { randomInt, createHash, randomUUID } from 'node:crypto';
 
-const TRANSPORT_OPTION_KEYS = [
-  "timeout",
-  "signal",
-  "exposeRawAxiosError",
-  "retry",
-  "paceWithRateLimit",
-  "rateLimitFloor",
-  "circuitBreaker",
-  "retryBudget",
-  "maxSockets",
-  "maxFreeSockets",
-  "onError",
-  "onRetry",
-  "onRequestStart",
-  "onResponse",
-  "onPace",
-  "onHookError",
-  "diagnostics",
-  "onCircuitOpen",
-  "onCircuitClose",
-  "ignorePaceDeadline",
-  "allowPartialData",
-  "responseCache"
-];
+const DEFAULT_REQUEST_TIMEOUT = 3e4;
+const MAX_FREE_SOCKETS = 5;
+const MAX_SOCKETS = 20;
+const resolveDiagnosticsMode = (diagnostics) => {
+  const resolved = diagnostics ?? "warn";
+  if (resolved !== "warn" && resolved !== "hook" && resolved !== "silent") {
+    throw new TypeError(
+      `Invalid diagnostics ${JSON.stringify(resolved)}: it must be one of "warn", "hook", or "silent".`
+    );
+  }
+  return resolved;
+};
 
-const isNonBlank = (value) => typeof value === "string" && value.trim() !== "";
-const resolveTransportOptions = (credentials, providerFields) => {
-  const allowedKeys = /* @__PURE__ */ new Set([...TRANSPORT_OPTION_KEYS, ...providerFields]);
-  const options = {};
-  for (const [key, value] of Object.entries(credentials)) {
-    if (providerFields.includes(key)) continue;
-    if (!allowedKeys.has(key)) {
+const DEFAULT_AGENT_OPTIONS = {
+  keepAlive: true,
+  maxSockets: MAX_SOCKETS,
+  maxFreeSockets: MAX_FREE_SOCKETS,
+  scheduling: "lifo"
+};
+let defaultHttpAgent = new http.Agent(DEFAULT_AGENT_OPTIONS);
+let defaultHttpsAgent = new https.Agent(DEFAULT_AGENT_OPTIONS);
+let axiosClient = axios.create({
+  timeout: DEFAULT_REQUEST_TIMEOUT,
+  httpAgent: defaultHttpAgent,
+  httpsAgent: defaultHttpsAgent
+});
+let defaultAgentsTornDown = false;
+const ensureDefaultAgents = () => {
+  if (!defaultAgentsTornDown) {
+    return;
+  }
+  defaultHttpAgent = new http.Agent(DEFAULT_AGENT_OPTIONS);
+  defaultHttpsAgent = new https.Agent(DEFAULT_AGENT_OPTIONS);
+  axiosClient = axios.create({
+    timeout: DEFAULT_REQUEST_TIMEOUT,
+    httpAgent: defaultHttpAgent,
+    httpsAgent: defaultHttpsAgent
+  });
+  defaultAgentsTornDown = false;
+};
+const MAX_CACHED_AGENT_PAIRS = 8;
+const MAX_PARKED_EVICTED_PAIRS = 16;
+const cachedAgentPairs = /* @__PURE__ */ new Map();
+const parkedEvictedPairs = [];
+const buildAgentCacheKey = (maxSockets, maxFreeSockets) => `${maxSockets}:${maxFreeSockets}`;
+const evictLruAgentPair = () => {
+  const oldestKey = cachedAgentPairs.keys().next().value;
+  if (oldestKey !== void 0) {
+    const evicted = cachedAgentPairs.get(oldestKey);
+    cachedAgentPairs.delete(oldestKey);
+    if (evicted !== void 0) {
+      if (parkedEvictedPairs.length >= MAX_PARKED_EVICTED_PAIRS) {
+        const oldestParked = parkedEvictedPairs.shift();
+        if (oldestParked !== void 0) {
+          oldestParked.httpAgent.destroy();
+          oldestParked.httpsAgent.destroy();
+        }
+      }
+      parkedEvictedPairs.push(evicted);
+    }
+  }
+};
+const destroyCachedAgents = () => {
+  for (const pair of cachedAgentPairs.values()) {
+    pair.httpAgent.destroy();
+    pair.httpsAgent.destroy();
+  }
+  cachedAgentPairs.clear();
+  for (const pair of parkedEvictedPairs) {
+    pair.httpAgent.destroy();
+    pair.httpsAgent.destroy();
+  }
+  parkedEvictedPairs.length = 0;
+  if (!defaultAgentsTornDown) {
+    defaultHttpAgent.destroy();
+    defaultHttpsAgent.destroy();
+    defaultAgentsTornDown = true;
+  }
+};
+const resolveAgents = (maxSockets, maxFreeSockets) => {
+  ensureDefaultAgents();
+  if (maxSockets === void 0 && maxFreeSockets === void 0) {
+    return { httpAgent: defaultHttpAgent, httpsAgent: defaultHttpsAgent };
+  }
+  const normalizeSockets = (value, fallback, min) => {
+    if (value === void 0) {
+      return fallback;
+    }
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
       throw new TypeError(
-        `Unknown credential key "${key}". Valid transport options are: ${TRANSPORT_OPTION_KEYS.join(
-          ", "
-        )}. Provider auth fields are: ${providerFields.join(", ")}.`
+        `Invalid socket bound ${value}: maxSockets/maxFreeSockets must be finite, non-negative integers.`
       );
     }
-    options[key] = value;
+    return Math.max(min, value);
+  };
+  const sockets = normalizeSockets(maxSockets, MAX_SOCKETS, 1);
+  const freeSockets = normalizeSockets(maxFreeSockets, MAX_FREE_SOCKETS, 0);
+  const key = buildAgentCacheKey(sockets, freeSockets);
+  const cached = cachedAgentPairs.get(key);
+  if (cached !== void 0) {
+    cachedAgentPairs.delete(key);
+    cachedAgentPairs.set(key, cached);
+    return { httpAgent: cached.httpAgent, httpsAgent: cached.httpsAgent };
   }
-  return Object.keys(options).length === 0 ? void 0 : options;
-};
-function resolveAniListCredentials(credentials) {
-  if (credentials === void 0) return {};
-  return {
-    auth: credentials.authToken,
-    options: resolveTransportOptions(credentials, [
-      "authToken",
-      "refreshToken",
-      "clientId",
-      "clientSecret",
-      "onTokenRefresh",
-      "onTokenRefreshError"
-    ])
+  if (cachedAgentPairs.size >= MAX_CACHED_AGENT_PAIRS) {
+    evictLruAgentPair();
+  }
+  const agentOptions = {
+    keepAlive: true,
+    maxSockets: sockets,
+    maxFreeSockets: freeSockets,
+    scheduling: "lifo"
   };
-}
-function resolveMalCredentials(credentials) {
-  if (credentials === void 0) return {};
-  const headers = credentials.clientId !== void 0 && credentials.accessToken === void 0 ? { "X-MAL-CLIENT-ID": credentials.clientId } : void 0;
-  return {
-    auth: credentials.accessToken === void 0 && headers === void 0 ? void 0 : { token: credentials.accessToken, headers },
-    options: resolveTransportOptions(credentials, [
-      "accessToken",
-      "refreshToken",
-      "clientId",
-      "clientSecret",
-      "onTokenRefresh",
-      "onTokenRefreshError"
-    ])
+  const pair = {
+    httpAgent: new http.Agent(agentOptions),
+    httpsAgent: new https.Agent(agentOptions)
   };
-}
+  cachedAgentPairs.set(key, pair);
+  return { httpAgent: pair.httpAgent, httpsAgent: pair.httpsAgent };
+};
 
 const AniLinkErrorCodes = {
   API: "API_ERROR",
@@ -245,111 +294,6 @@ class AniLinkNetworkError extends AniLinkError {
   }
 }
 
-const DEFAULT_REQUEST_TIMEOUT = 3e4;
-const MAX_FREE_SOCKETS = 5;
-const MAX_SOCKETS = 20;
-const resolveDiagnosticsMode = (diagnostics) => {
-  const resolved = diagnostics ?? "warn";
-  if (resolved !== "warn" && resolved !== "hook" && resolved !== "silent") {
-    throw new TypeError(
-      `Invalid diagnostics ${JSON.stringify(resolved)}: it must be one of "warn", "hook", or "silent".`
-    );
-  }
-  return resolved;
-};
-
-const defaultHttpAgent = new http.Agent({
-  keepAlive: true,
-  maxSockets: MAX_SOCKETS,
-  maxFreeSockets: MAX_FREE_SOCKETS,
-  scheduling: "lifo"
-});
-const defaultHttpsAgent = new https.Agent({
-  keepAlive: true,
-  maxSockets: MAX_SOCKETS,
-  maxFreeSockets: MAX_FREE_SOCKETS,
-  scheduling: "lifo"
-});
-const axiosClient = axios.create({
-  timeout: DEFAULT_REQUEST_TIMEOUT,
-  httpAgent: defaultHttpAgent,
-  httpsAgent: defaultHttpsAgent
-});
-const MAX_CACHED_AGENT_PAIRS = 8;
-const MAX_PARKED_EVICTED_PAIRS = 16;
-const cachedAgentPairs = /* @__PURE__ */ new Map();
-const parkedEvictedPairs = [];
-const buildAgentCacheKey = (maxSockets, maxFreeSockets) => `${maxSockets}:${maxFreeSockets}`;
-const evictLruAgentPair = () => {
-  const oldestKey = cachedAgentPairs.keys().next().value;
-  if (oldestKey !== void 0) {
-    const evicted = cachedAgentPairs.get(oldestKey);
-    cachedAgentPairs.delete(oldestKey);
-    if (evicted !== void 0) {
-      if (parkedEvictedPairs.length >= MAX_PARKED_EVICTED_PAIRS) {
-        const oldestParked = parkedEvictedPairs.shift();
-        if (oldestParked !== void 0) {
-          oldestParked.httpAgent.destroy();
-          oldestParked.httpsAgent.destroy();
-        }
-      }
-      parkedEvictedPairs.push(evicted);
-    }
-  }
-};
-const destroyCachedAgents = () => {
-  for (const pair of cachedAgentPairs.values()) {
-    pair.httpAgent.destroy();
-    pair.httpsAgent.destroy();
-  }
-  cachedAgentPairs.clear();
-  for (const pair of parkedEvictedPairs) {
-    pair.httpAgent.destroy();
-    pair.httpsAgent.destroy();
-  }
-  parkedEvictedPairs.length = 0;
-};
-const resolveAgents = (maxSockets, maxFreeSockets) => {
-  if (maxSockets === void 0 && maxFreeSockets === void 0) {
-    return { httpAgent: defaultHttpAgent, httpsAgent: defaultHttpsAgent };
-  }
-  const normalizeSockets = (value, fallback, min) => {
-    if (value === void 0) {
-      return fallback;
-    }
-    if (!Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
-      throw new TypeError(
-        `Invalid socket bound ${value}: maxSockets/maxFreeSockets must be finite, non-negative integers.`
-      );
-    }
-    return Math.max(min, value);
-  };
-  const sockets = normalizeSockets(maxSockets, MAX_SOCKETS, 1);
-  const freeSockets = normalizeSockets(maxFreeSockets, MAX_FREE_SOCKETS, 0);
-  const key = buildAgentCacheKey(sockets, freeSockets);
-  const cached = cachedAgentPairs.get(key);
-  if (cached !== void 0) {
-    cachedAgentPairs.delete(key);
-    cachedAgentPairs.set(key, cached);
-    return { httpAgent: cached.httpAgent, httpsAgent: cached.httpsAgent };
-  }
-  if (cachedAgentPairs.size >= MAX_CACHED_AGENT_PAIRS) {
-    evictLruAgentPair();
-  }
-  const agentOptions = {
-    keepAlive: true,
-    maxSockets: sockets,
-    maxFreeSockets: freeSockets,
-    scheduling: "lifo"
-  };
-  const pair = {
-    httpAgent: new http.Agent(agentOptions),
-    httpsAgent: new https.Agent(agentOptions)
-  };
-  cachedAgentPairs.set(key, pair);
-  return { httpAgent: pair.httpAgent, httpsAgent: pair.httpsAgent };
-};
-
 const MAX_RETRY_AFTER_MS = 6e4;
 const DEFAULT_RETRY_POLICY = {
   maxRetries: 3,
@@ -476,6 +420,19 @@ const computeNextRetryDelay = (input) => {
   }
   return getRetryDelay(normalized, rawError, attempt, policy);
 };
+const isBudgetGatedFailure = (input) => {
+  const { normalized, rawError, attempt, policy, budgetState, budget, wasProbe } = input;
+  if (wasProbe || policy === null) {
+    return false;
+  }
+  if (budgetState === void 0 || budget === void 0) {
+    return false;
+  }
+  if (budgetState.retriesUsed < budget.maxRetriesPerWindow) {
+    return false;
+  }
+  return getRetryDelay(normalized, rawError, attempt, policy) !== null;
+};
 const retryBudgetStates = /* @__PURE__ */ new WeakMap();
 const getRetryBudgetState = (owner, budget) => {
   if (owner === void 0 || budget === void 0) {
@@ -529,8 +486,184 @@ const resolveRequestOptions = (options = {}) => {
     onCircuitClose: options.onCircuitClose,
     ignorePaceDeadline: options.ignorePaceDeadline ?? false,
     allowPartialData: options.allowPartialData ?? false,
-    responseCache: options.responseCache
+    responseCache: options.responseCache,
+    bypassResponseCache: options.bypassResponseCache ?? false
+  };
+};
+const DEEP_MERGED_OPTION_KEYS = ["retry", "circuitBreaker", "retryBudget"];
+const assignDeepMergedOption = (merged, key, value) => {
+  merged[key] = value;
+};
+const mergeOptions = (base, overrides) => {
+  if (overrides === void 0) return base;
+  if (base === void 0) return overrides;
+  const merged = { ...base, ...overrides };
+  for (const key of DEEP_MERGED_OPTION_KEYS) {
+    const baseValue = base[key];
+    const overrideValue = overrides[key];
+    if (typeof baseValue === "object" && baseValue !== null && typeof overrideValue === "object" && overrideValue !== null) {
+      assignDeepMergedOption(merged, key, { ...baseValue, ...overrideValue });
+    }
+  }
+  return merged;
+};
+const TRANSPORT_OPTION_KEYS = [
+  "timeout",
+  "signal",
+  "exposeRawAxiosError",
+  "retry",
+  "paceWithRateLimit",
+  "rateLimitFloor",
+  "circuitBreaker",
+  "retryBudget",
+  "maxSockets",
+  "maxFreeSockets",
+  "onError",
+  "onRetry",
+  "onRequestStart",
+  "onResponse",
+  "onPace",
+  "onHookError",
+  "diagnostics",
+  "onCircuitOpen",
+  "onCircuitClose",
+  "ignorePaceDeadline",
+  "allowPartialData",
+  "responseCache",
+  "bypassResponseCache"
+];
+
+const isNonBlank = (value) => typeof value === "string" && value.trim() !== "";
+const resolveTransportOptions = (credentials, providerFields) => {
+  const allowedKeys = /* @__PURE__ */ new Set([...TRANSPORT_OPTION_KEYS, ...providerFields]);
+  const options = {};
+  for (const [key, value] of Object.entries(credentials)) {
+    if (providerFields.includes(key)) continue;
+    if (!allowedKeys.has(key)) {
+      throw new TypeError(
+        `Unknown credential key "${key}". Valid transport options are: ${TRANSPORT_OPTION_KEYS.join(
+          ", "
+        )}. Provider auth fields are: ${providerFields.join(", ")}.`
+      );
+    }
+    options[key] = value;
+  }
+  return Object.keys(options).length === 0 ? void 0 : options;
+};
+function resolveAniListCredentials(credentials) {
+  if (credentials === void 0) return {};
+  return {
+    auth: credentials.authToken,
+    options: resolveTransportOptions(credentials, [
+      "authToken",
+      "refreshToken",
+      "clientId",
+      "clientSecret",
+      "onTokenRefresh",
+      "onTokenRefreshError"
+    ])
   };
+}
+function resolveMalCredentials(credentials) {
+  if (credentials === void 0) return {};
+  const headers = credentials.clientId !== void 0 && credentials.accessToken === void 0 ? { "X-MAL-CLIENT-ID": credentials.clientId } : void 0;
+  return {
+    auth: credentials.accessToken === void 0 && headers === void 0 ? void 0 : { token: credentials.accessToken, headers },
+    options: resolveTransportOptions(credentials, [
+      "accessToken",
+      "refreshToken",
+      "clientId",
+      "clientSecret",
+      "onTokenRefresh",
+      "onTokenRefreshError"
+    ])
+  };
+}
+
+const buildDiagnostic = (kind, hookName, message, requestId) => ({
+  source: "anilink",
+  kind,
+  hookName,
+  ...requestId === void 0 ? {} : { requestId },
+  message
+});
+const reportDiagnostic = (options) => {
+  const { kind, hookName, message, requestId, onHookError, diagnostics, rawError, rethrown } = options;
+  if (onHookError !== void 0 && (rawError !== void 0 || diagnostics !== "silent")) {
+    const record = buildDiagnostic(kind, hookName, message, requestId);
+    try {
+      onHookError(
+        hookName,
+        new Error(message, {
+          cause: rawError !== void 0 ? rawError : record
+        })
+      );
+    } catch {
+    }
+    return true;
+  }
+  if (rethrown === true || diagnostics !== "warn") {
+    return false;
+  }
+  console.warn(JSON.stringify(buildDiagnostic(kind, hookName, message, requestId)));
+  return true;
+};
+const safeInvoke = (hook, name, onHookError, diagnostics, ...args) => {
+  if (hook === void 0) {
+    return;
+  }
+  try {
+    hook(...args);
+  } catch (hookError) {
+    const firstArg = args[0];
+    const requestId = firstArg !== null && typeof firstArg === "object" && "requestId" in firstArg && typeof firstArg.requestId === "string" ? firstArg.requestId : void 0;
+    const detail = hookError instanceof Error ? hookError.message : String(hookError);
+    reportDiagnostic({
+      kind: "hook-failure",
+      hookName: name,
+      message: `The ${name} hook threw and was ignored: ${detail}`,
+      requestId,
+      onHookError,
+      diagnostics,
+      rawError: hookError
+    });
+  }
+};
+const buildErrorContext = (requestId, url, method, attempt, normalized, facts = {}) => ({
+  requestId,
+  url,
+  method,
+  attempt,
+  code: normalized.code,
+  ...normalized instanceof AniLinkApiError ? { status: normalized.status } : {},
+  ...normalized instanceof AniLinkApiError && normalized.rateLimit !== void 0 ? { rateLimit: normalized.rateLimit } : {},
+  ...facts.nextDelayMs === void 0 ? {} : { nextDelayMs: facts.nextDelayMs },
+  ...facts.retryWaitMs === void 0 || facts.retryWaitMs <= 0 ? {} : { retryWaitMs: facts.retryWaitMs },
+  ...facts.budgetExhausted ? { budgetExhausted: true } : {},
+  ...facts.host === void 0 ? {} : { host: facts.host },
+  ...facts.retryAfterMs === void 0 ? {} : { retryAfterMs: facts.retryAfterMs }
+});
+const reportFailure = (requestId, url, method, attempt, normalized, resolved, facts = {}) => {
+  const context = buildErrorContext(requestId, url, method, attempt, normalized, facts);
+  if (facts.nextDelayMs !== void 0) {
+    safeInvoke(
+      resolved.onRetry ?? resolved.onError,
+      resolved.onRetry === void 0 ? "onError" : "onRetry",
+      resolved.onHookError,
+      resolved.diagnostics,
+      normalized,
+      context
+    );
+    return;
+  }
+  safeInvoke(
+    resolved.onError,
+    "onError",
+    resolved.onHookError,
+    resolved.diagnostics,
+    normalized,
+    context
+  );
 };
 
 const GRAPHQL_QUERY_PATTERN = /^\s*(?:\{|query\b[\s\S]*\{)/;
@@ -592,6 +725,176 @@ const resolveCacheAuthKey = (cache, method, data, isRestCall, auth) => {
   }
   return buildCacheAuthKey(auth.hasBearerToken, auth.hasCredentialHeaders, auth.auth?.token);
 };
+const extractRootField = (document) => {
+  const keyword = /^\s*(query|mutation|subscription|fragment)\b/.exec(document);
+  let rest = keyword === null ? document : document.slice(keyword[0].length);
+  const name = /^\s*[A-Za-z_][A-Za-z0-9_]*/.exec(rest);
+  if (name !== null && name[0].trim() !== "") {
+    rest = rest.slice(name[0].length);
+  }
+  if (/^\s*\(/.test(rest)) {
+    let depth = 0;
+    let end = -1;
+    for (let i = 0; i < rest.length; i += 1) {
+      const ch = rest[i];
+      if (ch === "(") {
+        depth += 1;
+      } else if (ch === ")") {
+        depth -= 1;
+        if (depth === 0) {
+          end = i + 1;
+          break;
+        }
+      }
+    }
+    if (end === -1) {
+      return void 0;
+    }
+    rest = rest.slice(end);
+  }
+  const openBrace = rest.indexOf("{");
+  if (openBrace === -1) {
+    return void 0;
+  }
+  const inside = rest.slice(openBrace + 1);
+  if (/^\s*\.\.\./.test(inside)) {
+    return void 0;
+  }
+  let cursor = inside;
+  let selection = /^\s*[A-Za-z_][A-Za-z0-9_]*/.exec(cursor);
+  if (selection === null) {
+    return void 0;
+  }
+  let fieldName = selection[0].trim();
+  cursor = cursor.slice(selection[0].length);
+  const colon = /^\s*:/.exec(cursor);
+  if (colon !== null) {
+    selection = /^\s*[A-Za-z_][A-Za-z0-9_]*/.exec(cursor.slice(colon[0].length));
+    if (selection === null) {
+      return void 0;
+    }
+    fieldName = selection[0].trim();
+    cursor = cursor.slice(colon[0].length + selection[0].length);
+  }
+  if (/^\s*\(/.test(cursor)) {
+    const openParen = cursor.indexOf("(");
+    let depth = 0;
+    let end = -1;
+    for (let i = openParen; i < cursor.length; i += 1) {
+      const ch = cursor[i];
+      if (ch === "(") {
+        depth += 1;
+      } else if (ch === ")") {
+        depth -= 1;
+        if (depth === 0) {
+          end = i + 1;
+          break;
+        }
+      }
+    }
+    if (end === -1) {
+      return void 0;
+    }
+    cursor = cursor.slice(end);
+  }
+  if (/^\s*\{/.test(cursor)) {
+    const openBraceIdx = cursor.indexOf("{");
+    let depth = 0;
+    let end = -1;
+    for (let i = openBraceIdx; i < cursor.length; i += 1) {
+      const ch = cursor[i];
+      if (ch === "{") {
+        depth += 1;
+      } else if (ch === "}") {
+        depth -= 1;
+        if (depth === 0) {
+          end = i + 1;
+          break;
+        }
+      }
+    }
+    if (end === -1) {
+      return void 0;
+    }
+    cursor = cursor.slice(end);
+  }
+  const trailing = cursor.trimStart();
+  if (trailing === "" || trailing[0] !== "}") {
+    return void 0;
+  }
+  return fieldName;
+};
+const extractQueryRootField = (data) => {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return void 0;
+  }
+  const { query } = data;
+  if (typeof query !== "string") {
+    return void 0;
+  }
+  return extractRootField(stripLeadingComments$1(query));
+};
+const MUTATION_ROOT_FIELD_INVALIDATION = /* @__PURE__ */ new Map([
+  // Media list entry writes change what MediaList, MediaListCollection,
+  // and Page (media lists) queries report, plus the Media documents
+  // that embed the requesting user's list entry for that media
+  // (`Media.mediaListEntry`), the User/Viewer documents that embed a
+  // `mediaListCollection`, and the Activity queries that embed the
+  // ListActivity AniList generates from the write. The shipped schemas
+  // do not select those embeds, but `custom()` documents can, and the
+  // map must not under-invalidate them.
+  [
+    "SaveMediaListEntry",
+    ["MediaList", "MediaListCollection", "Page", "Media", "User", "Viewer", "Activity"]
+  ],
+  [
+    "UpdateMediaListEntries",
+    ["MediaList", "MediaListCollection", "Page", "Media", "User", "Viewer", "Activity"]
+  ],
+  [
+    "DeleteMediaListEntry",
+    ["MediaList", "MediaListCollection", "Page", "Media", "User", "Viewer", "Activity"]
+  ],
+  // Favourite toggles change the user's Favourites, the User/Viewer
+  // documents that embed them, the isFavourite/favourites embeds on the
+  // object types the shipped Media/Character/Staff/Studio schemas
+  // select, and the Page queries that reach those embeds
+  // (Page→users→favourites, Page→media→isFavourite).
+  [
+    "ToggleFavourite",
+    ["Favourites", "User", "Viewer", "Media", "Character", "Staff", "Studio", "Page"]
+  ],
+  [
+    "UpdateFavouriteOrder",
+    ["Favourites", "User", "Viewer", "Media", "Character", "Staff", "Studio", "Page"]
+  ],
+  // Review writes change Review queries, Page (reviews), the Media
+  // documents that embed the reviews connection (`Media.reviews`), and
+  // the User/Viewer documents that embed one (`User.reviews`).
+  ["SaveReview", ["Review", "Page", "Media", "User", "Viewer"]],
+  ["DeleteReview", ["Review", "Page", "Media", "User", "Viewer"]],
+  ["RateReview", ["Review", "Page", "Media", "User", "Viewer"]],
+  // Profile writes change User and Viewer documents, the Follower and
+  // Following collections (the user's name/avatar/about change what they
+  // report), and the Page queries that embed user profiles. The
+  // animeListOptions/mangaListOptions variables also change list options
+  // (custom lists, scoring display), so the MediaList/MediaListCollection
+  // queries and the Media documents embedding the user's list entry
+  // (`Media.mediaListEntry`) are affected too.
+  [
+    "UpdateUser",
+    [
+      "User",
+      "Viewer",
+      "Follower",
+      "Following",
+      "Page",
+      "MediaList",
+      "MediaListCollection",
+      "Media"
+    ]
+  ]
+]);
 const MUTATION_ACTION_SEGMENTS = /* @__PURE__ */ new Set(["my_list_status"]);
 const deriveMutationCachePrefix = (url) => {
   const fragmentIndex = url.indexOf("#");
@@ -618,7 +921,13 @@ const invalidateAfterMutation = (cache, method, url, data, isRestCall) => {
     return;
   }
   if (!isRestCall && isGraphQLDocumentRequest(method, data) && !isCacheableRequest(method, data)) {
-    cache.deleteAllForUrl(url);
+    const rootField = extractQueryRootField(data);
+    const affected = rootField === void 0 ? void 0 : MUTATION_ROOT_FIELD_INVALIDATION.get(rootField);
+    if (affected !== void 0) {
+      cache.deleteRootFieldsForUrl(url, affected);
+    } else {
+      cache.deleteAllForUrl(url);
+    }
     return;
   }
   const prefix = deriveMutationCachePrefix(url);
@@ -626,6 +935,29 @@ const invalidateAfterMutation = (cache, method, url, data, isRestCall) => {
     cache.deleteMatching(prefix);
   }
 };
+const tryCacheRead = (resolved, method, url, data, cacheAuthKey) => {
+  const cached = resolved.responseCache.get(method, url, data, cacheAuthKey);
+  if (cached === void 0) {
+    return void 0;
+  }
+  if (resolved.onRequestStart !== void 0 || resolved.onResponse !== void 0) {
+    const requestId = randomUUID();
+    const hookContext = { requestId, url, method, attempt: 1 };
+    safeInvoke(
+      resolved.onRequestStart,
+      "onRequestStart",
+      resolved.onHookError,
+      resolved.diagnostics,
+      hookContext
+    );
+    safeInvoke(resolved.onResponse, "onResponse", resolved.onHookError, resolved.diagnostics, {
+      ...hookContext,
+      durationMs: 0,
+      cacheHit: true
+    });
+  }
+  return cached;
+};
 const MAX_INVALIDATION_EVENTS = 64;
 const isPlainObject$1 = (value) => {
   const proto = Object.getPrototypeOf(value);
@@ -699,12 +1031,12 @@ class ResponseCache {
   }
   /**
    * Canonicalizes a URL for keying: the query string's parameters are
-   * sorted so `?a=1&b=2` and `?b=2&a=1` — the same resource — share one
+   * sorted so `?a=1&b=2` and `?b=2&a=1`, the same resource, share one
    * cache entry instead of missing each other.
    *
    * The query string is anchored at the first `?` that appears before any
    * `#`, so a `?` inside a fragment (`path#frag?x`) is never mistaken for
-   * the query delimiter — harmless for keying, but the method must stay
+   * the query delimiter. That is harmless for keying, but the method must stay
    * correct if it is ever reused for matching or allowlists.
    *
    * @param url - The request URL, possibly carrying a query string.
@@ -731,7 +1063,7 @@ class ResponseCache {
    *
    * The serialized body is SHA-256 hashed (truncated to 16 hex chars)
    * before it enters the key, so a credential-bearing GET body is never
-   * duplicated into the key string in plaintext — the key map retains
+   * duplicated into the key string in plaintext. The key map retains
    * entries for up to the TTL, outliving the error paths the rest of the
    * library scrubs. The hash is deterministic, so equal bodies still share
    * one entry and different bodies still get different entries. The URL's
@@ -815,15 +1147,15 @@ class ResponseCache {
   }
   /**
    * Stores a response in the cache, evicting the LRU entry when the cap is
-   * is reached. Only cacheable reads are stored — `GET` requests and
+   * is reached. Only cacheable reads are stored, `GET` requests and
    * GraphQL query documents dispatched as `POST`; mutations and other
    * methods are no-ops. The value is deep-copied on write; the cache never
    * aliases the caller's object.
    *
    * Note for direct callers: a `POST` body shaped like `{ query: "..." }`
    * is treated as a GraphQL document and cached when the document declares
-   * a read. Do not use `set` for REST `POST` writes whose body merely
-   * carries a `query` field — the transport excludes those via its protocol
+   * a read. Do not use `set` for REST `POST` writes whose body only
+   * carries a `query` field: the transport excludes those via its protocol
    * flag, but `set` itself cannot distinguish them.
    *
    * @param method - The HTTP method.
@@ -834,14 +1166,35 @@ class ResponseCache {
    * @param response - The response body to cache.
    */
   set(method, url, data, authKey, response) {
-    if (!isCacheableRequest(method, data)) return;
-    if (this.ttlMs === 0) return;
+    this.setEntry(method, url, data, authKey, response, void 0);
+  }
+  /**
+   * The single write path behind {@link set} and {@link setIfFresh}: all
+   * the write-side guards (cacheability, `ttlMs: 0`, the clone, the
+   * opportunistic purge, LRU eviction) with the entry's root field
+   * recorded for GraphQL query documents so scoped invalidation can
+   * attribute the entry to the root field its document selects.
+   *
+   * @param method - The HTTP method.
+   * @param url - The request URL.
+   * @param data - The request body, when present.
+   * @param authKey - An authentication-safe credential identity.
+   * @param response - The response body to cache.
+   * @param rootField - The GraphQL document's single selected root field,
+   * when the caller knows it (the transport extracts it for query reads).
+   * @returns Whether the response was stored: `false` when a
+   * write-side guard skipped it (not cacheable, `ttlMs: 0`, or an
+   * uncloneable payload).
+   */
+  setEntry(method, url, data, authKey, response, rootField) {
+    if (!isCacheableRequest(method, data)) return false;
+    if (this.ttlMs === 0) return false;
     const key = ResponseCache.buildKey(method, url, data, authKey);
     let snapshot;
     try {
       snapshot = structuredClone(response);
     } catch {
-      return;
+      return false;
     }
     this.purgeExpired();
     if (this.entries.has(key)) {
@@ -851,8 +1204,10 @@ class ResponseCache {
     }
     this.entries.set(key, {
       data: snapshot,
-      expiresAt: Date.now() + this.ttlMs
+      expiresAt: Date.now() + this.ttlMs,
+      ...rootField !== void 0 ? { rootField } : {}
     });
+    return true;
   }
   /**
    * Returns the current invalidation generation, for callers that need to
@@ -868,7 +1223,7 @@ class ResponseCache {
   }
   /**
    * Stores a response only when no invalidation affecting the request has
-   * landed since the caller captured the generation — the write-back half
+   * landed since the caller captured the generation, the write-back half
    * of the in-flight-read guard.
    *
    * The transport captures the generation right after a cache miss (before
@@ -888,16 +1243,26 @@ class ResponseCache {
    * @param generationAtRead - The generation the caller captured before
    * the read went to the network.
    * @param response - The response body to cache.
+   * @param rootField - The GraphQL document's single selected root field,
+   * when the caller knows it, so scoped invalidations that landed while
+   * the read was in flight are matched against the read's own root field;
+   * an unattributed document (`undefined`) is treated as affected by
+   * every scoped invalidation, fail-closed.
+   * @returns Whether the response was stored: `false` when an
+   * invalidation affecting the read landed while it was in flight (the
+   * stale response is dropped) or a write-side guard skipped it. That is
+   * the signal behind the `cacheWrite` flag on the transport's `onResponse`
+   * emission, so consumers can measure cache fill rate.
    */
-  setIfFresh(method, url, data, authKey, generationAtRead, response) {
-    if (this.wasInvalidatedSince(generationAtRead, method, url, data, authKey)) {
-      return;
+  setIfFresh(method, url, data, authKey, generationAtRead, response, rootField) {
+    if (this.wasInvalidatedSince(generationAtRead, method, url, data, authKey, rootField)) {
+      return false;
     }
-    this.set(method, url, data, authKey, response);
+    return this.setEntry(method, url, data, authKey, response, rootField);
   }
   /**
    * Whether an invalidation affecting the given request's key landed
-   * after the caller captured the generation — the decision half of the
+   * after the caller captured the generation, the decision half of the
    * in-flight-read guard.
    *
    * The check is scoped, not global: an invalidation of one resource does
@@ -914,9 +1279,13 @@ class ResponseCache {
    * @param url - The URL of the read.
    * @param data - The request body of the read, when present.
    * @param authKey - The auth-scoping cache key fragment of the read.
+   * @param rootField - The read's GraphQL root field, when known, so a
+   * scoped invalidation is matched against the read's own root field; an
+   * unattributed document is treated as affected by every scoped
+   * invalidation, fail-closed.
    * @returns `true` when an affecting invalidation landed mid-flight.
    */
-  wasInvalidatedSince(generationAtRead, method, url, data, authKey) {
+  wasInvalidatedSince(generationAtRead, method, url, data, authKey, rootField) {
     if (generationAtRead === this.generation) {
       return false;
     }
@@ -929,7 +1298,7 @@ class ResponseCache {
       if (event.at <= generationAtRead) {
         break;
       }
-      if (event.affects(key)) {
+      if (event.affects(key, rootField)) {
         return true;
       }
     }
@@ -940,8 +1309,8 @@ class ResponseCache {
    * so an in-flight read can later tell whether the invalidation affected
    * its key (see {@link setIfFresh}).
    *
-   * @param affects - Whether a cache key falls inside the invalidation's
-   * scope.
+   * @param affects - Whether a cache key (with its entry's recorded root
+   * field, when one exists) falls inside the invalidation's scope.
    */
   recordInvalidation(affects) {
     this.generation += 1;
@@ -955,8 +1324,8 @@ class ResponseCache {
    * Removes the cached entry for the given request, if present. Use this
    * for targeted invalidation after a mutation that changes the resource
    * (for example a `POST` that updates the entity a cached `GET` returned).
-   * Only cacheable reads are tracked — `GET` requests and GraphQL query
-   * documents dispatched as `POST` — so other methods are a no-op and
+   * Only cacheable reads are tracked, `GET` requests and GraphQL query
+   * documents dispatched as `POST`, so other methods are a no-op and
    * return `false`.
    *
    * @param method - The HTTP method.
@@ -981,14 +1350,14 @@ class ResponseCache {
    * string and fragment stripped, so a cached read of
    * `https://host/anime/21?fields=...` is invalidated by the prefix
    * `https://host/anime/21`. The match is boundary-aware: the prefix
-   * `https://host/anime/21` does **not** match `https://host/anime/212` —
-   * the cached URL must be either exactly the prefix, continue with `/`
+   * `https://host/anime/21` does **not** match `https://host/anime/212`.
+   * The cached URL must be either exactly the prefix, continue with `/`
    * (a child path), `?` (a query string), or `#` (a fragment). Matching
    * spans every auth namespace, because a mutation performed by one
    * identity changes the underlying resource for every identity that can
    * read it.
    *
-   * This is the invalidation primitive behind mutation-triggered cache
+   * This is the invalidation path used by mutation-triggered cache
    * invalidation for REST writes: after a successful write, the transport
    * derives the mutated resource's base URL and drops every cached read
    * of that resource. It is also usable directly for manual bulk
@@ -1018,18 +1387,18 @@ class ResponseCache {
     return removed;
   }
   /**
-   * Removes every cached read keyed at the given URL — `GET` entries and
+   * Removes every cached read keyed at the given URL, `GET` entries and
    * GraphQL query `POST` entries alike, across query strings, documents,
-   * variables, and auth namespaces — and returns how many entries were
+   * variables, and auth namespaces, and returns how many entries were
    * removed.
    *
-   * This is the invalidation primitive for GraphQL writes: every GraphQL
+   * This is the invalidation path for GraphQL writes: every GraphQL
    * operation of one provider is keyed at the same endpoint URL, and a
    * `mutation` document can change what many different query documents
    * return (a `SaveMediaListEntry` changes what both a `MediaList` and a
    * `MediaListCollection` query report), so no finer-grained prefix than
    * the endpoint can be derived. Dropping the endpoint's cached queries is
-   * deliberately conservative: the next reads refetch fresh data instead
+   * conservative: the next reads refetch fresh data instead
    * of serving pre-mutation entries for the rest of the TTL.
    *
    * @param url - The request URL whose cached reads should be dropped;
@@ -1060,6 +1429,50 @@ class ResponseCache {
     }
     return removed;
   }
+  /**
+   * Removes every cached GraphQL query `POST` entry at the given URL whose
+   * document selects one of the given root fields, and returns how many
+   * entries were removed.
+   *
+   * This is the scoped invalidation path for mapped GraphQL mutations
+   * (see {@link invalidateAfterMutation}): a mutation whose root field is
+   * known to affect only certain query root fields drops exactly those
+   * cached queries, leaving unrelated root fields' entries warm, instead
+   * of the whole-endpoint sweep {@link deleteAllForUrl} performs. The
+   * match is against the document's single selected root field, recorded
+   * on the entry at write time (see {@link CacheEntry.rootField}), so a
+   * query document is attributed to the root field it selects,
+   * not to every field it mentions. Entries whose document could not be
+   * attributed to a single root field (fragment-spread roots,
+   * multi-field selections) are dropped too, fail-closed like the
+   * unmapped-mutation fallback, because such a document may select data
+   * the affected-field match cannot see.
+   *
+   * @param url - The request URL whose cached reads should be considered;
+   * its query string and fragment are ignored.
+   * @param rootFields - The query root fields whose cached entries should
+   * be dropped.
+   * @returns The number of cached entries removed.
+   */
+  deleteRootFieldsForUrl(url, rootFields) {
+    const fragmentIndex = url.indexOf("#");
+    const withoutFragment = fragmentIndex === -1 ? url : url.slice(0, fragmentIndex);
+    const queryIndex = withoutFragment.indexOf("?");
+    const base = queryIndex === -1 ? withoutFragment : withoutFragment.slice(0, queryIndex);
+    const prefix = base.endsWith("/") && base.length > 1 ? base.slice(0, -1) : base;
+    const fieldSet = new Set(rootFields);
+    this.recordInvalidation(
+      (key, rootField) => ResponseCache.keyAtPrefix(key, `POST:${prefix}`, ":?#") && (rootField === void 0 || fieldSet.has(rootField))
+    );
+    let removed = 0;
+    for (const [key, entry] of this.entries) {
+      if (ResponseCache.keyAtPrefix(key, `POST:${prefix}`, ":?#") && (entry.rootField === void 0 || fieldSet.has(entry.rootField))) {
+        this.entries.delete(key);
+        removed += 1;
+      }
+    }
+    return removed;
+  }
   /**
    * Evicts the least-recently-used entry.
    */
@@ -1105,13 +1518,14 @@ class ResponseCache {
    * counters, so cache tuning (`ttlMs`/`maxEntries`) can be data-driven:
    * entry counts and eviction/expiration counters distinguish a too-small
    * cache (rising `evictions`) from a too-short TTL (rising
-   * `expirations`), and hit-rate dashboards can read `hits`/`misses`
-   * directly instead of inferring misses by subtracting hits from total
-   * response counts.
+   * `expirations`), and hit-rate dashboards compute
+   * `hits / (hits + misses + expirations)`: an expired-on-read entry
+   * counts as an expiration, not a miss, so the three counters partition
+   * every `get()` call.
    *
-   * The counters are cumulative for the cache instance's lifetime —
+   * The counters are cumulative for the cache instance's lifetime:
    * `delete()`, `deleteMatching()`, `deleteAllForUrl()`, and `clear()`
-   * drop entries but never reset or increment the counters — and
+   * drop entries but never reset or increment the counters, and
    * `entries` reflects the current live entry count. The returned object
    * is frozen, so a caller cannot mutate the cache's internal state
    * through it.
@@ -1313,88 +1727,6 @@ const unwrapGraphQLResponse = (response, headers, options) => {
   return unwrapped === void 0 ? response : unwrapped;
 };
 
-const buildDiagnostic = (kind, hookName, message, requestId) => ({
-  source: "anilink",
-  kind,
-  hookName,
-  ...requestId === void 0 ? {} : { requestId },
-  message
-});
-const reportDiagnostic = (options) => {
-  const { kind, hookName, message, requestId, onHookError, diagnostics, rawError, rethrown } = options;
-  if (onHookError !== void 0 && (rawError !== void 0 || diagnostics !== "silent")) {
-    const record = buildDiagnostic(kind, hookName, message, requestId);
-    try {
-      onHookError(
-        hookName,
-        new Error(message, {
-          cause: rawError !== void 0 ? rawError : record
-        })
-      );
-    } catch {
-    }
-    return true;
-  }
-  if (rethrown === true || diagnostics !== "warn") {
-    return false;
-  }
-  console.warn(JSON.stringify(buildDiagnostic(kind, hookName, message, requestId)));
-  return true;
-};
-const safeInvoke = (hook, name, onHookError, diagnostics, ...args) => {
-  if (hook === void 0) {
-    return;
-  }
-  try {
-    hook(...args);
-  } catch (hookError) {
-    const firstArg = args[0];
-    const requestId = firstArg !== null && typeof firstArg === "object" && "requestId" in firstArg && typeof firstArg.requestId === "string" ? firstArg.requestId : void 0;
-    const detail = hookError instanceof Error ? hookError.message : String(hookError);
-    reportDiagnostic({
-      kind: "hook-failure",
-      hookName: name,
-      message: `The ${name} hook threw and was ignored: ${detail}`,
-      requestId,
-      onHookError,
-      diagnostics,
-      rawError: hookError
-    });
-  }
-};
-const buildErrorContext = (requestId, url, method, attempt, normalized, nextDelayMs) => ({
-  requestId,
-  url,
-  method,
-  attempt,
-  code: normalized.code,
-  ...normalized instanceof AniLinkApiError ? { status: normalized.status } : {},
-  ...normalized instanceof AniLinkApiError && normalized.rateLimit !== void 0 ? { rateLimit: normalized.rateLimit } : {},
-  ...nextDelayMs === void 0 ? {} : { nextDelayMs }
-});
-const reportFailure = (requestId, url, method, attempt, normalized, resolved, nextDelayMs) => {
-  const context = buildErrorContext(requestId, url, method, attempt, normalized, nextDelayMs);
-  if (nextDelayMs !== void 0) {
-    safeInvoke(
-      resolved.onRetry ?? resolved.onError,
-      resolved.onRetry === void 0 ? "onError" : "onRetry",
-      resolved.onHookError,
-      resolved.diagnostics,
-      normalized,
-      context
-    );
-    return;
-  }
-  safeInvoke(
-    resolved.onError,
-    "onError",
-    resolved.onHookError,
-    resolved.diagnostics,
-    normalized,
-    context
-  );
-};
-
 const circuitStates = /* @__PURE__ */ new WeakMap();
 const MAX_PROBE_BACKOFF_EXPONENT = 3;
 const scaledCooldownMs = (breaker, failedProbes) => {
@@ -1410,6 +1742,7 @@ const isAvailabilityFailure = (error) => {
   }
   return false;
 };
+const isStreakNeutralFailure = (error) => error instanceof AniLinkGraphQLError && error.status === 200;
 const MAX_CIRCUIT_SCOPES_PER_OWNER = 64;
 const circuitScopeOf = (url, requestId) => {
   try {
@@ -1447,6 +1780,16 @@ const getCircuitState = (owner, scope) => {
   scopes.set(scope, state);
   return state;
 };
+const circuitCooldownRemainingMs = (circuit, breaker) => {
+  if (circuit === void 0 || breaker === void 0) {
+    return void 0;
+  }
+  if (circuit.probeInFlight || circuit.openedAt === null) {
+    return void 0;
+  }
+  const remaining = circuit.openedAt + scaledCooldownMs(breaker, circuit.failedProbes) - Date.now();
+  return remaining > 0 ? remaining : void 0;
+};
 const peekCircuitStates = (owner) => circuitStates.get(owner);
 const checkCircuitOpen = (circuit, breaker) => {
   if (circuit === void 0 || breaker === void 0) {
@@ -1498,6 +1841,9 @@ const recordCircuitFailure = (circuit, breaker, normalized, resolved, hookContex
     return;
   }
   if (!isAvailabilityFailure(normalized)) {
+    if (isStreakNeutralFailure(normalized) && !circuit.probeInFlight) {
+      return;
+    }
     recordCircuitSuccess(circuit, resolved, hookContext, host);
     return;
   }
@@ -1550,6 +1896,8 @@ const sleep = (ms, signal, requestId) => new Promise((resolve, reject) => {
 
 const paceDeadlines = /* @__PURE__ */ new WeakMap();
 const MAX_PACE_WAIT_MS = 5 * 60 * 1e3;
+const MAX_PACE_SCOPES_PER_OWNER = 64;
+const MAX_PACE_JITTER_MS = 500;
 const sleepForPacing = async (delayMs, resolved, hookContext) => {
   try {
     await sleep(delayMs, resolved.signal, hookContext.requestId);
@@ -1573,79 +1921,121 @@ const recordPaceDeadline = (owner, host, deadlineMs) => {
     scopes = /* @__PURE__ */ new Map();
     paceDeadlines.set(owner, scopes);
   }
-  if (deadlineMs <= Date.now()) {
-    scopes.delete(host);
+  const now = Date.now();
+  const existing = scopes.get(host);
+  if (deadlineMs <= now) {
+    if (existing === void 0 || existing <= now) {
+      scopes.delete(host);
+    }
     return;
   }
-  const existing = scopes.get(host);
-  if (existing !== void 0 && deadlineMs <= existing) {
+  if (existing !== void 0) {
+    scopes.delete(host);
+    scopes.set(host, Math.max(existing, deadlineMs));
     return;
   }
+  if (scopes.size >= MAX_PACE_SCOPES_PER_OWNER) {
+    const oldestHost = scopes.keys().next().value;
+    if (oldestHost !== void 0) {
+      scopes.delete(oldestHost);
+    }
+  }
   scopes.set(host, deadlineMs);
 };
 const awaitPaceDeadline = async (owner, host, resolved, hookContext) => {
   if (owner === void 0 || !resolved.paceWithRateLimit || resolved.ignorePaceDeadline) {
-    return;
+    return 0;
+  }
+  const scopes = paceDeadlines.get(owner);
+  if (scopes === void 0) {
+    return 0;
   }
-  const deadlineMs = paceDeadlines.get(owner)?.get(host);
+  const deadlineMs = scopes.get(host);
   if (deadlineMs === void 0) {
-    return;
+    return 0;
   }
   const delayMs = deadlineMs - Date.now();
   if (delayMs <= 0) {
-    paceDeadlines.get(owner)?.delete(host);
-    return;
+    scopes.delete(host);
+    return 0;
+  }
+  scopes.delete(host);
+  scopes.set(host, deadlineMs);
+  const jitterMs = randomInt(Math.min(MAX_PACE_JITTER_MS, Math.floor(delayMs / 10)) + 1);
+  const waitStartedAt = Date.now();
+  try {
+    await sleepForPacing(delayMs + jitterMs, resolved, hookContext);
+  } catch (error) {
+    if (error instanceof AniLinkNetworkError && error.code === AniLinkErrorCodes.ABORTED && error.abortedDuringPacing === true) {
+      const elapsedMs = Math.min(Date.now() - waitStartedAt, delayMs);
+      safeInvoke(resolved.onPace, "onPace", resolved.onHookError, resolved.diagnostics, {
+        ...hookContext,
+        delayMs: elapsedMs,
+        aborted: true
+      });
+      throw error;
+    }
+    throw error;
   }
-  await sleepForPacing(delayMs, resolved, hookContext);
   safeInvoke(resolved.onPace, "onPace", resolved.onHookError, resolved.diagnostics, {
     ...hookContext,
     delayMs
   });
+  return delayMs;
 };
 const paceAfterSuccess = (response, resolved, rateLimit, owner, host) => {
   if (!resolved.paceWithRateLimit) {
     return;
   }
-  const info = rateLimit ?? getRateLimitInfo(response.headers);
-  if (info !== void 0 && info.remaining < resolved.rateLimitFloor) {
-    const rawDeadlineMs = info.reset * 1e3;
-    const deadlineMs = Math.min(rawDeadlineMs, Date.now() + MAX_PACE_WAIT_MS);
-    if (owner !== void 0 && host !== void 0) {
-      recordPaceDeadline(owner, host, deadlineMs);
-    }
+  const info = rateLimit ?? getRateLimitInfo(response.headers);
+  if (info !== void 0 && info.remaining < resolved.rateLimitFloor) {
+    const rawDeadlineMs = info.reset * 1e3;
+    const deadlineMs = Math.min(rawDeadlineMs, Date.now() + MAX_PACE_WAIT_MS);
+    if (owner !== void 0 && host !== void 0) {
+      recordPaceDeadline(owner, host, deadlineMs);
+    }
+  }
+};
+const paceAfterTerminalRateLimit = (normalized, resolved, owner, host) => {
+  if (!resolved.paceWithRateLimit) {
+    return;
+  }
+  if (!(normalized instanceof AniLinkApiError) || normalized.status !== 429) {
+    return;
+  }
+  const reset = normalized.rateLimit?.reset;
+  if (reset === void 0 || !Number.isFinite(reset)) {
+    return;
+  }
+  const deadlineMs = Math.min(reset * 1e3, Date.now() + MAX_PACE_WAIT_MS);
+  if (owner !== void 0) {
+    recordPaceDeadline(owner, host, deadlineMs);
   }
 };
 const peekPaceDeadlines = (owner) => paceDeadlines.get(owner);
 
-const resolveEnvelopeOutcome = (response, resolved, rawPassthrough, requestId, url, method, attempt) => {
+const resolveEnvelopeOutcome = (response, resolved, rawPassthrough) => {
   let resolvedPartial = false;
-  let partialAvailabilityFailure;
+  let partialError;
+  let partialBreakerError;
   const result = rawPassthrough ? response.data : unwrapGraphQLResponse(
     response.data,
     response.headers,
     resolved.allowPartialData ? {
       allowPartialData: true,
-      onPartialData: (partialError) => {
+      onPartialData: (error) => {
         resolvedPartial = true;
-        if (isAvailabilityFailure(partialError)) {
-          partialAvailabilityFailure = partialError;
+        partialError = error;
+        if (isAvailabilityFailure(error) || isStreakNeutralFailure(error)) {
+          partialBreakerError = error;
         }
-        stampRequestId(partialError, requestId);
-        safeInvoke(
-          resolved.onError,
-          "onError",
-          resolved.onHookError,
-          resolved.diagnostics,
-          partialError,
-          buildErrorContext(requestId, url, method, attempt + 1, partialError)
-        );
       }
     } : void 0
   );
-  return { result, resolvedPartial, partialAvailabilityFailure };
+  return { result, resolvedPartial, partialError, partialBreakerError };
 };
 const executeWithRetry = async (options, resolved, stateOwner, modifiers = {}) => {
-  const { rawPassthrough = false, cacheMiss = false } = modifiers;
+  const { rawPassthrough = false, cacheMiss = false, writeBack, authGuard } = modifiers;
   const { url, method, data, headers } = options;
   const policy = resolved.retry;
   const requestId = randomUUID();
@@ -1654,9 +2044,30 @@ const executeWithRetry = async (options, resolved, stateOwner, modifiers = {}) =
   const budgetState = getRetryBudgetState(stateOwner, resolved.retryBudget);
   let attempt = 0;
   let pacedWaitMs = 0;
+  let retryWaitMs = 0;
   for (; ; ) {
     const startedAt = Date.now();
     const hookContext = { requestId, url, method, attempt: attempt + 1 };
+    const authError = authGuard?.();
+    if (authError !== void 0) {
+      safeInvoke(
+        resolved.onRequestStart,
+        "onRequestStart",
+        resolved.onHookError,
+        resolved.diagnostics,
+        hookContext
+      );
+      stampRequestId(authError, requestId);
+      safeInvoke(
+        resolved.onError,
+        "onError",
+        resolved.onHookError,
+        resolved.diagnostics,
+        authError,
+        buildErrorContext(requestId, url, method, attempt + 1, authError)
+      );
+      throw authError;
+    }
     const circuitError = checkCircuitOpen(circuit, resolved.circuitBreaker);
     if (circuitError !== void 0) {
       safeInvoke(
@@ -1667,20 +2078,25 @@ const executeWithRetry = async (options, resolved, stateOwner, modifiers = {}) =
         hookContext
       );
       stampRequestId(circuitError, requestId);
+      const cooldownRemainingMs = circuitCooldownRemainingMs(
+        circuit,
+        resolved.circuitBreaker
+      );
       safeInvoke(
         resolved.onError,
         "onError",
         resolved.onHookError,
         resolved.diagnostics,
         circuitError,
-        buildErrorContext(requestId, url, method, attempt + 1, circuitError)
+        buildErrorContext(requestId, url, method, attempt + 1, circuitError, {
+          host,
+          ...cooldownRemainingMs !== void 0 ? { retryAfterMs: cooldownRemainingMs } : {}
+        })
       );
       throw circuitError;
     }
-    const paceStartedAt = Date.now();
     try {
-      await awaitPaceDeadline(stateOwner, host, resolved, hookContext);
-      pacedWaitMs += Date.now() - paceStartedAt;
+      pacedWaitMs += await awaitPaceDeadline(stateOwner, host, resolved, hookContext);
     } catch (paceError) {
       if (circuit !== void 0 && circuit.probeInFlight) {
         recordCircuitSuccess(circuit, resolved, hookContext, host);
@@ -1707,34 +2123,54 @@ const executeWithRetry = async (options, resolved, stateOwner, modifiers = {}) =
         httpsAgent: resolved.httpsAgent
       });
       const rateLimit = getRateLimitInfo(response.headers);
+      const attemptDurationMs = Date.now() - startedAt;
+      const responseFacts = {
+        ...hookContext,
+        durationMs: attemptDurationMs,
+        ...rateLimit !== void 0 ? { rateLimit } : {},
+        ...cacheMiss ? { cacheHit: false } : {},
+        ...pacedWaitMs > 0 ? { pacedMs: pacedWaitMs } : {}
+      };
+      let outcome;
+      try {
+        outcome = resolveEnvelopeOutcome(response, resolved, rawPassthrough);
+      } catch (envelopeError) {
+        safeInvoke(
+          resolved.onResponse,
+          "onResponse",
+          resolved.onHookError,
+          resolved.diagnostics,
+          responseFacts
+        );
+        responseReported = true;
+        throw envelopeError;
+      }
+      const { result, resolvedPartial, partialError, partialBreakerError } = outcome;
+      const cacheWritten = writeBack?.(result, resolvedPartial) ?? false;
       safeInvoke(
         resolved.onResponse,
         "onResponse",
         resolved.onHookError,
         resolved.diagnostics,
-        {
-          ...hookContext,
-          durationMs: Date.now() - startedAt,
-          ...rateLimit !== void 0 ? { rateLimit } : {},
-          ...cacheMiss ? { cacheHit: false } : {},
-          ...pacedWaitMs > 0 ? { pacedMs: pacedWaitMs } : {}
-        }
+        { ...responseFacts, ...cacheWritten ? { cacheWrite: true } : {} }
       );
       responseReported = true;
-      const { result, resolvedPartial, partialAvailabilityFailure } = resolveEnvelopeOutcome(
-        response,
-        resolved,
-        rawPassthrough,
-        requestId,
-        url,
-        method,
-        attempt
-      );
-      if (partialAvailabilityFailure !== void 0) {
+      if (partialError !== void 0) {
+        stampRequestId(partialError, requestId);
+        safeInvoke(
+          resolved.onError,
+          "onError",
+          resolved.onHookError,
+          resolved.diagnostics,
+          partialError,
+          buildErrorContext(requestId, url, method, attempt + 1, partialError)
+        );
+      }
+      if (partialBreakerError !== void 0) {
         recordCircuitFailure(
           circuit,
           resolved.circuitBreaker,
-          partialAvailabilityFailure,
+          partialBreakerError,
           resolved,
           hookContext,
           host
@@ -1768,7 +2204,7 @@ const executeWithRetry = async (options, resolved, stateOwner, modifiers = {}) =
         hookContext,
         host
       );
-      const delay = computeNextRetryDelay({
+      const delayInput = {
         normalized,
         rawError: error,
         attempt,
@@ -1776,27 +2212,42 @@ const executeWithRetry = async (options, resolved, stateOwner, modifiers = {}) =
         budgetState,
         budget: resolved.retryBudget,
         wasProbe
-      });
+      };
+      const delay = computeNextRetryDelay(delayInput);
       if (delay !== null && budgetState !== void 0) {
         budgetState.retriesUsed += 1;
       }
-      reportFailure(
-        requestId,
-        url,
-        method,
-        attempt + 1,
-        normalized,
-        resolved,
-        delay ?? void 0
-      );
+      if (delay === null) {
+        paceAfterTerminalRateLimit(normalized, resolved, stateOwner, host);
+      }
+      reportFailure(requestId, url, method, attempt + 1, normalized, resolved, {
+        nextDelayMs: delay ?? void 0,
+        // The cumulative retry wait is present only when a wait
+        // occurred, following the same optional-presence convention
+        // as `pacedMs`. Terminal-failure metrics can report the
+        // total retry investment directly from the onError
+        // payload.
+        ...retryWaitMs > 0 ? { retryWaitMs } : {},
+        // The budget-exhaustion signal: this failure was
+        // retryable, but the window's retry spend was already
+        // spent. The hook can distinguish this from a failure that
+        // was never retryable, without polling
+        // transport-state snapshots. Gated on actual retryability
+        // (see isBudgetGatedFailure) so a never-retryable failure
+        // landing in a spent window is not miscounted as chronic
+        // budget exhaustion.
+        ...delay === null && isBudgetGatedFailure(delayInput) ? { budgetExhausted: true } : {}
+      });
       if (delay === null) {
         throw normalized;
       }
+      retryWaitMs += delay;
       attempt += 1;
       await sleep(delay, resolved.signal, requestId);
     }
   }
 };
+
 let warnedOptionsKeyedState = false;
 const warnOptionsKeyedState = (onHookError, diagnostics) => {
   if (warnedOptionsKeyedState) {
@@ -1846,29 +2297,6 @@ const buildHeaders = (resolvedAuth, contentType) => {
   }
   return headers;
 };
-const tryCacheRead = (resolved, method, url, data, cacheAuthKey) => {
-  const cached = resolved.responseCache.get(method, url, data, cacheAuthKey);
-  if (cached === void 0) {
-    return void 0;
-  }
-  if (resolved.onRequestStart !== void 0 || resolved.onResponse !== void 0) {
-    const requestId = randomUUID();
-    const hookContext = { requestId, url, method, attempt: 1 };
-    safeInvoke(
-      resolved.onRequestStart,
-      "onRequestStart",
-      resolved.onHookError,
-      resolved.diagnostics,
-      hookContext
-    );
-    safeInvoke(resolved.onResponse, "onResponse", resolved.onHookError, resolved.diagnostics, {
-      ...hookContext,
-      durationMs: 0,
-      cacheHit: true
-    });
-  }
-  return cached;
-};
 const sendRequest = async (url, method, data, auth, sendOptions) => {
   const {
     requiresAuth = false,
@@ -1880,21 +2308,13 @@ const sendRequest = async (url, method, data, auth, sendOptions) => {
   } = sendOptions ?? {};
   const isRestCall = protocol === "rest" || protocol === void 0 && contentType !== void 0;
   const resolvedAuth = resolveAuthMaterial(auth);
-  if (requiresAuth && !resolvedAuth.hasAuthMaterial) {
-    throw new AniLinkAuthError(operation);
-  }
+  const authGuard = requiresAuth && !resolvedAuth.hasAuthMaterial ? () => new AniLinkAuthError(operation) : void 0;
   const headers = buildHeaders(resolvedAuth, contentType);
   const resolved = resolveRequestOptions(options);
   if (stateOwner === void 0 && options !== void 0 && (resolved.circuitBreaker !== void 0 || resolved.retryBudget !== void 0 || resolved.paceWithRateLimit)) {
     warnOptionsKeyedState(resolved.onHookError, resolved.diagnostics);
   }
-  const cacheAuthKey = resolveCacheAuthKey(
-    resolved.responseCache,
-    method,
-    data,
-    isRestCall,
-    resolvedAuth
-  );
+  const cacheAuthKey = authGuard !== void 0 || resolved.bypassResponseCache ? void 0 : resolveCacheAuthKey(resolved.responseCache, method, data, isRestCall, resolvedAuth);
   let cacheGenerationAtRead;
   if (cacheAuthKey !== void 0) {
     const cached = tryCacheRead(resolved, method, url, data, cacheAuthKey);
@@ -1903,53 +2323,32 @@ const sendRequest = async (url, method, data, auth, sendOptions) => {
     }
     cacheGenerationAtRead = resolved.responseCache.getGeneration();
   }
-  const { result, resolvedPartial } = await executeWithRetry(
+  const writeBack = cacheAuthKey !== void 0 ? (result2, resolvedPartial) => resolvedPartial ? false : resolved.responseCache.setIfFresh(
+    method,
+    url,
+    data,
+    cacheAuthKey,
+    cacheGenerationAtRead,
+    result2,
+    isRestCall ? void 0 : extractQueryRootField(data)
+  ) : void 0;
+  const { result } = await executeWithRetry(
     { url, method, data, headers },
     resolved,
     stateOwner ?? options,
     {
       rawPassthrough: isRestCall,
-      // A cacheable read that missed the cache: its network response
-      // carries cacheHit: false so consumers can count misses without
-      // subtracting hits from total response counts. Fail-closed reads
-      // (no cache key) and mutations stay unmarked.
-      cacheMiss: cacheAuthKey !== void 0
+      cacheMiss: cacheAuthKey !== void 0,
+      authGuard,
+      writeBack
     }
   );
-  if (cacheAuthKey !== void 0) {
-    if (!resolvedPartial) {
-      resolved.responseCache.setIfFresh(
-        method,
-        url,
-        data,
-        cacheAuthKey,
-        cacheGenerationAtRead,
-        result
-      );
-    }
-  } else {
+  if (cacheAuthKey === void 0) {
     invalidateAfterMutation(resolved.responseCache, method, url, data, isRestCall);
   }
   return result;
 };
 
-const DEEP_MERGED_OPTION_KEYS = ["retry", "circuitBreaker", "retryBudget"];
-const assignDeepMergedOption = (merged, key, value) => {
-  merged[key] = value;
-};
-const mergeOptions = (base, overrides) => {
-  if (overrides === void 0) return base;
-  if (base === void 0) return overrides;
-  const merged = { ...base, ...overrides };
-  for (const key of DEEP_MERGED_OPTION_KEYS) {
-    const baseValue = base[key];
-    const overrideValue = overrides[key];
-    if (typeof baseValue === "object" && baseValue !== null && typeof overrideValue === "object" && overrideValue !== null) {
-      assignDeepMergedOption(merged, key, { ...baseValue, ...overrideValue });
-    }
-  }
-  return merged;
-};
 const resolveOperationLabel = (operation) => {
   const name = operation.constructor?.name;
   return typeof name === "string" && name.length > 0 ? name : void 0;
@@ -1970,8 +2369,8 @@ class BaseOperation {
   /**
    * The authentication token shared by all operations of an instance.
    *
-   * Mutable only through {@link BaseOperation.updateAuth} so a provider
-   * wiring seam can swap in refreshed auth material (for example the MAL
+   * Mutable only through {@link BaseOperation.updateAuth} so provider
+   * wiring can swap in refreshed auth material (for example the MAL
    * automatic token-refresh lifecycle) without rebuilding operations.
    */
   requestAuth;
@@ -2018,10 +2417,10 @@ class BaseOperation {
   /**
    * Swaps the instance authentication material in place.
    *
-   * @internal This mutator exists for provider wiring seams that refresh
+   * @internal This mutator exists for provider wiring that refreshes
    * credentials mid-flight (the MAL automatic token-refresh lifecycle swaps
    * the stored auth on the operation instances before replaying a 401'd
-   * request). It is not part of the public API surface.
+   * request). It is not part of the public API.
    *
    * @param auth - The replacement authentication material, or `undefined` to clear it.
    */
@@ -2031,12 +2430,11 @@ class BaseOperation {
   /**
    * Reads the current instance authentication material.
    *
-   * @internal Companion to {@link BaseOperation.updateAuth} for wiring
-   * seams that rebuild auth from the operation's live state at swap time
+   * @internal Companion to {@link BaseOperation.updateAuth} for provider
+   * wiring that rebuilds auth from the operation's current state at swap time
    * (the MAL refresh lifecycle reads each operation's current auth before
    * applying a fresh access token, so a replay never rebuilds headers from
-   * a stale construction-time snapshot). It is not part of the public API
-   * surface.
+   * a stale construction-time snapshot). It is not part of the public API.
    *
    * @returns The current {@link RequestAuthInput}, or `undefined`.
    */
@@ -2070,7 +2468,7 @@ class BaseOperation {
       // The stable owner keys cross-request transport state (circuit
       // breaker, retry budget, pacing deadlines) so failure streaks
       // accumulate across requests even when each call carries fresh
-      // per-request options — across the whole client when the wiring
+      // per-request options, across the whole client when the wiring
       // shared one owner, or across this instance's requests otherwise.
       stateOwner: this.stateOwner
     });
@@ -2264,8 +2662,8 @@ class AniListOperation extends BaseOperation {
    * Runs the shared validate-then-dispatch pipeline for an operation.
    *
    * Operations declare their contract as a {@link AniListExecuteOptions}
-   * object — variable-presence requirements, an optional type map, and the
-   * auth requirement — and this method applies them in a fixed order before
+   * object: variable-presence requirements, an optional type map, and the
+   * auth requirement. This method applies them in a fixed order before
    * delegating to {@link AniListOperation.request}.
    *
    * @param query - The GraphQL document to execute.
@@ -2278,144 +2676,17 @@ class AniListOperation extends BaseOperation {
    */
   async execute(query, variables, options) {
     const { requirements, mappings, requiresAuth, transportOptions } = options;
-    const variablesForRequirements = variables ?? {};
-    if (requirements) {
-      for (const requirement of requirements) {
-        requireVariables(variablesForRequirements, requirement, requirement.message);
-      }
-    }
-    if (mappings && variables !== void 0) {
-      validateVariables(variables, mappings);
-    }
-    return await this.request(query, variables, { requiresAuth, transportOptions });
-  }
-}
-
-const GRAPHQL_OPERATION_PATTERN = /^\s*(?:\{|(?:query|mutation)\b[\s\S]*\{)/;
-const stripLeadingComments = (query) => {
-  let rest = query;
-  for (; ; ) {
-    const line = /^[^\n]*\n/.exec(rest);
-    if (line === null) {
-      return rest;
-    }
-    if (!/^\s*(#|$)/.test(line[0])) {
-      return rest;
-    }
-    rest = rest.slice(line[0].length);
-  }
-};
-class CustomRequest extends AniListOperation {
-  /**
-   * `custom` sends a caller-authored GraphQL query or mutation document.
-   *
-   * The response follows the same unwrapping rule as every other operation:
-   * a document with a single root field resolves to the bare field value,
-   * while a document with multiple root fields resolves to the full
-   * `{ data }` envelope. Annotate `T` with the shape you expect — the bare
-   * value for single-root-field documents, or the envelope type itself when
-   * the document selects several root fields:
-   *
-   * ```typescript
-   * const viewer = await aniLink.anilist.custom<{ id: number }>("query { Viewer { id } }");
-   *
-   * // Multi-root-field document: T is the full envelope.
-   * const both = await aniLink.anilist.custom<{ data: { Media: { id: number }; User: { id: number } } }>(
-   *     "query { Media (id: 1) { id } User (id: 1) { id } }"
-   * );
-   * ```
-   *
-   * @param query - The GraphQL document to execute. It must declare an executable operation: an anonymous shorthand selection (`{ Viewer { id } }`) or a `query`/`mutation` document. AniList's HTTP endpoint does not serve subscriptions, so `subscription` documents are rejected here rather than failing remotely.
-   * @param variables - The variables for the document. This parameter is optional.
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
-   * @returns A promise that resolves to the unwrapped response data for single-root-field documents, or the full `{ data }` envelope otherwise.
-   * @throws An {@link AniLinkValidationError} when the query is empty or is not an executable document (for example a fragment-only definition).
-   * @throws An `AniLinkError` when the request fails. When AniList returns partial success (some fields resolve while others fail inside an HTTP 200 envelope), the thrown `AniLinkGraphQLError` exposes the resolved portion via its `partialData` field, so the fields that did resolve remain recoverable from the error.
-   * @see https://docs.anilist.co/reference/query
-   * @see https://docs.anilist.co/reference/mutation
-   */
-  async custom(query, variables = {}, options) {
-    if (typeof query !== "string" || !GRAPHQL_OPERATION_PATTERN.test(stripLeadingComments(query))) {
-      throw new AniLinkValidationError([
-        "custom() requires an executable GraphQL document (an anonymous selection or a query/mutation operation)"
-      ]);
-    }
-    return await this.request(query, variables, { transportOptions: options });
-  }
-}
-
-function fuzzyDate(options) {
-  const input = {
-    year: options?.year ?? 0,
-    month: options?.month ?? 0,
-    day: options?.day ?? 0
-  };
-  return input;
-}
-
-function fuzzyDateInt(options) {
-  const year = options?.year ?? 0;
-  const month = options?.month ?? 0;
-  const day = options?.day ?? 0;
-  return year * 1e4 + month * 100 + day;
-}
-
-function flattenMediaListCollection(response) {
-  if (!response || !Array.isArray(response.lists)) {
-    return [];
-  }
-  const byId = /* @__PURE__ */ new Map();
-  for (const group of response.lists) {
-    if (!Array.isArray(group.entries)) {
-      continue;
-    }
-    for (const entry of group.entries) {
-      mergeEntry(byId, entry, group.name, group.isCustomList, group.isSplitCompletedList);
-    }
-  }
-  return Array.from(byId.values());
-}
-function mergeEntry(byId, entry, listName, isCustomList, isSplitCompletedList) {
-  if (typeof entry !== "object" || entry === null || typeof entry.id !== "number" || !Number.isFinite(entry.id)) {
-    throw new AniLinkValidationError([
-      `flattenMediaListCollection: a list entry in "${listName}" is malformed \u2014 every entry must be an object with a finite numeric id.`
-    ]);
-  }
-  const existing = byId.get(entry.id);
-  if (existing) {
-    if (!existing.listNames.includes(listName)) {
-      existing.listNames.push(listName);
-    }
-    if (isCustomList) existing.inCustomList = true;
-    if (isSplitCompletedList) existing.inSplitCompletedList = true;
-    return;
-  }
-  byId.set(entry.id, {
-    id: entry.id,
-    userId: entry.userId,
-    mediaId: entry.mediaId,
-    status: entry.status,
-    score: entry.score,
-    progress: entry.progress,
-    listNames: [listName],
-    inCustomList: isCustomList,
-    inSplitCompletedList: isSplitCompletedList
-  });
-}
-
-function crossLink(media) {
-  const anilistToMal = /* @__PURE__ */ new Map();
-  const malToAnilist = /* @__PURE__ */ new Map();
-  const unmapped = [];
-  for (const entry of media) {
-    if (typeof entry.idMal !== "number") {
-      unmapped.push(entry);
-      continue;
+    const variablesForRequirements = variables ?? {};
+    if (requirements) {
+      for (const requirement of requirements) {
+        requireVariables(variablesForRequirements, requirement, requirement.message);
+      }
     }
-    anilistToMal.set(entry.id, entry.idMal);
-    malToAnilist.set(entry.idMal, entry.id);
+    if (mappings && variables !== void 0) {
+      validateVariables(variables, mappings);
+    }
+    return await this.request(query, variables, { requiresAuth, transportOptions });
   }
-  return { anilistToMal, malToAnilist, unmapped };
 }
 
 const MAX_CONCURRENCY = 8;
@@ -2429,6 +2700,32 @@ function resolvePositiveInt(value, fallback, name = "option") {
 function resolveCappedInt(value, max, fallback, name = "option") {
   return Math.min(resolvePositiveInt(value, fallback, name), max);
 }
+function resolvePaginationOptions(options, defaults) {
+  const perEntryName = defaults.naming === "page" ? "perPage" : "perChunk";
+  const startName = defaults.naming === "page" ? "startPage" : "startChunk";
+  const maxEntriesName = defaults.naming === "page" ? "maxPages" : "maxChunks";
+  return {
+    perEntry: resolveCappedInt(
+      options?.[perEntryName],
+      defaults.maxPerEntry,
+      defaults.defaultPerEntry,
+      perEntryName
+    ),
+    startEntry: resolvePositiveInt(options?.[startName], 1, startName),
+    maxEntries: resolvePositiveInt(
+      options?.[maxEntriesName],
+      defaults.defaultMaxEntries,
+      maxEntriesName
+    ),
+    concurrency: resolveCappedInt(
+      options?.concurrency,
+      MAX_CONCURRENCY,
+      defaults.defaultConcurrency,
+      "concurrency"
+    ),
+    diagnostics: resolveDiagnosticsMode(options?.diagnostics)
+  };
+}
 function bridgeAbortSignal(external) {
   const controller = new AbortController();
   if (external === void 0) {
@@ -2449,30 +2746,7 @@ function bridgeAbortSignal(external) {
     }
   };
 }
-async function fetchWithLookAhead(...args) {
-  if (typeof args[2] === "function") {
-    const [fetch2, extractHasMore2, extractNextKey, firstKey, maxEntries2, , signal2] = args;
-    return fetchCursorChain(
-      fetch2,
-      extractHasMore2,
-      extractNextKey,
-      firstKey,
-      maxEntries2,
-      signal2
-    );
-  }
-  if (args[2] === void 0) {
-    const [fetch2, extractHasMore2, , startNumber2, maxEntries2, concurrency2, signal2] = args;
-    return fetchNumericWithLookAhead(
-      fetch2,
-      extractHasMore2,
-      startNumber2,
-      maxEntries2,
-      concurrency2,
-      signal2
-    );
-  }
-  const [fetch, extractHasMore, startNumber, maxEntries, concurrency, signal, extractBound] = args;
+async function fetchWithLookAhead(fetch, extractHasMore, startNumber, maxEntries, concurrency, signal, extractBound) {
   return fetchNumericWithLookAhead(
     fetch,
     extractHasMore,
@@ -2501,13 +2775,14 @@ async function fetchNumericWithLookAhead(fetch, extractHasMore, startNumber, max
   let truncated = false;
   const readBound = extractBound ?? (() => void 0);
   let lastPageBound = Number.POSITIVE_INFINITY;
+  let windowSize = Math.min(1, concurrency);
   while (count < maxEntries) {
     if (signal?.aborted) {
       await Promise.allSettled(pending.slice(count));
       responses.length = count;
       return { responses, count, truncated: false };
     }
-    while (launched < maxEntries && launched - count < concurrency && startNumber + launched <= lastPageBound) {
+    while (launched < maxEntries && launched - count < windowSize && startNumber + launched <= lastPageBound) {
       const slot = launched;
       launched += 1;
       const request = fetch(startNumber + slot).then((response) => {
@@ -2543,6 +2818,7 @@ async function fetchNumericWithLookAhead(fetch, extractHasMore, startNumber, max
       responses.length = count;
       return { responses, count, truncated: false };
     }
+    windowSize = concurrency;
     if (count >= maxEntries) {
       await Promise.allSettled(pending.slice(count));
       truncated = true;
@@ -2551,38 +2827,6 @@ async function fetchNumericWithLookAhead(fetch, extractHasMore, startNumber, max
   }
   return { responses, count, truncated };
 }
-async function fetchCursorChain(fetch, extractHasMore, extractNextKey, firstKey, maxEntries, signal) {
-  const responses = [];
-  let key = firstKey;
-  while (responses.length < maxEntries && key !== void 0) {
-    if (signal?.aborted) {
-      return { responses, count: responses.length, truncated: false };
-    }
-    let entry;
-    try {
-      entry = await fetch(key);
-    } catch (err) {
-      if (signal?.aborted) {
-        return { responses, count: responses.length, truncated: false };
-      }
-      throw err;
-    }
-    responses.push(entry);
-    if (!extractHasMore(entry)) {
-      return { responses, count: responses.length, truncated: false };
-    }
-    key = extractNextKey(entry);
-  }
-  return {
-    responses,
-    count: responses.length,
-    // A degenerate guard (maxEntries <= 0) fetched nothing and cut
-    // nothing short: `truncated` reports whether the guard ended a run
-    // that still had data, matching the numeric driver's `while (count <
-    // maxEntries)` early exit.
-    truncated: responses.length >= maxEntries && maxEntries > 0
-  };
-}
 async function* streamNumericPages(fetchPage, isTerminalPage, options, extractBound) {
   const { perPage, startPage, maxPages, concurrency } = options;
   const { signal, dispose } = bridgeAbortSignal(options.signal);
@@ -2596,8 +2840,9 @@ async function* streamNumericPages(fetchPage, isTerminalPage, options, extractBo
   let terminal = false;
   let launchBound = Number.POSITIVE_INFINITY;
   const readBound = extractBound ?? (() => void 0);
-  const launchWindow = () => {
-    while (!terminal && nextToLaunch - startPage < maxPages && pending.size < concurrency && nextToLaunch <= launchBound) {
+  let windowSize = Math.min(1, concurrency);
+  const launchWindow = (limit) => {
+    while (!terminal && nextToLaunch - startPage < maxPages && pending.size < limit && nextToLaunch <= launchBound) {
       const page = nextToLaunch;
       nextToLaunch += 1;
       const request = fetchPage(page, perPage, signal);
@@ -2608,7 +2853,7 @@ async function* streamNumericPages(fetchPage, isTerminalPage, options, extractBo
   };
   try {
     while (nextToYield - startPage < maxPages) {
-      launchWindow();
+      launchWindow(windowSize);
       const page = nextToYield;
       const request = pending.get(page);
       if (request === void 0) {
@@ -2629,8 +2874,13 @@ async function* streamNumericPages(fetchPage, isTerminalPage, options, extractBo
       if (observedBound !== void 0 && observedBound < launchBound) {
         launchBound = observedBound;
       }
+      const pageIsTerminal = isTerminalPage(response);
+      if (!pageIsTerminal) {
+        windowSize = concurrency;
+        launchWindow(concurrency - 1);
+      }
       yield response;
-      if (isTerminalPage(response)) {
+      if (pageIsTerminal) {
         terminal = true;
         await Promise.allSettled([...pending.values()]);
         break;
@@ -2642,8 +2892,8 @@ async function* streamNumericPages(fetchPage, isTerminalPage, options, extractBo
   }
 }
 
-const DEFAULT_PER_PAGE$1 = 50;
-const MAX_PER_PAGE$1 = DEFAULT_PER_PAGE$1;
+const DEFAULT_PER_PAGE$2 = 50;
+const MAX_PER_PAGE$2 = DEFAULT_PER_PAGE$2;
 const DEFAULT_MAX_PAGES$1 = 100;
 const DEFAULT_PER_CHUNK = 500;
 const MAX_PER_CHUNK = DEFAULT_PER_CHUNK;
@@ -2652,6 +2902,20 @@ const safeCallback$1 = (callback, name, onHookError, diagnostics, payload) => {
   safeInvoke(callback, name, onHookError, diagnostics, payload);
 };
 const DEFAULT_CONCURRENCY$1 = 3;
+const PAGE_DEFAULTS = {
+  naming: "page",
+  maxPerEntry: MAX_PER_PAGE$2,
+  defaultPerEntry: DEFAULT_PER_PAGE$2,
+  defaultMaxEntries: DEFAULT_MAX_PAGES$1,
+  defaultConcurrency: DEFAULT_CONCURRENCY$1
+};
+const CHUNK_DEFAULTS = {
+  naming: "chunk",
+  maxPerEntry: MAX_PER_CHUNK,
+  defaultPerEntry: DEFAULT_PER_CHUNK,
+  defaultMaxEntries: DEFAULT_MAX_CHUNKS,
+  defaultConcurrency: DEFAULT_CONCURRENCY$1
+};
 function extractHasMore$1(response) {
   if (typeof response !== "object" || response === null) return false;
   if ("pageInfo" in response) {
@@ -2664,16 +2928,13 @@ function extractHasMore$1(response) {
   return response.hasNextChunk === true;
 }
 async function paginate(fetchPage, itemsKey, options) {
-  const perPage = resolveCappedInt(options?.perPage, MAX_PER_PAGE$1, DEFAULT_PER_PAGE$1, "perPage");
-  const startPage = resolvePositiveInt(options?.startPage, 1, "startPage");
-  const maxPages = resolvePositiveInt(options?.maxPages, DEFAULT_MAX_PAGES$1, "maxPages");
-  const concurrency = resolveCappedInt(
-    options?.concurrency,
-    MAX_CONCURRENCY,
-    DEFAULT_CONCURRENCY$1,
-    "concurrency"
-  );
-  const diagnostics = resolveDiagnosticsMode(options?.diagnostics);
+  const {
+    perEntry: perPage,
+    startEntry: startPage,
+    maxEntries: maxPages,
+    concurrency,
+    diagnostics
+  } = resolvePaginationOptions(options, PAGE_DEFAULTS);
   const { signal, dispose } = bridgeAbortSignal(options?.signal);
   try {
     const { responses, count, truncated } = await fetchWithLookAhead(
@@ -2685,92 +2946,500 @@ async function paginate(fetchPage, itemsKey, options) {
       signal,
       extractLastPageBound
     );
-    const items = [];
-    const pages = [];
-    for (const response of responses) {
-      const raw = response[itemsKey];
-      if (raw === void 0) {
-        throw new AniLinkValidationError([
-          `paginate: the page response has no "${itemsKey}" key. Check the itemsKey argument.`
-        ]);
+    const items = [];
+    const pages = [];
+    for (const response of responses) {
+      const raw = response[itemsKey];
+      if (raw === void 0) {
+        throw new AniLinkValidationError([
+          `paginate: the page response has no "${itemsKey}" key. Check the itemsKey argument.`
+        ]);
+      }
+      const pageItems = Array.isArray(raw) ? raw : [];
+      pages.push({ pageInfo: response.pageInfo, items: pageItems });
+      items.push(...pageItems);
+      safeCallback$1(options?.onPage, "onPage", options?.onHookError, diagnostics, {
+        pageInfo: response.pageInfo,
+        items: pageItems
+      });
+    }
+    return { items, pages, pageCount: count, truncated };
+  } finally {
+    dispose();
+  }
+}
+async function* paginatePages(fetchPage, options) {
+  const {
+    perEntry: perPage,
+    startEntry: startPage,
+    maxEntries: maxPages,
+    concurrency
+  } = resolvePaginationOptions(options, PAGE_DEFAULTS);
+  yield* streamNumericPages(
+    fetchPage,
+    (response) => !response.pageInfo.hasNextPage,
+    { perPage, startPage, maxPages, concurrency, signal: options?.signal },
+    extractLastPageBound
+  );
+}
+async function paginateChunks(fetchChunk, itemsKey, options) {
+  const {
+    perEntry: perChunk,
+    startEntry: startChunk,
+    maxEntries: maxChunks,
+    concurrency,
+    diagnostics
+  } = resolvePaginationOptions(options, CHUNK_DEFAULTS);
+  const { signal, dispose } = bridgeAbortSignal(options?.signal);
+  try {
+    const { responses, count, truncated } = await fetchWithLookAhead(
+      (number) => fetchChunk(number, perChunk, signal),
+      extractHasMore$1,
+      startChunk,
+      maxChunks,
+      concurrency,
+      signal
+    );
+    const items = [];
+    const chunks = [];
+    for (const response of responses) {
+      const raw = response[itemsKey];
+      if (raw === void 0) {
+        throw new AniLinkValidationError([
+          `paginateChunks: the chunk response has no "${itemsKey}" key. Check the itemsKey argument.`
+        ]);
+      }
+      const chunkItems = Array.isArray(raw) ? raw : [];
+      chunks.push({ hasNextChunk: response.hasNextChunk, items: chunkItems });
+      items.push(...chunkItems);
+      safeCallback$1(options?.onChunk, "onChunk", options?.onHookError, diagnostics, {
+        hasNextChunk: response.hasNextChunk,
+        items: chunkItems
+      });
+    }
+    return { items, chunks, chunkCount: count, truncated };
+  } finally {
+    dispose();
+  }
+}
+
+const GRAPHQL_OPERATION_PATTERN = /^\s*(?:\{|(?:query|mutation)\b[\s\S]*\{)/;
+const GRAPHQL_PAGE_QUERY_PATTERN = /^\s*query\b[\s\S]*\bPage\s*\(/;
+const CUSTOM_PAGE_VALIDATION_MESSAGE = "customPage() requires a query document whose single root field is Page, selecting it with $page and $perPage Int variables";
+const stripLeadingComments = (query) => {
+  let rest = query;
+  for (; ; ) {
+    const line = /^[^\n]*\n/.exec(rest);
+    if (line === null) {
+      return rest;
+    }
+    if (!/^\s*(#|$)/.test(line[0])) {
+      return rest;
+    }
+    rest = rest.slice(line[0].length);
+  }
+};
+class CustomRequest extends AniListOperation {
+  /**
+   * `custom` sends a caller-authored GraphQL query or mutation document.
+   *
+   * The response follows the same unwrapping rule as every other operation:
+   * a document with a single root field resolves to the bare field value,
+   * while a document with multiple root fields resolves to the full
+   * `{ data }` envelope. Annotate `T` with the shape you expect: the bare
+   * value for single-root-field documents, or the envelope type itself when
+   * the document selects several root fields:
+   *
+   * ```typescript
+   * const viewer = await aniLink.anilist.custom<{ id: number }>("query { Viewer { id } }");
+   *
+   * // Multi-root-field document: T is the full envelope.
+   * const both = await aniLink.anilist.custom<{ data: { Media: { id: number }; User: { id: number } } }>(
+   *     "query { Media (id: 1) { id } User (id: 1) { id } }"
+   * );
+   * ```
+   *
+   * @param query - The GraphQL document to execute. It must declare an executable operation: an anonymous shorthand selection (`{ Viewer { id } }`) or a `query`/`mutation` document. AniList's HTTP endpoint does not serve subscriptions, so `subscription` documents are rejected here rather than failing remotely.
+   * @param variables - The variables for the document. This parameter is optional.
+   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @returns A promise that resolves to the unwrapped response data for single-root-field documents, or the full `{ data }` envelope otherwise.
+   * @throws An {@link AniLinkValidationError} when the query is empty or is not an executable document (for example a fragment-only definition).
+   * @throws An `AniLinkError` when the request fails. When AniList returns partial success (some fields resolve while others fail inside an HTTP 200 envelope), the thrown `AniLinkGraphQLError` exposes the resolved portion via its `partialData` field, so the fields that did resolve remain recoverable from the error.
+   * @see https://docs.anilist.co/reference/query
+   * @see https://docs.anilist.co/reference/mutation
+   */
+  async custom(query, variables = {}, options) {
+    if (typeof query !== "string" || !GRAPHQL_OPERATION_PATTERN.test(stripLeadingComments(query))) {
+      throw new AniLinkValidationError([
+        "custom() requires an executable GraphQL document (an anonymous selection or a query/mutation operation)"
+      ]);
+    }
+    return await this.request(query, variables, { transportOptions: options });
+  }
+  /**
+   * `customPage` paginates a caller-authored `Page` document through the
+   * shared engine. Use it for collections whose field combination the
+   * generated page operations do not expose.
+   *
+   * The document must declare the standard AniList `Page` wrapper with
+   * `$page`/`$perPage` `Int` variables and select `pageInfo { hasNextPage }`
+   * (the engine's terminal flag) plus an items array under a key of your
+   * choosing. Because `Page` is the document's single root field, the
+   * response unwraps to the bare `Page` object, so `TPage` is the `Page`
+   * selection's shape, not an envelope:
+   *
+   * ```typescript
+   * const result = await aniLink.anilist.customPage(
+   *     `query ($page: Int, $perPage: Int) {
+   *         Page(page: $page, perPage: $perPage) {
+   *             pageInfo { total currentPage lastPage hasNextPage }
+   *             media(type: ANIME, sort: POPULARITY_DESC) { id title { romaji } }
+   *         }
+   *     }`,
+   *     "media",
+   *     {},
+   *     { perPage: 50, maxPages: 5 }
+   * );
+   * ```
+   *
+   * The traversal reuses every engine guard: `perPage` clamping (AniList caps
+   * it at 50), the `maxPages` bound (default 100), look-ahead `concurrency`
+   * (default 3), `AbortSignal` forwarding, and the `pageInfo.lastPage`
+   * terminal bound. `variables` are forwarded verbatim on every page
+   * request with `page`/`perPage` merged over them.
+   *
+   * @typeParam TPage - The `Page` selection's response shape; must include `pageInfo` (the engine reads `pageInfo.hasNextPage`).
+   * @typeParam K - The key of the items array on `TPage` (e.g. `"media"`).
+   * @param query - The GraphQL document to traverse. It must be a `query` document whose single root field is `Page`, selected with `$page`/`$perPage` variables; mutation documents, non-`Page` documents, and documents with additional root fields are rejected locally.
+   * @param itemsKey - The key of the items array on the `Page` response (e.g. `"media"`, `"characters"`).
+   * @param variables - The variables for the document, forwarded on every page request with `page`/`perPage` merged over them. This parameter is optional.
+   * @param options - Optional `CustomPageOptions`: the `PaginateOptions` controls (`perPage`, `startPage`, `maxPages`, `concurrency`, `signal`, `onPage`, `onHookError`, `diagnostics`) plus per-request transport settings under `transportOptions`, merged over the instance-level ones for this call only.
+   * @returns The collected items, per-page snapshots, page count, and whether the `maxPages` guard or the server-reported `lastPage` bound truncated the run; a `PaginateResult`.
+   * @throws An {@link AniLinkValidationError} when the document is not a `query` selecting the `Page` root field with `$page`/`$perPage` variable references, or when a fetched page response has no `itemsKey` key at all.
+   * @throws An `AniLinkError` when a page request fails.
+   * @see https://docs.anilist.co/reference/object/page
+   * @example
+   * ```typescript
+   * const result = await aniLink.anilist.customPage(
+   *     `query ($page: Int, $perPage: Int) {
+   *         Page(page: $page, perPage: $perPage) {
+   *             pageInfo { hasNextPage }
+   *             characters(search: "spike") { id name { full } }
+   *         }
+   *     }`,
+   *     "characters",
+   *     {},
+   *     { perPage: 50, maxPages: 3 }
+   * );
+   * console.log(result.items.length, result.truncated);
+   * ```
+   */
+  async customPage(query, itemsKey, variables = {}, options) {
+    if (typeof query !== "string") {
+      throw new AniLinkValidationError([CUSTOM_PAGE_VALIDATION_MESSAGE]);
+    }
+    const normalized = stripLeadingComments(query);
+    if (!GRAPHQL_OPERATION_PATTERN.test(normalized) || !GRAPHQL_PAGE_QUERY_PATTERN.test(normalized) || extractQueryRootField({ query }) !== "Page" || !/\$page\b/.test(normalized) || !/\$perPage\b/.test(normalized)) {
+      throw new AniLinkValidationError([CUSTOM_PAGE_VALIDATION_MESSAGE]);
+    }
+    const { transportOptions, ...paginateOptions } = options ?? {};
+    return await paginate(
+      (page, perPage, signal) => this.request(
+        query,
+        { ...variables, page, perPage },
+        { transportOptions: { ...transportOptions, signal } }
+      ),
+      itemsKey,
+      paginateOptions
+    );
+  }
+}
+
+function fuzzyDate(options) {
+  const input = {
+    year: options?.year ?? 0,
+    month: options?.month ?? 0,
+    day: options?.day ?? 0
+  };
+  return input;
+}
+
+function fuzzyDateInt(options) {
+  const year = options?.year ?? 0;
+  const month = options?.month ?? 0;
+  const day = options?.day ?? 0;
+  return year * 1e4 + month * 100 + day;
+}
+
+function flattenMediaListCollection(response) {
+  if (!response || !Array.isArray(response.lists)) {
+    return [];
+  }
+  const byId = /* @__PURE__ */ new Map();
+  for (const group of response.lists) {
+    if (!Array.isArray(group.entries)) {
+      continue;
+    }
+    for (const entry of group.entries) {
+      mergeEntry(byId, entry, group.name, group.isCustomList, group.isSplitCompletedList);
+    }
+  }
+  return Array.from(byId.values());
+}
+function mergeEntry(byId, entry, listName, isCustomList, isSplitCompletedList) {
+  if (typeof entry !== "object" || entry === null || typeof entry.id !== "number" || !Number.isFinite(entry.id)) {
+    throw new AniLinkValidationError([
+      `flattenMediaListCollection: a list entry in "${listName}" is malformed \u2014 every entry must be an object with a finite numeric id.`
+    ]);
+  }
+  const existing = byId.get(entry.id);
+  if (existing) {
+    if (!existing.listNames.includes(listName)) {
+      existing.listNames.push(listName);
+    }
+    if (isCustomList) existing.inCustomList = true;
+    if (isSplitCompletedList) existing.inSplitCompletedList = true;
+    return;
+  }
+  byId.set(entry.id, {
+    id: entry.id,
+    userId: entry.userId,
+    mediaId: entry.mediaId,
+    status: entry.status,
+    score: entry.score,
+    progress: entry.progress,
+    listNames: [listName],
+    inCustomList: isCustomList,
+    inSplitCompletedList: isSplitCompletedList
+  });
+}
+
+function crossLink(media) {
+  const anilistToMal = /* @__PURE__ */ new Map();
+  const malToAnilist = /* @__PURE__ */ new Map();
+  const unmapped = [];
+  for (const entry of media) {
+    if (typeof entry.idMal !== "number") {
+      unmapped.push(entry);
+      continue;
+    }
+    anilistToMal.set(entry.id, entry.idMal);
+    malToAnilist.set(entry.idMal, entry.id);
+  }
+  return { anilistToMal, malToAnilist, unmapped };
+}
+
+const ARM_IDS_URL = "https://arm.haglund.dev/api/v2/ids?include=anilist,myanimelist";
+const ARM_MAX_IDS_PER_REQUEST = 100;
+async function mapExternalIds(source, ids, options = {}) {
+  return requestMapExternalIds(source, ids, options, options);
+}
+const buildMapExternalIdsFacade = (instanceOptions, stateOwner) => (source, ids, options) => requestMapExternalIds(source, ids, mergeOptions(instanceOptions, options), stateOwner);
+const requestMapExternalIds = async (source, ids, options, stateOwner) => {
+  const anilistToMal = /* @__PURE__ */ new Map();
+  const malToAnilist = /* @__PURE__ */ new Map();
+  const unmapped = [];
+  if (ids.length === 0) {
+    return { anilistToMal, malToAnilist, unmapped };
+  }
+  for (let offset = 0; offset < ids.length; offset += ARM_MAX_IDS_PER_REQUEST) {
+    const batchIds = ids.slice(offset, offset + ARM_MAX_IDS_PER_REQUEST);
+    const responseBody = await sendRequest(
+      ARM_IDS_URL,
+      "POST",
+      batchIds.map((id) => ({ [source]: id })),
+      void 0,
+      {
+        options,
+        protocol: "rest",
+        stateOwner
+      }
+    );
+    if (!Array.isArray(responseBody) || responseBody.length !== batchIds.length) {
+      throw new TypeError("ARM ID mapping response did not contain one result per input id.");
+    }
+    for (let index = 0; index < batchIds.length; index += 1) {
+      const relation = responseBody[index];
+      const inputId = batchIds[index];
+      const mappedId = source === "anilist" ? relation?.myanimelist : relation?.anilist;
+      if (typeof mappedId !== "number") {
+        unmapped.push(inputId);
+        continue;
+      }
+      if (source === "anilist") {
+        anilistToMal.set(inputId, mappedId);
+        malToAnilist.set(mappedId, inputId);
+      } else {
+        anilistToMal.set(mappedId, inputId);
+        malToAnilist.set(inputId, mappedId);
       }
-      const pageItems = Array.isArray(raw) ? raw : [];
-      pages.push({ pageInfo: response.pageInfo, items: pageItems });
-      items.push(...pageItems);
-      safeCallback$1(options?.onPage, "onPage", options?.onHookError, diagnostics, {
-        pageInfo: response.pageInfo,
-        items: pageItems
-      });
     }
-    return { items, pages, pageCount: count, truncated };
-  } finally {
-    dispose();
   }
+  return { anilistToMal, malToAnilist, unmapped };
+};
+
+const DEFAULT_INTERVAL_MS = 6e4;
+const MIN_INTERVAL_MS = 1e4;
+const DEFAULT_PER_PAGE$1 = 50;
+const MAX_PER_PAGE$1 = DEFAULT_PER_PAGE$1;
+const MAX_DRAIN_PAGES = 10;
+const SEEN_RETENTION_POLLS = 3;
+const sleepBetweenPolls = (ms, signal) => new Promise((resolve) => {
+  const timeout = setTimeout(() => {
+    signal?.removeEventListener("abort", abort);
+    resolve();
+  }, ms);
+  timeout.unref();
+  const abort = () => {
+    clearTimeout(timeout);
+    resolve();
+  };
+  if (signal?.aborted) {
+    clearTimeout(timeout);
+    resolve();
+    return;
+  }
+  signal?.addEventListener("abort", abort, { once: true });
+});
+const dropUndefined = (variables) => {
+  const result = {};
+  for (const [key, value] of Object.entries(variables)) {
+    if (value !== void 0) {
+      result[key] = value;
+    }
+  }
+  return result;
+};
+async function drainPoll(ctx) {
+  const { fetchPage, perPage, since, signal, seen } = ctx;
+  const fresh = [];
+  const startPage = ctx.resumeFromPage;
+  const resuming = startPage > 1;
+  const baselineDrain = ctx.baselinePending;
+  ctx.resumeFromPage = 1;
+  let hitSeenFrontier = false;
+  let drainedToCap = false;
+  let page = startPage;
+  let lastDrainedItems = [];
+  let lastDrainedHasNext = false;
+  for (; page < startPage + MAX_DRAIN_PAGES; page++) {
+    const { pageInfo, items } = await fetchPage(page, perPage, signal);
+    lastDrainedItems = items;
+    lastDrainedHasNext = pageInfo.hasNextPage;
+    for (const item of items) {
+      if (seen.has(item.id) || since !== void 0 && item.createdAt <= since) {
+        hitSeenFrontier = true;
+        continue;
+      }
+      if (!ctx.baselinePending) {
+        fresh.push(item);
+      }
+    }
+    for (const item of items) {
+      seen.set(item.id, item.createdAt);
+    }
+    if (hitSeenFrontier || items.length < perPage) break;
+    if (!pageInfo.hasNextPage) break;
+    if (page === startPage + MAX_DRAIN_PAGES - 1) {
+      drainedToCap = true;
+    }
+  }
+  if (drainedToCap) {
+    ctx.resumeFromPage = baselineDrain ? startPage : page;
+  } else if (resuming && hitSeenFrontier && page === startPage && lastDrainedHasNext) {
+    ctx.resumeFromPage = startPage + 1;
+  }
+  ctx.baselinePending = false;
+  const oldestDrained = lastDrainedItems[lastDrainedItems.length - 1];
+  return {
+    fresh,
+    resumeFromPage: ctx.resumeFromPage,
+    watermark: oldestDrained?.createdAt
+  };
 }
-async function* paginatePages(fetchPage, options) {
-  const perPage = resolveCappedInt(options?.perPage, MAX_PER_PAGE$1, DEFAULT_PER_PAGE$1, "perPage");
-  const startPage = resolvePositiveInt(options?.startPage, 1, "startPage");
-  const maxPages = resolvePositiveInt(options?.maxPages, DEFAULT_MAX_PAGES$1, "maxPages");
-  const concurrency = resolveCappedInt(
-    options?.concurrency,
-    MAX_CONCURRENCY,
-    DEFAULT_CONCURRENCY$1,
-    "concurrency"
+async function* watchFeed(fetchPage, options) {
+  const intervalMs = Math.max(
+    resolvePositiveInt(options.intervalMs, DEFAULT_INTERVAL_MS, "intervalMs"),
+    MIN_INTERVAL_MS
   );
-  yield* streamNumericPages(
+  const perPage = resolveCappedInt(options.perPage, MAX_PER_PAGE$1, DEFAULT_PER_PAGE$1, "perPage");
+  const { since, signal } = options;
+  const ctx = {
     fetchPage,
-    (response) => !response.pageInfo.hasNextPage,
-    { perPage, startPage, maxPages, concurrency, signal: options?.signal },
-    extractLastPageBound
-  );
-}
-async function paginateChunks(fetchChunk, itemsKey, options) {
-  const perChunk = resolveCappedInt(
-    options?.perChunk,
-    MAX_PER_CHUNK,
-    DEFAULT_PER_CHUNK,
-    "perChunk"
-  );
-  const startChunk = resolvePositiveInt(options?.startChunk, 1, "startChunk");
-  const maxChunks = resolvePositiveInt(options?.maxChunks, DEFAULT_MAX_CHUNKS, "maxChunks");
-  const concurrency = resolveCappedInt(
-    options?.concurrency,
-    MAX_CONCURRENCY,
-    DEFAULT_CONCURRENCY$1,
-    "concurrency"
-  );
-  const diagnostics = resolveDiagnosticsMode(options?.diagnostics);
-  const { signal, dispose } = bridgeAbortSignal(options?.signal);
-  try {
-    const { responses, count, truncated } = await fetchWithLookAhead(
-      (number) => fetchChunk(number, perChunk, signal),
-      extractHasMore$1,
-      startChunk,
-      maxChunks,
-      concurrency,
-      signal
-    );
-    const items = [];
-    const chunks = [];
-    for (const response of responses) {
-      const raw = response[itemsKey];
-      if (raw === void 0) {
-        throw new AniLinkValidationError([
-          `paginateChunks: the chunk response has no "${itemsKey}" key. Check the itemsKey argument.`
-        ]);
+    perPage,
+    since,
+    signal,
+    seen: /* @__PURE__ */ new Map(),
+    baselinePending: since === void 0,
+    resumeFromPage: 1
+  };
+  while (!signal?.aborted) {
+    const { fresh, resumeFromPage, watermark } = await drainPoll(ctx);
+    ctx.resumeFromPage = resumeFromPage;
+    if (watermark !== void 0) {
+      const pruneBefore = watermark - intervalMs / 1e3 * SEEN_RETENTION_POLLS;
+      for (const [id, createdAt] of ctx.seen) {
+        if (createdAt < pruneBefore) {
+          ctx.seen.delete(id);
+        }
       }
-      const chunkItems = Array.isArray(raw) ? raw : [];
-      chunks.push({ hasNextChunk: response.hasNextChunk, items: chunkItems });
-      items.push(...chunkItems);
-      safeCallback$1(options?.onChunk, "onChunk", options?.onHookError, diagnostics, {
-        hasNextChunk: response.hasNextChunk,
-        items: chunkItems
-      });
     }
-    return { items, chunks, chunkCount: count, truncated };
-  } finally {
-    dispose();
-  }
+    for (let index = fresh.length - 1; index >= 0; index--) {
+      yield fresh[index];
+    }
+    await sleepBetweenPolls(intervalMs, signal);
+  }
+}
+function watchNotifications(fetch, options = {}) {
+  const { type, type_in, resetNotificationCount, asHtml, ...shared } = options;
+  let resetPending = resetNotificationCount === true;
+  return watchFeed(async (page, perPage, signal) => {
+    const resetNow = resetPending;
+    const response = await fetch(
+      dropUndefined({
+        page,
+        perPage,
+        type,
+        type_in,
+        resetNotificationCount: resetNow,
+        asHtml
+      }),
+      // Poll requests always bypass the response cache: each poll
+      // needs current data and must never be served a cached page,
+      // so a cache enabled on the client cannot make the watcher
+      // stale.
+      { ...shared.transportOptions, signal, bypassResponseCache: true }
+    );
+    resetPending = false;
+    return { pageInfo: response.pageInfo, items: response.notifications };
+  }, shared);
+}
+function watchActivity(fetch, options = {}) {
+  const { userId, messengerId, mediaId, type, isFollowing, sort, ...shared } = options;
+  return watchFeed(async (page, perPage, signal) => {
+    const response = await fetch(
+      // ID_DESC (newest first) is the order the watcher needs:
+      // new items enter at the front, so page 1 is always the
+      // window that contains them. A caller-provided sort
+      // overrides it; see the option's caveat.
+      dropUndefined({
+        page,
+        perPage,
+        userId,
+        messengerId,
+        mediaId,
+        type,
+        isFollowing,
+        sort: sort ?? ["ID_DESC"]
+      }),
+      // Poll requests always bypass the response cache: each poll
+      // needs current data and must never be served a cached page,
+      // so a cache enabled on the client cannot make the watcher
+      // stale.
+      { ...shared.transportOptions, signal, bypassResponseCache: true }
+    );
+    return { pageInfo: response.pageInfo, items: response.activities };
+  }, shared);
 }
 
 const parseCache = /* @__PURE__ */ new Map();
@@ -6077,6 +6746,7 @@ class NotificationsQuery extends AniListOperation {
       variables,
       {
         mappings: NotificationsMappings,
+        requiresAuth: true,
         transportOptions
       }
     );
@@ -8226,12 +8896,13 @@ class SaveMediaListEntryMutation extends AniListOperation {
   }
 }
 
-function op(name, operationClass, options) {
+function op$1(name, operationClass, options) {
   return {
     name,
     operationClass,
     methodName: name,
-    fieldsEnabled: options?.fieldsEnabled ?? false
+    fieldsEnabled: options?.fieldsEnabled ?? false,
+    alwaysKeys: options?.alwaysKeys ?? []
   };
 }
 function opAs(name, operationClass, methodName, options) {
@@ -8239,96 +8910,224 @@ function opAs(name, operationClass, methodName, options) {
     name,
     operationClass,
     methodName,
-    fieldsEnabled: options?.fieldsEnabled ?? false
+    fieldsEnabled: options?.fieldsEnabled ?? false,
+    alwaysKeys: options?.alwaysKeys ?? []
   };
 }
 const ANILIST_OPERATION_REGISTRY = {
   query: [
-    op("user", UserQuery, { fieldsEnabled: true }),
-    op("media", MediaQuery, { fieldsEnabled: true }),
-    op("mediaTrend", MediaTrendQuery, { fieldsEnabled: true }),
-    op("airingSchedule", AiringScheduleQuery, { fieldsEnabled: true }),
-    op("character", CharacterQuery, { fieldsEnabled: true }),
-    op("staff", StaffQuery, { fieldsEnabled: true }),
-    op("mediaList", MediaListQuery, { fieldsEnabled: true }),
-    op("mediaListCollection", MediaListCollectionQuery, { fieldsEnabled: true }),
-    op("genreCollection", GenreCollectionQuery),
-    op("mediaTagCollection", MediaTagCollectionQuery),
-    op("viewer", ViewerQuery),
-    op("notification", NotificationQuery, { fieldsEnabled: true }),
-    op("studio", StudioQuery, { fieldsEnabled: true }),
-    op("review", ReviewQuery, { fieldsEnabled: true }),
-    op("activity", ActivityQuery, { fieldsEnabled: true }),
-    op("activityReply", ActivityReplyQuery),
-    op("following", FollowingQuery),
-    op("follower", FollowerQuery),
-    op("thread", ThreadQuery, { fieldsEnabled: true }),
-    op("threadComment", ThreadCommentQuery, { fieldsEnabled: true }),
-    op("recommendation", RecommendationQuery, { fieldsEnabled: true }),
-    op("markdown", MarkdownQuery),
-    op("aniChartUser", AniChartUserQuery),
-    op("siteStatistics", SiteStatisticsQuery, { fieldsEnabled: true }),
-    op("externalLinkSourceCollection", ExternalLinkSourceCollectionQuery)
+    op$1("user", UserQuery, { fieldsEnabled: true, alwaysKeys: USER_ALWAYS }),
+    op$1("media", MediaQuery, { fieldsEnabled: true, alwaysKeys: MEDIA_ALWAYS }),
+    op$1("mediaTrend", MediaTrendQuery, { fieldsEnabled: true, alwaysKeys: MEDIA_TREND_ALWAYS }),
+    op$1("airingSchedule", AiringScheduleQuery, {
+      fieldsEnabled: true,
+      alwaysKeys: AIRING_SCHEDULE_ALWAYS
+    }),
+    op$1("character", CharacterQuery, { fieldsEnabled: true, alwaysKeys: CHARACTER_ALWAYS }),
+    op$1("staff", StaffQuery, { fieldsEnabled: true, alwaysKeys: STAFF_ALWAYS }),
+    op$1("mediaList", MediaListQuery, { fieldsEnabled: true, alwaysKeys: MEDIA_LIST_ALWAYS }),
+    op$1("mediaListCollection", MediaListCollectionQuery, {
+      fieldsEnabled: true,
+      alwaysKeys: MEDIA_LIST_COLLECTION_ALWAYS
+    }),
+    op$1("genreCollection", GenreCollectionQuery),
+    op$1("mediaTagCollection", MediaTagCollectionQuery),
+    op$1("viewer", ViewerQuery),
+    op$1("notification", NotificationQuery, { fieldsEnabled: true }),
+    op$1("studio", StudioQuery, { fieldsEnabled: true, alwaysKeys: STUDIO_ALWAYS }),
+    op$1("review", ReviewQuery, { fieldsEnabled: true, alwaysKeys: REVIEW_ALWAYS }),
+    op$1("activity", ActivityQuery, { fieldsEnabled: true }),
+    op$1("activityReply", ActivityReplyQuery),
+    op$1("following", FollowingQuery),
+    op$1("follower", FollowerQuery),
+    op$1("thread", ThreadQuery, { fieldsEnabled: true, alwaysKeys: THREAD_ALWAYS }),
+    op$1("threadComment", ThreadCommentQuery, {
+      fieldsEnabled: true,
+      alwaysKeys: THREAD_COMMENT_ALWAYS
+    }),
+    op$1("recommendation", RecommendationQuery, {
+      fieldsEnabled: true,
+      alwaysKeys: RECOMMENDATION_ALWAYS
+    }),
+    op$1("markdown", MarkdownQuery),
+    op$1("aniChartUser", AniChartUserQuery),
+    op$1("siteStatistics", SiteStatisticsQuery, {
+      fieldsEnabled: true,
+      alwaysKeys: SITE_STATISTICS_ALWAYS
+    }),
+    op$1("externalLinkSourceCollection", ExternalLinkSourceCollectionQuery)
   ],
   page: [
-    op("users", UsersQuery, { fieldsEnabled: true }),
-    op("medias", MediasQuery, { fieldsEnabled: true }),
-    op("characters", CharactersQuery, { fieldsEnabled: true }),
-    op("staffs", StaffsQuery, { fieldsEnabled: true }),
-    op("studios", StudiosQuery, { fieldsEnabled: true }),
-    op("mediaLists", MediaListsQuery, { fieldsEnabled: true }),
-    op("airingSchedules", AiringSchedulesQuery, { fieldsEnabled: true }),
-    op("mediaTrends", MediaTrendsQuery, { fieldsEnabled: true }),
-    op("notifications", NotificationsQuery, { fieldsEnabled: true }),
-    op("followers", FollowersQuery, { fieldsEnabled: true }),
-    opAs("following", FollowingsQuery, "followings", { fieldsEnabled: true }),
-    op("activities", ActivitiesQuery, { fieldsEnabled: true }),
-    opAs("activityReplies", ActivityRepliesQuery, "activityReplies", { fieldsEnabled: true }),
-    op("threads", ThreadsQuery, { fieldsEnabled: true }),
-    opAs("threadComments", ThreadCommentsQuery, "threadComments", { fieldsEnabled: true }),
-    op("reviews", ReviewsQuery, { fieldsEnabled: true }),
-    opAs("recommendations", RecommendationsQuery, "recommendations", { fieldsEnabled: true }),
-    op("likes", LikesQuery, { fieldsEnabled: true })
+    op$1("users", UsersQuery, { fieldsEnabled: true, alwaysKeys: PAGE_ALWAYS }),
+    op$1("medias", MediasQuery, { fieldsEnabled: true, alwaysKeys: PAGE_ALWAYS }),
+    op$1("characters", CharactersQuery, { fieldsEnabled: true, alwaysKeys: PAGE_ALWAYS }),
+    op$1("staffs", StaffsQuery, { fieldsEnabled: true, alwaysKeys: PAGE_ALWAYS }),
+    op$1("studios", StudiosQuery, { fieldsEnabled: true, alwaysKeys: PAGE_ALWAYS }),
+    op$1("mediaLists", MediaListsQuery, { fieldsEnabled: true, alwaysKeys: PAGE_ALWAYS }),
+    op$1("airingSchedules", AiringSchedulesQuery, {
+      fieldsEnabled: true,
+      alwaysKeys: PAGE_ALWAYS
+    }),
+    op$1("mediaTrends", MediaTrendsQuery, { fieldsEnabled: true, alwaysKeys: PAGE_ALWAYS }),
+    op$1("notifications", NotificationsQuery, { fieldsEnabled: true, alwaysKeys: PAGE_ALWAYS }),
+    op$1("followers", FollowersQuery, { fieldsEnabled: true, alwaysKeys: PAGE_ALWAYS }),
+    opAs("following", FollowingsQuery, "followings", {
+      fieldsEnabled: true,
+      alwaysKeys: PAGE_ALWAYS
+    }),
+    op$1("activities", ActivitiesQuery, { fieldsEnabled: true, alwaysKeys: PAGE_ALWAYS }),
+    opAs("activityReplies", ActivityRepliesQuery, "activityReplies", {
+      fieldsEnabled: true,
+      alwaysKeys: PAGE_ALWAYS
+    }),
+    op$1("threads", ThreadsQuery, { fieldsEnabled: true, alwaysKeys: PAGE_ALWAYS }),
+    opAs("threadComments", ThreadCommentsQuery, "threadComments", {
+      fieldsEnabled: true,
+      alwaysKeys: PAGE_ALWAYS
+    }),
+    op$1("reviews", ReviewsQuery, { fieldsEnabled: true, alwaysKeys: PAGE_ALWAYS }),
+    opAs("recommendations", RecommendationsQuery, "recommendations", {
+      fieldsEnabled: true,
+      alwaysKeys: PAGE_ALWAYS
+    }),
+    op$1("likes", LikesQuery, { fieldsEnabled: true, alwaysKeys: PAGE_ALWAYS })
   ],
   mutation: [
-    op("updateUser", UpdateUserMutation, { fieldsEnabled: true }),
-    op("saveMediaListEntry", SaveMediaListEntryMutation, { fieldsEnabled: true }),
-    op("updateMediaListEntries", UpdateMediaListEntriesMutation, { fieldsEnabled: true }),
-    op("deleteMediaListEntry", DeleteMediaListEntryMutation, { fieldsEnabled: true }),
-    op("deleteCustomList", DeleteCustomListMutation, { fieldsEnabled: true }),
-    op("saveTextActivity", SaveTextActivityMutation, { fieldsEnabled: true }),
-    op("saveMessageActivity", SaveMessageActivityMutation, { fieldsEnabled: true }),
-    op("saveListActivity", SaveListActivityMutation, { fieldsEnabled: true }),
-    op("deleteActivity", DeleteActivityMutation, { fieldsEnabled: true }),
-    op("toggleActivityPin", ToggleActivityPinMutation, { fieldsEnabled: true }),
-    op("toggleActivitySubscription", ToggleActivitySubscriptionMutation, {
+    op$1("updateUser", UpdateUserMutation, { fieldsEnabled: true }),
+    op$1("saveMediaListEntry", SaveMediaListEntryMutation, { fieldsEnabled: true }),
+    op$1("updateMediaListEntries", UpdateMediaListEntriesMutation, { fieldsEnabled: true }),
+    op$1("deleteMediaListEntry", DeleteMediaListEntryMutation, { fieldsEnabled: true }),
+    op$1("deleteCustomList", DeleteCustomListMutation, { fieldsEnabled: true }),
+    op$1("saveTextActivity", SaveTextActivityMutation, { fieldsEnabled: true }),
+    op$1("saveMessageActivity", SaveMessageActivityMutation, { fieldsEnabled: true }),
+    op$1("saveListActivity", SaveListActivityMutation, { fieldsEnabled: true }),
+    op$1("deleteActivity", DeleteActivityMutation, { fieldsEnabled: true }),
+    op$1("toggleActivityPin", ToggleActivityPinMutation, { fieldsEnabled: true }),
+    op$1("toggleActivitySubscription", ToggleActivitySubscriptionMutation, {
       fieldsEnabled: true
     }),
-    op("saveActivityReply", SaveActivityReplyMutation, { fieldsEnabled: true }),
-    op("deleteActivityReply", DeleteActivityReplyMutation, { fieldsEnabled: true }),
-    op("toggleLike", ToggleLikeMutation, { fieldsEnabled: true }),
-    op("toggleLikeV2", ToggleLikeV2Mutation, { fieldsEnabled: true }),
-    op("toggleFollow", ToggleFollowMutation, { fieldsEnabled: true }),
-    op("toggleFavourite", ToggleFavouriteMutation, { fieldsEnabled: true }),
-    op("updateFavouriteOrder", UpdateFavouriteOrderMutation, { fieldsEnabled: true }),
-    op("saveReview", SaveReviewMutation, { fieldsEnabled: true }),
-    op("rateReview", RateReviewMutation, { fieldsEnabled: true }),
-    op("deleteReview", DeleteReviewMutation, { fieldsEnabled: true }),
-    op("saveRecommendation", SaveRecommendationMutation, { fieldsEnabled: true }),
-    op("saveThread", SaveThreadMutation, { fieldsEnabled: true }),
-    op("deleteThread", DeleteThreadMutation, { fieldsEnabled: true }),
-    op("toggleThreadSubscription", ToggleThreadSubscriptionMutation, { fieldsEnabled: true }),
-    op("saveThreadComment", SaveThreadCommentMutation, { fieldsEnabled: true }),
-    op("deleteThreadComment", DeleteThreadCommentMutation, { fieldsEnabled: true }),
-    op("updateAniChartSettings", UpdateAniChartSettingsMutation),
-    op("updateAniChartHighlights", UpdateAniChartHighlightsMutation)
+    op$1("saveActivityReply", SaveActivityReplyMutation, { fieldsEnabled: true }),
+    op$1("deleteActivityReply", DeleteActivityReplyMutation, { fieldsEnabled: true }),
+    op$1("toggleLike", ToggleLikeMutation, { fieldsEnabled: true }),
+    op$1("toggleLikeV2", ToggleLikeV2Mutation, { fieldsEnabled: true }),
+    op$1("toggleFollow", ToggleFollowMutation, { fieldsEnabled: true }),
+    op$1("toggleFavourite", ToggleFavouriteMutation, { fieldsEnabled: true }),
+    op$1("updateFavouriteOrder", UpdateFavouriteOrderMutation, { fieldsEnabled: true }),
+    op$1("saveReview", SaveReviewMutation, { fieldsEnabled: true }),
+    op$1("rateReview", RateReviewMutation, { fieldsEnabled: true }),
+    op$1("deleteReview", DeleteReviewMutation, { fieldsEnabled: true }),
+    op$1("saveRecommendation", SaveRecommendationMutation, { fieldsEnabled: true }),
+    op$1("saveThread", SaveThreadMutation, { fieldsEnabled: true }),
+    op$1("deleteThread", DeleteThreadMutation, { fieldsEnabled: true }),
+    op$1("toggleThreadSubscription", ToggleThreadSubscriptionMutation, { fieldsEnabled: true }),
+    op$1("saveThreadComment", SaveThreadCommentMutation, { fieldsEnabled: true }),
+    op$1("deleteThreadComment", DeleteThreadCommentMutation, { fieldsEnabled: true }),
+    op$1("updateAniChartSettings", UpdateAniChartSettingsMutation),
+    op$1("updateAniChartHighlights", UpdateAniChartHighlightsMutation)
   ]
 };
 
+const sanitizeTokenError = (error, label) => {
+  if (error instanceof AniLinkRestError) {
+    const relabeled = new AniLinkRestError(error.status, error.data, void 0, {
+      rateLimit: error.rateLimit,
+      contentType: error.contentType,
+      requestId: error.requestId
+    });
+    if (error.rawAxiosError === void 0) {
+      relabeled.cause = error;
+    }
+    relabeled.message = `${label} failed with status ${error.status}.`;
+    return relabeled;
+  }
+  if (error instanceof AniLinkApiError) {
+    const relabeled = new AniLinkApiError(error.status, error.data, void 0, {
+      rateLimit: error.rateLimit,
+      contentType: error.contentType,
+      requestId: error.requestId
+    });
+    if (error.rawAxiosError === void 0) {
+      relabeled.cause = error;
+    }
+    relabeled.message = `${label} failed with status ${error.status}.`;
+    return relabeled;
+  }
+  if (error instanceof AniLinkError) {
+    return error;
+  }
+  if (axios.isCancel(error)) {
+    return new AniLinkNetworkError(AniLinkErrorCodes.ABORTED, `${label} was cancelled.`);
+  }
+  if (axios.isAxiosError(error)) {
+    if (error.response?.status !== void 0) {
+      const status = error.response.status;
+      const apiError = new AniLinkApiError(status, error.response.data);
+      apiError.message = `${label} failed with status ${status}.`;
+      return apiError;
+    }
+    if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
+      return new AniLinkNetworkError(AniLinkErrorCodes.TIMEOUT, `${label} timed out.`);
+    }
+    return new AniLinkNetworkError(
+      AniLinkErrorCodes.NETWORK,
+      `${label} failed due to a network error.`
+    );
+  }
+  return new AniLinkError(`${label} failed.`, AniLinkErrorCodes.UNKNOWN);
+};
+
+const TOKEN_REQUEST_TIMEOUT_MS = 1e4;
+const requestTokenGrant = async (descriptor, params, signal, options) => {
+  try {
+    const body = new URLSearchParams(params).toString();
+    return await sendRequest(descriptor.tokenUrl, "POST", body, void 0, {
+      requiresAuth: false,
+      options: {
+        ...options,
+        timeout: options?.timeout ?? TOKEN_REQUEST_TIMEOUT_MS,
+        retry: options?.retry ?? false,
+        signal: signal ?? options?.signal,
+        // Never honor a caller's exposeRawAxiosError here: the
+        // grant body carries client secrets and one-time codes.
+        exposeRawAxiosError: false
+      },
+      contentType: "application/x-www-form-urlencoded"
+    });
+  } catch (error) {
+    throw sanitizeTokenError(error, descriptor.errorLabel);
+  }
+};
+const refreshGrantParams = (clientId, clientSecret, refreshToken) => ({
+  grant_type: "refresh_token",
+  client_id: clientId,
+  ...clientSecret !== void 0 ? { client_secret: clientSecret } : {},
+  refresh_token: refreshToken
+});
+const computeTokenExpiry = (response, now = Date.now()) => {
+  const { expires_in } = response;
+  if (!Number.isFinite(expires_in) || expires_in <= 0) {
+    throw new TypeError(
+      `Invalid expires_in ${expires_in}: token lifetime must be a finite, positive number of seconds.`
+    );
+  }
+  return new Date(now + expires_in * 1e3);
+};
+const rewriteAuth = (descriptor, auth, accessToken) => {
+  const headers = typeof auth === "object" && auth?.headers !== void 0 ? Object.fromEntries(
+    Object.entries(auth.headers).filter(
+      ([key]) => !descriptor.stripHeaders.includes(key)
+    )
+  ) : void 0;
+  return {
+    token: accessToken,
+    headers: headers !== void 0 && Object.keys(headers).length > 0 ? headers : void 0
+  };
+};
 class TokenRefresher {
-  exchange;
+  descriptor;
+  clientId;
+  clientSecret;
   refreshToken;
-  provider;
   onTokenRefresh;
   onTokenRefreshError;
   onHookError;
@@ -8338,13 +9137,14 @@ class TokenRefresher {
   /**
    * Constructs a refresh coordinator from the wiring's fields.
    *
-   * @param options - The exchange adapter, the stored refresh token, the diagnostics names, the auth-swap callback, the optional persistence and failure callbacks, and the diagnostics mode.
+   * @param options - The provider descriptor, the client credentials, the stored refresh token, the diagnostics names, the auth-swap callback, the optional persistence and failure callbacks, and the diagnostics mode.
    * @throws A `TypeError` when `options.diagnostics` is defined but not one of `"warn"`, `"hook"`, or `"silent"`.
    */
   constructor(options) {
-    this.exchange = options.exchange;
+    this.descriptor = options.descriptor;
+    this.clientId = options.clientId;
+    this.clientSecret = options.clientSecret;
     this.refreshToken = options.refreshToken;
-    this.provider = options.provider;
     this.onTokenRefresh = options.onTokenRefresh;
     this.onTokenRefreshError = options.onTokenRefreshError;
     this.onHookError = options.onHookError;
@@ -8354,13 +9154,13 @@ class TokenRefresher {
   /**
    * Runs one operation attempt under the automatic refresh lifecycle.
    *
-   * A 401 from the first attempt — or an {@link AniLinkAuthError} raised
+   * A 401 from the first attempt, or an {@link AniLinkAuthError} raised
    * before any request because no access token is configured, which lets
-   * a persisted refresh token bootstrap the client — triggers exactly one
+   * a persisted refresh token bootstrap the client, triggers exactly one
    * refresh (concurrent failures share the in-flight refresh) followed by
-   * a single replay with the new auth material. Any other failure — a
-   * non-401 first attempt, a failed refresh, or a replay that fails again
-   * — surfaces unchanged. A failed refresh grant is reported to
+   * a single replay with the new auth material. Any other failure, a
+   * non-401 first attempt, a failed refresh, or a replay that fails again,
+   * surfaces unchanged. A failed refresh grant is reported to
    * `onHookError` (under the coordinator's `hookName`) before the
    * sanitized error rethrows, so the grant failure is observable through
    * the same channel as every other lifecycle failure. The
@@ -8385,8 +9185,8 @@ class TokenRefresher {
       } catch (refreshError) {
         reportDiagnostic({
           kind: "token-refresh",
-          hookName: this.provider.hookName,
-          message: `The ${this.provider.providerLabel} token refresh failed: ${refreshError instanceof Error ? refreshError.message : String(refreshError)}`,
+          hookName: this.descriptor.provider.hookName,
+          message: `The ${this.descriptor.provider.providerLabel} token refresh failed: ${refreshError instanceof Error ? refreshError.message : String(refreshError)}`,
           onHookError: this.onHookError,
           diagnostics: this.diagnostics,
           rawError: refreshError,
@@ -8405,7 +9205,7 @@ class TokenRefresher {
    *
    * The auth swap and the callback run inside the shared in-flight promise
    * so concurrent 401s observe one grant, one swap, and one callback
-   * invocation — and so the swap always lands in grant order.
+   * invocation, and so the swap always lands in grant order.
    *
    * @returns The effective token response, with `refresh_token` filled in when the provider omitted it.
    */
@@ -8437,69 +9237,29 @@ class TokenRefresher {
     return await this.refreshInFlight;
   }
   /**
-   * Runs the refresh grant and stores the rotated refresh token.
+   * Runs the refresh grant against the descriptor's token endpoint and
+   * stores the rotated refresh token.
    *
    * @returns The effective token response.
    */
   async performRefresh() {
-    const response = await this.exchange(this.refreshToken);
+    const response = await requestTokenGrant(
+      this.descriptor,
+      refreshGrantParams(this.clientId, this.clientSecret, this.refreshToken)
+    );
     this.refreshToken = response.refresh_token ?? this.refreshToken;
     return { ...response, refresh_token: this.refreshToken };
   }
 }
 
-const sanitizeTokenError = (error, label) => {
-  if (error instanceof AniLinkRestError) {
-    const relabeled = new AniLinkRestError(error.status, error.data, void 0, {
-      rateLimit: error.rateLimit,
-      contentType: error.contentType,
-      requestId: error.requestId
-    });
-    if (error.rawAxiosError === void 0) {
-      relabeled.cause = error;
-    }
-    relabeled.message = `${label} failed with status ${error.status}.`;
-    return relabeled;
-  }
-  if (error instanceof AniLinkApiError) {
-    const relabeled = new AniLinkApiError(error.status, error.data, void 0, {
-      rateLimit: error.rateLimit,
-      contentType: error.contentType,
-      requestId: error.requestId
-    });
-    if (error.rawAxiosError === void 0) {
-      relabeled.cause = error;
-    }
-    relabeled.message = `${label} failed with status ${error.status}.`;
-    return relabeled;
-  }
-  if (error instanceof AniLinkError) {
-    return error;
-  }
-  if (axios.isCancel(error)) {
-    return new AniLinkNetworkError(AniLinkErrorCodes.ABORTED, `${label} was cancelled.`);
-  }
-  if (axios.isAxiosError(error)) {
-    if (error.response?.status !== void 0) {
-      const status = error.response.status;
-      const apiError = new AniLinkApiError(status, error.response.data);
-      apiError.message = `${label} failed with status ${status}.`;
-      return apiError;
-    }
-    if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
-      return new AniLinkNetworkError(AniLinkErrorCodes.TIMEOUT, `${label} timed out.`);
-    }
-    return new AniLinkNetworkError(
-      AniLinkErrorCodes.NETWORK,
-      `${label} failed due to a network error.`
-    );
-  }
-  return new AniLinkError(`${label} failed.`, AniLinkErrorCodes.UNKNOWN);
-};
-
-const AUTH_TOKEN_TIMEOUT_MS = 1e4;
 const ANILIST_TOKEN_URL = "https://anilist.co/api/v2/oauth/token";
 const ANILIST_AUTHORIZE_URL = "https://anilist.co/api/v2/oauth/authorize";
+const ANILIST_TOKEN_GRANT = {
+  tokenUrl: ANILIST_TOKEN_URL,
+  errorLabel: "AniList token request",
+  stripHeaders: [],
+  provider: { hookName: "aniListTokenRefresh", providerLabel: "AniList" }
+};
 const buildAuthorizationUrl = (clientId, redirectUri, state) => {
   let url = `${ANILIST_AUTHORIZE_URL}?client_id=${encodeURIComponent(
     clientId
@@ -8509,29 +9269,8 @@ const buildAuthorizationUrl = (clientId, redirectUri, state) => {
   }
   return url;
 };
-const normalizeTokenRequestError = (error) => sanitizeTokenError(error, "AniList token request");
-const requestToken = async (params, signal, options) => {
-  const mergedOptions = {
-    ...options,
-    timeout: options?.timeout ?? AUTH_TOKEN_TIMEOUT_MS,
-    retry: options?.retry ?? false,
-    signal: signal ?? options?.signal,
-    // Never honor a caller's exposeRawAxiosError here: the token request
-    // body carries the client secret and grant credentials.
-    exposeRawAxiosError: false
-  };
-  try {
-    const body = new URLSearchParams(params).toString();
-    return await sendRequest(ANILIST_TOKEN_URL, "POST", body, void 0, {
-      requiresAuth: false,
-      options: mergedOptions,
-      contentType: "application/x-www-form-urlencoded"
-    });
-  } catch (error) {
-    throw normalizeTokenRequestError(error);
-  }
-};
-const getAccessToken = async (clientId, clientSecret, code, redirectUri, signal, options) => requestToken(
+const getAccessToken = async (clientId, clientSecret, code, redirectUri, signal, options) => requestTokenGrant(
+  ANILIST_TOKEN_GRANT,
   {
     grant_type: "authorization_code",
     client_id: clientId,
@@ -8547,46 +9286,19 @@ const getAccessToken = async (clientId, clientSecret, code, redirectUri, signal,
   signal,
   options
 );
-const refreshAccessToken = async (clientId, clientSecret, refreshToken, signal, options) => requestToken(
-  {
-    grant_type: "refresh_token",
-    client_id: clientId,
-    client_secret: clientSecret,
-    refresh_token: refreshToken
-  },
+const refreshAccessToken = async (clientId, clientSecret, refreshToken, signal, options) => requestTokenGrant(
+  ANILIST_TOKEN_GRANT,
+  refreshGrantParams(clientId, clientSecret, refreshToken),
   signal,
   options
 );
-const getTokenExpiry = (response, now = Date.now()) => {
-  const { expires_in } = response;
-  if (!Number.isFinite(expires_in) || expires_in <= 0) {
-    throw new TypeError(
-      `Invalid expires_in ${expires_in}: token lifetime must be a finite, positive number of seconds.`
-    );
-  }
-  return new Date(now + expires_in * 1e3);
-};
+const getTokenExpiry = (response, now) => computeTokenExpiry(response, now);
 
-const buildAniListTokenRefresher = (options) => {
-  const exchange = (refreshToken) => refreshAccessToken(options.clientId, options.clientSecret, refreshToken);
-  return new TokenRefresher({
-    exchange,
-    refreshToken: options.refreshToken,
-    provider: { hookName: "aniListTokenRefresh", providerLabel: "AniList" },
-    onTokenRefresh: options.onTokenRefresh,
-    onTokenRefreshError: options.onTokenRefreshError,
-    onHookError: options.onHookError,
-    diagnostics: options.diagnostics,
-    applyAccessToken: options.applyAccessToken
-  });
-};
-const buildRefreshedAuth$1 = (auth, accessToken) => {
-  const headers = typeof auth === "object" && auth?.headers !== void 0 ? Object.fromEntries(Object.entries(auth.headers)) : void 0;
-  return {
-    token: accessToken,
-    headers: headers !== void 0 && Object.keys(headers).length > 0 ? headers : void 0
-  };
-};
+const buildAniListTokenRefresher = (options) => new TokenRefresher({
+  descriptor: ANILIST_TOKEN_GRANT,
+  ...options
+});
+const buildRefreshedAuth$1 = (auth, accessToken) => rewriteAuth(ANILIST_TOKEN_GRANT, auth, accessToken);
 
 function validateCategoryMethods(category) {
   for (const entry of ANILIST_OPERATION_REGISTRY[category]) {
@@ -8684,6 +9396,15 @@ function buildAniListWiring(authToken, options, stateOwner, credentials) {
     writable: false
   });
   let customBound;
+  let customPageBound;
+  const page = pageFacade;
+  const notificationsFetch = (variables, options2) => page.notifications(variables, options2);
+  const activitiesFetch = (variables, options2) => page.activities(variables, options2);
+  const watchFacade = {
+    notifications: (watchOptions) => watchNotifications(notificationsFetch, watchOptions),
+    activity: (watchOptions) => watchActivity(activitiesFetch, watchOptions)
+  };
+  const mapExternalIdsFacade = buildMapExternalIdsFacade(options, sharedStateOwner);
   return Object.defineProperties(
     {
       query: queryFacade,
@@ -8694,7 +9415,9 @@ function buildAniListWiring(authToken, options, stateOwner, credentials) {
       fuzzyDate,
       fuzzyDateInt,
       flattenMediaListCollection,
-      crossLink
+      crossLink,
+      mapExternalIds: mapExternalIdsFacade,
+      watch: watchFacade
     },
     {
       custom: {
@@ -8712,6 +9435,24 @@ function buildAniListWiring(authToken, options, stateOwner, credentials) {
           }
           return customBound;
         }
+      },
+      customPage: {
+        enumerable: true,
+        configurable: false,
+        get() {
+          if (customPageBound === void 0) {
+            const customPageInstance = new CustomRequest(
+              getAuth(),
+              options,
+              sharedStateOwner
+            );
+            trackOperation?.(customPageInstance);
+            customPageBound = maybeWrap(
+              customPageInstance.customPage.bind(customPageInstance)
+            );
+          }
+          return customPageBound;
+        }
       }
     }
   );
@@ -8721,6 +9462,162 @@ function buildAniListApi(authToken, options, stateOwner, credentials) {
   return buildAniListWiring(authToken, options, stateOwner, credentials);
 }
 
+const MAL_API_BASE_URL = "https://api.myanimelist.net/v2";
+const MAL_AUTHORIZE_URL = "https://myanimelist.net/v1/oauth2/authorize";
+const MAL_TOKEN_URL = "https://myanimelist.net/v1/oauth2/token";
+const MAL_API_REFERENCE = "https://myanimelist.net/apiconfig/references/api/v2";
+const DEFAULT_MAL_ANIME_FIELD_KEYS = {
+  id: true,
+  title: true,
+  main_picture: true,
+  synopsis: true,
+  status: true,
+  mean: true,
+  num_episodes: true,
+  media_type: true,
+  start_date: true,
+  broadcast: true,
+  average_episode_duration: true
+};
+const DEFAULT_MAL_ANIME_FIELDS = Object.keys(
+  DEFAULT_MAL_ANIME_FIELD_KEYS
+);
+const formatMalFields = (fields) => typeof fields === "string" ? fields : fields?.join(",");
+
+const MAL_TOKEN_GRANT = {
+  tokenUrl: MAL_TOKEN_URL,
+  errorLabel: "MAL token request",
+  stripHeaders: ["X-MAL-CLIENT-ID"],
+  provider: { hookName: "malTokenRefresh", providerLabel: "MAL" }
+};
+const validateMalPkceValue = (value, name) => {
+  if (!/^[-A-Za-z0-9._~]{43,128}$/.test(value)) {
+    throw new TypeError(`${name} must contain 43 to 128 RFC 7636 unreserved characters.`);
+  }
+};
+const buildMalAuthorizationUrl = (clientId, codeChallenge, state) => {
+  validateMalPkceValue(codeChallenge, "codeChallenge");
+  const params = new URLSearchParams({
+    response_type: "code",
+    client_id: clientId,
+    code_challenge: codeChallenge,
+    code_challenge_method: "plain"
+  });
+  if (state !== void 0) params.set("state", state);
+  return `${MAL_AUTHORIZE_URL}?${params.toString().replaceAll("+", "%20")}`;
+};
+const getMalAccessToken = async (request) => {
+  validateMalPkceValue(request.codeVerifier, "codeVerifier");
+  return requestTokenGrant(
+    MAL_TOKEN_GRANT,
+    {
+      client_id: request.clientId,
+      code: request.code,
+      code_verifier: request.codeVerifier,
+      grant_type: "authorization_code",
+      ...request.clientSecret === void 0 ? {} : { client_secret: request.clientSecret }
+    },
+    void 0,
+    request.options
+  );
+};
+const refreshMalAccessToken = (request) => requestTokenGrant(
+  MAL_TOKEN_GRANT,
+  refreshGrantParams(request.clientId, request.clientSecret, request.refreshToken),
+  void 0,
+  request.options
+);
+const getMalTokenExpiry = (response, now) => computeTokenExpiry(response, now);
+
+const MAX_PER_PAGE = 100;
+const DEFAULT_PER_PAGE = MAX_PER_PAGE;
+const DEFAULT_MAX_PAGES = 100;
+const DEFAULT_CONCURRENCY = 1;
+const MAL_DEFAULTS = {
+  naming: "page",
+  maxPerEntry: MAX_PER_PAGE,
+  defaultPerEntry: DEFAULT_PER_PAGE,
+  defaultMaxEntries: DEFAULT_MAX_PAGES,
+  defaultConcurrency: DEFAULT_CONCURRENCY
+};
+const safeCallback = (callback, name, onHookError, diagnostics, payload) => {
+  safeInvoke(callback, name, onHookError, diagnostics, payload);
+};
+function extractHasMore(response, perPage) {
+  if (!Array.isArray(response.data)) {
+    return false;
+  }
+  if (typeof response.paging === "object" && response.paging !== null) {
+    return response.paging.next != null;
+  }
+  return response.data.length >= perPage;
+}
+async function malPaginate(fetchPage, options) {
+  const {
+    perEntry: perPage,
+    startEntry: startPage,
+    maxEntries: maxPages,
+    concurrency,
+    diagnostics
+  } = resolvePaginationOptions(options, MAL_DEFAULTS);
+  const { signal, dispose } = bridgeAbortSignal(options?.signal);
+  try {
+    const { responses, count, truncated } = await fetchWithLookAhead(
+      (page) => fetchPage(page, perPage, signal),
+      (response) => extractHasMore(response, perPage),
+      startPage,
+      maxPages,
+      concurrency,
+      signal
+    );
+    const items = [];
+    const pages = [];
+    for (const response of responses) {
+      const raw = response.data;
+      if (raw === void 0) {
+        throw new AniLinkValidationError([
+          'malPaginate: the page response has no "data" key. Check the fetchPage closure returns the raw MAL list response.'
+        ]);
+      }
+      const pageItems = Array.isArray(raw) ? raw : [];
+      pages.push({ paging: response.paging, items: pageItems });
+      items.push(...pageItems);
+      safeCallback(options?.onPage, "onPage", options?.onHookError, diagnostics, {
+        paging: response.paging,
+        items: pageItems
+      });
+    }
+    return { items, pages, pageCount: count, truncated };
+  } finally {
+    dispose();
+  }
+}
+async function* malPaginatePages(fetchPage, options) {
+  const {
+    perEntry: perPage,
+    startEntry: startPage,
+    maxEntries: maxPages,
+    concurrency,
+    diagnostics
+  } = resolvePaginationOptions(options, MAL_DEFAULTS);
+  for await (const response of streamNumericPages(
+    fetchPage,
+    // Invert {@link extractHasMore} so both traversal helpers use the
+    // same terminal condition. Malformed `data` ends traversal in every
+    // branch. When present, MAL's `paging` node is authoritative. A
+    // missing `next` URL ends traversal even on a full page. Without a
+    // `paging` node, a short page ends traversal.
+    (page) => !extractHasMore(page, perPage),
+    { perPage, startPage, maxPages, concurrency, signal: options?.signal }
+  )) {
+    safeCallback(options?.onPage, "onPage", options?.onHookError, diagnostics, {
+      paging: response.paging,
+      items: Array.isArray(response.data) ? response.data : []
+    });
+    yield response;
+  }
+}
+
 const buildQueryString = (params) => {
   const segments = [];
   for (const [key, value] of Object.entries(params)) {
@@ -8748,16 +9645,17 @@ class RestOperation extends BaseOperation {
   /**
    * Sends one REST call through the shared transport pipeline.
    *
-   * GET and DELETE calls pass their parameters as a query string; POST, PUT,
-   * and PATCH calls send them as a JSON body. Responses are returned verbatim
-   * — REST providers have no GraphQL-style envelope, so no unwrapping
-   * happens.
+   * GET and DELETE calls pass parameters as a query string. POST, PUT, and
+   * PATCH calls send them as a JSON body. `execute` returns response bodies
+   * verbatim because REST providers have no GraphQL-style envelope to unwrap.
    *
    * @typeParam T - The expected parsed response body.
    * @param path - The endpoint path beginning with `/` (for example `/anime/{id}`); placeholders are substituted from `pathParams` before interpolation into the URL.
    * @param options - The declarative request contract: method, auth requirement, content type, query/body/pathParams, and per-request transport settings.
    * @returns The parsed response body as-is.
-   * @throws An {@link AniLinkAuthError} when `requiresAuth` is true and no token is set, an {@link AniLinkValidationError} when a `{placeholder}` in `path` has no matching `pathParams` entry, or a normalized {@link AniLinkError} (typically `AniLinkRestError`) when the request fails.
+   * @throws An {@link AniLinkAuthError} when `requiresAuth` is true and no token is set.
+   * @throws An {@link AniLinkValidationError} when a `{placeholder}` in `path` has no matching `pathParams` entry.
+   * @throws A normalized {@link AniLinkError} (typically `AniLinkRestError`) when the request fails.
    */
   async execute(path, options = {}) {
     const {
@@ -8793,25 +9691,6 @@ class RestOperation extends BaseOperation {
   }
 }
 
-const MAL_API_BASE_URL = "https://api.myanimelist.net/v2";
-const MAL_AUTHORIZE_URL = "https://myanimelist.net/v1/oauth2/authorize";
-const MAL_TOKEN_URL = "https://myanimelist.net/v1/oauth2/token";
-const MAL_API_REFERENCE = "https://myanimelist.net/apiconfig/references/api/v2";
-const DEFAULT_MAL_ANIME_FIELDS = [
-  "id",
-  "title",
-  "main_picture",
-  "synopsis",
-  "status",
-  "mean",
-  "num_episodes",
-  "media_type",
-  "start_date",
-  "broadcast",
-  "average_episode_duration"
-];
-const formatMalFields = (fields) => typeof fields === "string" ? fields : fields?.join(",");
-
 class MalAnimeOperation extends RestOperation {
   /** The base URL for MyAnimeList API v2, from {@link MAL_API_BASE_URL}. */
   baseUrl = MAL_API_BASE_URL;
@@ -8824,8 +9703,6 @@ class MalAnimeOperation extends RestOperation {
     "status",
     "num_watched_episodes",
     "score",
-    "start_date",
-    "finish_date",
     "comments",
     "is_rewatching",
     "num_times_rewatched",
@@ -8865,8 +9742,9 @@ class MalAnimeOperation extends RestOperation {
    * It calls `GET /anime` through `RestOperation.execute` with the `q` keyword
    * plus the `limit`/`offset` paging filters and returns a
    * {@link MalAnimeSearchResponse} page of `MalAnimeSearchEntry` entries
-   * shaped by {@link MalRequestOptions.fields}. The facade alias is
-   * `MyAnimeListAnimeApi.search` and it is a public read.
+   * shaped by {@link MalRequestOptions.fields}. The facade exposes this
+   * method as `MyAnimeListAnimeApi.search`. It does not require an access
+   * token.
    *
    * @param params - The search inputs; a {@link MalAnimeSearchParams} carrying the keyword plus the optional paging filters.
    * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
@@ -8905,7 +9783,11 @@ class MalAnimeOperation extends RestOperation {
   /**
    * {@link MalAnimeOperation.seasonal} gets the anime of one broadcast season.
    *
-   * It calls `GET /anime/season/{year}/{season}` through `RestOperation.execute` and returns a {@link MalSeasonalAnimeResponse} page of `MalSeasonalAnime` entries shaped by {@link MalRequestOptions.fields}. The facade alias is `MyAnimeListAnimeApi.seasonal` and it is a public read.
+   * It calls `GET /anime/season/{year}/{season}` through
+   * `RestOperation.execute` and returns a {@link MalSeasonalAnimeResponse} page
+   * of `MalSeasonalAnime` entries shaped by {@link MalRequestOptions.fields}.
+   * The facade exposes this method as `MyAnimeListAnimeApi.seasonal`. It does
+   * not require an access token.
    *
    * @param params - The seasonal read inputs; a {@link MalSeasonalParams} carrying the year and broadcast window.
    * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
@@ -8936,7 +9818,11 @@ class MalAnimeOperation extends RestOperation {
   /**
    * {@link MalAnimeOperation.ranking} gets one of MyAnimeList's anime ranking lists.
    *
-   * It calls `GET /anime/ranking` through `RestOperation.execute` with the `ranking_type` query parameter and returns a {@link MalAnimeRankingResponse} page of `MalRankingEntry` entries shaped by {@link MalRequestOptions.fields}. The facade alias is `MyAnimeListAnimeApi.ranking` and it is a public read.
+   * It calls `GET /anime/ranking` through `RestOperation.execute` with the
+   * `ranking_type` query parameter and returns a {@link MalAnimeRankingResponse}
+   * page of `MalRankingEntry` entries shaped by {@link MalRequestOptions.fields}.
+   * The facade exposes this method as `MyAnimeListAnimeApi.ranking`. It does
+   * not require an access token.
    *
    * @param params - The ranking read inputs; a {@link MalRankingParams} carrying the ranking list to fetch.
    * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
@@ -8999,11 +9885,11 @@ class MalAnimeOperation extends RestOperation {
    * MAL's list-status endpoints require.
    *
    * MAL documents `PATCH /anime/{id}/my_list_status` with an
-   * `application/x-www-form-urlencoded` request body, not JSON. Only the
-   * known list-status fields are encoded — excess properties from
-   * JavaScript callers (typos like `num_watched_episode`) are dropped
-   * instead of being sent to MAL as silent no-op fields. Array values
-   * (`tags`) are joined into the comma-separated string MAL expects.
+   * `application/x-www-form-urlencoded` request body, not JSON. The encoder
+   * includes only known list-status fields. It drops extra JavaScript
+   * properties, such as the typo `num_watched_episode`, rather than sending
+   * fields MAL would ignore. It joins array values (`tags`) into the
+   * comma-separated string MAL expects.
    *
    * @param payload - The list-status fields to update.
    * @returns The encoded body string, safe to pass as the request `data`.
@@ -9100,9 +9986,10 @@ class MalForumOperation extends RestOperation {
    * {@link MalForumOperation.boards} gets the MyAnimeList forum board tree.
    *
    * It calls `GET /forum/boards` through `RestOperation.execute` and returns
-   * a {@link MalForumBoardsResponse} of {@link MalForumCategory} entries,
-   * each carrying its {@link MalForumBoard} and subboards. The facade alias
-   * is `MyAnimeListForumApi.boards` and it is a public read.
+   * a {@link MalForumBoardsResponse} containing {@link MalForumCategory}
+   * entries, each with {@link MalForumBoard} entries and subboards. The
+   * facade exposes this method as `MyAnimeListForumApi.boards`. It does not
+   * require an access token.
    *
    * @param options - Optional transport settings; a {@link MalRequestOptions} merged over the instance defaults.
    * @returns The forum board tree, a {@link MalForumBoardsResponse}.
@@ -9129,8 +10016,8 @@ class MalForumOperation extends RestOperation {
    * `topic_user_name`/`user_name` creator filters, and the `sort` and
    * `limit`/`offset` paging filters, returning a
    * {@link MalForumTopicsResponse} page of {@link MalForumTopicSummary}
-   * entries. The facade alias is `MyAnimeListForumApi.topics` and it is a
-   * public read.
+   * entries. The facade exposes this method as `MyAnimeListForumApi.topics`.
+   * It does not require an access token.
    *
    * @param params - The topic-list read inputs; a {@link MalForumTopicsParams} carrying the optional board, keyword, creator, sort, and paging filters.
    * @param options - Optional transport settings; a {@link MalRequestOptions} merged over the instance defaults.
@@ -9169,8 +10056,9 @@ class MalForumOperation extends RestOperation {
    * It calls `GET /forum/topic/{id}` through `RestOperation.execute` with
    * the `limit`/`offset` post-paging filters and returns a
    * {@link MalForumTopicResponse} whose `data` carries the topic's
-   * {@link MalForumTopicDetail} — title, posts, and poll. The facade alias
-   * is `MyAnimeListForumApi.topic` and it is a public read.
+   * {@link MalForumTopicDetail}, which contains the title, posts, and poll.
+   * The facade exposes this method as `MyAnimeListForumApi.topic`. It does
+   * not require an access token.
    *
    * @param params - The topic read inputs; a {@link MalForumTopicParams} carrying the topic ID plus the optional post-paging filters.
    * @param options - Optional transport settings; a {@link MalRequestOptions} merged over the instance defaults.
@@ -9210,8 +10098,6 @@ class MalMangaOperation extends RestOperation {
     "num_chapters_read",
     "num_volumes_read",
     "score",
-    "start_date",
-    "finish_date",
     "comments",
     "is_rereading",
     "num_times_reread",
@@ -9252,8 +10138,9 @@ class MalMangaOperation extends RestOperation {
    * It calls `GET /manga` through `RestOperation.execute` with the `q` keyword
    * plus the `limit`/`offset` paging filters and returns a
    * {@link MalMangaSearchResponse} page of `MalMangaSearchEntry` entries
-   * shaped by {@link MalRequestOptions.fields}. The facade alias is
-   * `MyAnimeListMangaApi.search` and it is a public read.
+   * shaped by {@link MalRequestOptions.fields}. The facade exposes this
+   * method as `MyAnimeListMangaApi.search`. It does not require an access
+   * token.
    *
    * @param params - The search inputs; a {@link MalMangaSearchParams} carrying the keyword plus the optional paging filters.
    * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
@@ -9295,8 +10182,8 @@ class MalMangaOperation extends RestOperation {
    * It calls `GET /manga/ranking` through `RestOperation.execute` with the
    * `ranking_type` query parameter and returns a {@link MalMangaRankingResponse}
    * page of `MalMangaRankingEntry` entries shaped by
-   * {@link MalRequestOptions.fields}. The facade alias is
-   * `MyAnimeListMangaApi.ranking` and it is a public read.
+   * {@link MalRequestOptions.fields}. The facade exposes this method as
+   * `MyAnimeListMangaApi.ranking`. It does not require an access token.
    *
    * @param params - The ranking read inputs; a {@link MalMangaRankingParams} carrying the ranking list to fetch.
    * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
@@ -9331,11 +10218,11 @@ class MalMangaOperation extends RestOperation {
    * MAL's list-status endpoints require.
    *
    * MAL documents `PATCH /manga/{id}/my_list_status` with an
-   * `application/x-www-form-urlencoded` request body, not JSON. Only the
-   * known list-status fields are encoded — excess properties from
-   * JavaScript callers (typos like `num_chapter_read`) are dropped
-   * instead of being sent to MAL as silent no-op fields. Array values
-   * (`tags`) are joined into the comma-separated string MAL expects.
+   * `application/x-www-form-urlencoded` request body, not JSON. The encoder
+   * includes only known list-status fields. It drops extra JavaScript
+   * properties, such as the typo `num_chapter_read`, rather than sending
+   * fields MAL would ignore. It joins array values (`tags`) into the
+   * comma-separated string MAL expects.
    *
    * @param payload - The list-status fields to update.
    * @returns The encoded body string, safe to pass as the request `data`.
@@ -9429,17 +10316,17 @@ class MalUserOperation extends RestOperation {
   /** The base URL for MyAnimeList API v2, from {@link MAL_API_BASE_URL}. */
   baseUrl = MAL_API_BASE_URL;
   /**
-   * Normalizes a `username` argument for the `@me` check: trimmed and
-   * lowercased, so `@ME` and `" @me "` resolve the authenticated user too.
+   * Normalizes a `username` argument for the `@me` check by trimming and
+   * lowercasing it, so `@ME` and `" @me "` resolve the authenticated user too.
    */
   static normalizeUsername(username) {
     return username.trim().toLowerCase();
   }
   /**
    * Validates a normalized username before it is interpolated into a URL
-   * path: an empty string would produce a malformed `/users//animelist`
-   * path, so it fails fast with a clear client-side message instead of a
-   * confusing upstream 404 or URL-parse error.
+   * path. An empty string would produce a malformed `/users//animelist`
+   * path, so it fails fast with a clear client-side message instead of an
+   * upstream 404 or URL-parse error.
    *
    * @param normalized - The trimmed, lowercased username.
    * @throws An {@link AniLinkValidationError} when the username is empty.
@@ -9488,7 +10375,7 @@ class MalUserOperation extends RestOperation {
    * @param params - The profile read inputs; a {@link MalUserGetParams} carrying the username.
    * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
    * @returns The requested {@link MalUser}.
-   * @throws An `AniLinkAuthError` when `username` is `@me` and no access token is configured.
+   * @throws An `AniLinkAuthError` when no access token is configured.
    * @throws An {@link AniLinkValidationError} when `username` is empty or only whitespace.
    * @throws A normalized `AniLinkError` when the request fails.
    * @example
@@ -9510,17 +10397,17 @@ class MalUserOperation extends RestOperation {
     return await this.execute(
       normalized === "@me" ? "/users/@me" : "/users/{username}",
       {
-        // `@me` resolves the authenticated user, which only a bearer
-        // token can identify — a client ID alone cannot — so fail fast
-        // like `me`.
-        requiresAuth: normalized === "@me",
+        // Only a bearer token can identify the authenticated user at
+        // `@me`; a client ID alone cannot. Reject the request early,
+        // as `me` does.
+        requiresAuth: true,
         transportOptions,
         // `buildQueryString` skips undefined/null values, so the
         // optional filters can be passed straight through.
         query: {
           fields: formatMalFields(fields)
         },
-        // The trimmed username, not the raw argument: surrounding
+        // The trimmed username, not the raw argument. Surrounding
         // whitespace would otherwise be percent-encoded into the
         // path and answered with a 404.
         pathParams: normalized === "@me" ? void 0 : { username: normalized }
@@ -9530,7 +10417,13 @@ class MalUserOperation extends RestOperation {
   /**
    * {@link MalUserOperation.animeList} gets a user's anime list, one page at a time.
    *
-   * It calls `GET /users/{username}/animelist` through `RestOperation.execute` and returns a {@link MalUserAnimeListResponse} page of `MalUserAnimeListEntry` entries shaped by {@link MalRequestOptions.fields}. The facade alias is `MyAnimeListUserApi.animeList` and it is a public read: `username` accepts a user name or `@me`, with `@me` and private lists requiring an access token (a client ID alone cannot resolve `@me`). The `@me` check is case-insensitive and ignores surrounding whitespace.
+   * It calls `GET /users/{username}/animelist` through
+   * `RestOperation.execute` and returns a {@link MalUserAnimeListResponse}
+   * page of `MalUserAnimeListEntry` entries shaped by
+   * {@link MalRequestOptions.fields}. The facade exposes this method as
+   * `MyAnimeListUserApi.animeList`. `username` accepts a user name or `@me`;
+   * `@me` and private lists require an access token. The `@me` check ignores
+   * case and surrounding whitespace.
    *
    * @param params - The anime-list read inputs; a {@link MalUserAnimeListParams} carrying the username plus the optional status, sort, and paging filters.
    * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
@@ -9557,8 +10450,8 @@ class MalUserOperation extends RestOperation {
     return await this.execute(
       normalized === "@me" ? "/users/@me/animelist" : "/users/{username}/animelist",
       {
-        // `@me` resolves the authenticated user, which only a bearer token
-        // can identify — a client ID alone cannot — so fail fast like `me`.
+        // Only a bearer token can identify the authenticated user at
+        // `@me`; a client ID alone cannot. Require one, as `me` does.
         requiresAuth: normalized === "@me",
         transportOptions,
         // `buildQueryString` skips undefined/null values, so the
@@ -9570,7 +10463,7 @@ class MalUserOperation extends RestOperation {
           limit,
           offset
         },
-        // The trimmed username, not the raw argument: surrounding
+        // The trimmed username, not the raw argument. Surrounding
         // whitespace would otherwise be percent-encoded into the
         // path and answered with a 404.
         pathParams: normalized === "@me" ? void 0 : { username: normalized }
@@ -9580,7 +10473,13 @@ class MalUserOperation extends RestOperation {
   /**
    * {@link MalUserOperation.mangaList} gets a user's manga list, one page at a time.
    *
-   * It calls `GET /users/{username}/mangalist` through `RestOperation.execute` and returns a {@link MalUserMangaListResponse} page of `MalUserMangaListEntry` entries shaped by {@link MalRequestOptions.fields}. The facade alias is `MyAnimeListUserApi.mangaList` and it is a public read: `username` accepts a user name or `@me`, with `@me` and private lists requiring an access token (a client ID alone cannot resolve `@me`). The `@me` check is case-insensitive and ignores surrounding whitespace.
+   * It calls `GET /users/{username}/mangalist` through
+   * `RestOperation.execute` and returns a {@link MalUserMangaListResponse}
+   * page of `MalUserMangaListEntry` entries shaped by
+   * {@link MalRequestOptions.fields}. The facade exposes this method as
+   * `MyAnimeListUserApi.mangaList`. `username` accepts a user name or `@me`;
+   * `@me` and private lists require an access token. The `@me` check ignores
+   * case and surrounding whitespace.
    *
    * @param params - The manga-list read inputs; a {@link MalUserMangaListParams} carrying the username plus the optional status, sort, and paging filters.
    * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
@@ -9607,8 +10506,8 @@ class MalUserOperation extends RestOperation {
     return await this.execute(
       normalized === "@me" ? "/users/@me/mangalist" : "/users/{username}/mangalist",
       {
-        // `@me` resolves the authenticated user, which only a bearer token
-        // can identify — a client ID alone cannot — so fail fast like `me`.
+        // Only a bearer token can identify the authenticated user at
+        // `@me`; a client ID alone cannot. Require one, as `me` does.
         requiresAuth: normalized === "@me",
         transportOptions,
         // `buildQueryString` skips undefined/null values, so the
@@ -9620,7 +10519,7 @@ class MalUserOperation extends RestOperation {
           limit,
           offset
         },
-        // The trimmed username, not the raw argument: surrounding
+        // The trimmed username, not the raw argument. Surrounding
         // whitespace would otherwise be percent-encoded into the
         // path and answered with a 404.
         pathParams: normalized === "@me" ? void 0 : { username: normalized }
@@ -9629,180 +10528,60 @@ class MalUserOperation extends RestOperation {
   }
 }
 
-const MAX_PER_PAGE = 100;
-const DEFAULT_PER_PAGE = MAX_PER_PAGE;
-const DEFAULT_MAX_PAGES = 100;
-const DEFAULT_CONCURRENCY = 1;
-const safeCallback = (callback, name, onHookError, diagnostics, payload) => {
-  safeInvoke(callback, name, onHookError, diagnostics, payload);
-};
-function extractHasMore(response, perPage) {
-  return Array.isArray(response.data) && response.data.length >= perPage;
-}
-async function malPaginate(fetchPage, options) {
-  const perPage = resolveCappedInt(options?.perPage, MAX_PER_PAGE, DEFAULT_PER_PAGE, "perPage");
-  const startPage = resolvePositiveInt(options?.startPage, 1, "startPage");
-  const maxPages = resolvePositiveInt(options?.maxPages, DEFAULT_MAX_PAGES, "maxPages");
-  const concurrency = resolveCappedInt(
-    options?.concurrency,
-    MAX_CONCURRENCY,
-    DEFAULT_CONCURRENCY,
-    "concurrency"
-  );
-  const diagnostics = resolveDiagnosticsMode(options?.diagnostics);
-  const { signal, dispose } = bridgeAbortSignal(options?.signal);
-  try {
-    const { responses, count, truncated } = await fetchWithLookAhead(
-      (page) => fetchPage(page, perPage, signal),
-      (response) => extractHasMore(response, perPage),
-      startPage,
-      maxPages,
-      concurrency,
-      signal
-    );
-    const items = [];
-    const pages = [];
-    for (const response of responses) {
-      const raw = response.data;
-      if (raw === void 0) {
-        throw new AniLinkValidationError([
-          'malPaginate: the page response has no "data" key. Check the fetchPage closure returns the raw MAL list response.'
-        ]);
-      }
-      const pageItems = Array.isArray(raw) ? raw : [];
-      pages.push({ paging: response.paging, items: pageItems });
-      items.push(...pageItems);
-      safeCallback(options?.onPage, "onPage", options?.onHookError, diagnostics, {
-        paging: response.paging,
-        items: pageItems
-      });
-    }
-    return { items, pages, pageCount: count, truncated };
-  } finally {
-    dispose();
-  }
-}
-async function* malPaginatePages(fetchPage, options) {
-  const perPage = resolveCappedInt(options?.perPage, MAX_PER_PAGE, DEFAULT_PER_PAGE, "perPage");
-  const startPage = resolvePositiveInt(options?.startPage, 1, "startPage");
-  const maxPages = resolvePositiveInt(options?.maxPages, DEFAULT_MAX_PAGES, "maxPages");
-  const concurrency = resolveCappedInt(
-    options?.concurrency,
-    MAX_CONCURRENCY,
-    DEFAULT_CONCURRENCY,
-    "concurrency"
-  );
-  const diagnostics = resolveDiagnosticsMode(options?.diagnostics);
-  for await (const response of streamNumericPages(
-    fetchPage,
-    // A short page is MAL's own end-of-list signal (its `paging.next` is
-    // derived from the same offset math), so the traversal ends there
-    // instead of launching a request the server has already said is
-    // empty. A malformed `data` array ends the traversal the same way
-    // instead of looping forever.
-    (page) => !Array.isArray(page.data) || page.data.length < perPage,
-    { perPage, startPage, maxPages, concurrency, signal: options?.signal }
-  )) {
-    safeCallback(options?.onPage, "onPage", options?.onHookError, diagnostics, {
-      paging: response.paging,
-      items: Array.isArray(response.data) ? response.data : []
-    });
-    yield response;
-  }
+function op(name, operationClass) {
+  return { name, operationClass, methodName: name };
 }
-
-const MAL_AUTH_TIMEOUT_MS = 1e4;
-const buildMalAuthorizationUrl = (clientId, codeChallenge, state) => {
-  const params = new URLSearchParams({
-    response_type: "code",
-    client_id: clientId,
-    code_challenge: codeChallenge,
-    code_challenge_method: "plain"
-  });
-  if (state !== void 0) params.set("state", state);
-  return `${MAL_AUTHORIZE_URL}?${params.toString().replaceAll("+", "%20")}`;
-};
-const normalizeMalTokenError = (error) => sanitizeTokenError(error, "MAL token request");
-const requestMalToken = async (params, options) => {
-  try {
-    const body = new URLSearchParams(params).toString();
-    return await sendRequest(MAL_TOKEN_URL, "POST", body, void 0, {
-      requiresAuth: false,
-      options: {
-        ...options,
-        timeout: options?.timeout ?? MAL_AUTH_TIMEOUT_MS,
-        retry: options?.retry ?? false,
-        exposeRawAxiosError: false
-      },
-      contentType: "application/x-www-form-urlencoded"
-    });
-  } catch (error) {
-    throw normalizeMalTokenError(error);
-  }
-};
-const getMalAccessToken = (request) => requestMalToken(
-  {
-    client_id: request.clientId,
-    code: request.code,
-    code_verifier: request.codeVerifier,
-    grant_type: "authorization_code",
-    ...request.clientSecret === void 0 ? {} : { client_secret: request.clientSecret }
-  },
-  request.options
-);
-const refreshMalAccessToken = (request) => requestMalToken(
-  {
-    client_id: request.clientId,
-    grant_type: "refresh_token",
-    refresh_token: request.refreshToken,
-    ...request.clientSecret === void 0 ? {} : { client_secret: request.clientSecret }
-  },
-  request.options
-);
-const getMalTokenExpiry = (response, now = Date.now()) => {
-  const { expires_in } = response;
-  if (!Number.isFinite(expires_in) || expires_in <= 0) {
-    throw new TypeError(
-      `Invalid expires_in ${expires_in}: token lifetime must be a finite, positive number of seconds.`
-    );
-  }
-  return new Date(now + expires_in * 1e3);
+const MAL_OPERATION_REGISTRY = {
+  anime: [
+    op("get", MalAnimeOperation),
+    op("search", MalAnimeOperation),
+    op("seasonal", MalAnimeOperation),
+    op("ranking", MalAnimeOperation),
+    op("suggestions", MalAnimeOperation),
+    op("updateMyListStatus", MalAnimeOperation),
+    op("deleteFromList", MalAnimeOperation)
+  ],
+  manga: [
+    op("get", MalMangaOperation),
+    op("search", MalMangaOperation),
+    op("ranking", MalMangaOperation),
+    op("updateMyListStatus", MalMangaOperation),
+    op("deleteFromList", MalMangaOperation)
+  ],
+  user: [
+    op("me", MalUserOperation),
+    op("get", MalUserOperation),
+    op("animeList", MalUserOperation),
+    op("mangaList", MalUserOperation)
+  ],
+  forum: [
+    op("boards", MalForumOperation),
+    op("topics", MalForumOperation),
+    op("topic", MalForumOperation)
+  ]
 };
 
-const buildMalTokenRefresher = (options) => {
-  const exchange = (refreshToken) => refreshMalAccessToken({
-    clientId: options.clientId,
-    refreshToken,
-    clientSecret: options.clientSecret
-  });
-  return new TokenRefresher({
-    exchange,
-    refreshToken: options.refreshToken,
-    provider: { hookName: "malTokenRefresh", providerLabel: "MAL" },
-    onTokenRefresh: options.onTokenRefresh,
-    onTokenRefreshError: options.onTokenRefreshError,
-    onHookError: options.onHookError,
-    diagnostics: options.diagnostics,
-    applyAccessToken: options.applyAccessToken
-  });
-};
-const buildRefreshedAuth = (auth, accessToken) => {
-  const headers = typeof auth === "object" && auth?.headers !== void 0 ? Object.fromEntries(
-    Object.entries(auth.headers).filter(([key]) => key !== "X-MAL-CLIENT-ID")
-  ) : void 0;
-  return {
-    token: accessToken,
-    headers: headers !== void 0 && Object.keys(headers).length > 0 ? headers : void 0
-  };
-};
+const buildMalTokenRefresher = (options) => new TokenRefresher({
+  descriptor: MAL_TOKEN_GRANT,
+  ...options
+});
+const buildRefreshedAuth = (auth, accessToken) => rewriteAuth(MAL_TOKEN_GRANT, auth, accessToken);
 
 function buildMyAnimeListApi(credentials, stateOwner) {
   const { auth, options } = resolveMalCredentials(credentials);
   const sharedStateOwner = stateOwner ?? {};
-  const anime = new MalAnimeOperation(auth, options, sharedStateOwner);
-  const manga = new MalMangaOperation(auth, options, sharedStateOwner);
-  const user = new MalUserOperation(auth, options, sharedStateOwner);
-  const forum = new MalForumOperation(auth, options, sharedStateOwner);
+  const groups = Object.keys(MAL_OPERATION_REGISTRY);
+  const wired = [];
+  for (const group of groups) {
+    for (const entry of MAL_OPERATION_REGISTRY[group]) {
+      const operationClass = entry.operationClass;
+      wired.push({
+        group,
+        entry,
+        instance: new operationClass(auth, options, sharedStateOwner)
+      });
+    }
+  }
   const refresher = isNonBlank(credentials?.refreshToken) && isNonBlank(credentials?.clientId) ? buildMalTokenRefresher({
     clientId: credentials.clientId.trim(),
     refreshToken: credentials.refreshToken.trim(),
@@ -9812,83 +10591,34 @@ function buildMyAnimeListApi(credentials, stateOwner) {
     onHookError: credentials.onHookError,
     diagnostics: credentials.diagnostics,
     applyAccessToken: (accessToken) => {
-      for (const operation of [anime, manga, user, forum]) {
-        operation.updateAuth(
-          buildRefreshedAuth(operation.getAuth(), accessToken)
-        );
+      for (const { instance } of wired) {
+        instance.updateAuth(buildRefreshedAuth(instance.getAuth(), accessToken));
       }
     }
   }) : void 0;
-  if (refresher === void 0) {
-    return {
-      anime: {
-        get: anime.get.bind(anime),
-        search: anime.search.bind(anime),
-        seasonal: anime.seasonal.bind(anime),
-        ranking: anime.ranking.bind(anime),
-        suggestions: anime.suggestions.bind(anime),
-        updateMyListStatus: anime.updateMyListStatus.bind(anime),
-        deleteFromList: anime.deleteFromList.bind(anime)
-      },
-      manga: {
-        get: manga.get.bind(manga),
-        search: manga.search.bind(manga),
-        ranking: manga.ranking.bind(manga),
-        updateMyListStatus: manga.updateMyListStatus.bind(manga),
-        deleteFromList: manga.deleteFromList.bind(manga)
-      },
-      user: {
-        me: user.me.bind(user),
-        get: user.get.bind(user),
-        animeList: user.animeList.bind(user),
-        mangaList: user.mangaList.bind(user)
-      },
-      forum: {
-        boards: forum.boards.bind(forum),
-        topics: forum.topics.bind(forum),
-        topic: forum.topic.bind(forum)
-      },
-      // The pagination helpers are provider-owned pure functions over
-      // the shared engine — no transport state to bind, so they are
-      // exposed directly on both branches.
-      paginate: malPaginate,
-      paginatePages: malPaginatePages
-    };
+  const maybeWrap = refresher === void 0 ? (method) => method : (method) => (...args) => refresher.executeWithRefresh(() => method(...args));
+  const groupMembers = Object.fromEntries(groups.map((group) => [group, {}]));
+  for (const { group, entry, instance } of wired) {
+    const method = instance[entry.methodName];
+    groupMembers[group][entry.name] = maybeWrap(
+      method.bind(instance)
+    );
   }
-  const wrap = (method) => (...args) => refresher.executeWithRefresh(() => method(...args));
   return {
-    anime: {
-      get: wrap(anime.get.bind(anime)),
-      search: wrap(anime.search.bind(anime)),
-      seasonal: wrap(anime.seasonal.bind(anime)),
-      ranking: wrap(anime.ranking.bind(anime)),
-      suggestions: wrap(anime.suggestions.bind(anime)),
-      updateMyListStatus: wrap(anime.updateMyListStatus.bind(anime)),
-      deleteFromList: wrap(anime.deleteFromList.bind(anime))
-    },
-    manga: {
-      get: wrap(manga.get.bind(manga)),
-      search: wrap(manga.search.bind(manga)),
-      ranking: wrap(manga.ranking.bind(manga)),
-      updateMyListStatus: wrap(manga.updateMyListStatus.bind(manga)),
-      deleteFromList: wrap(manga.deleteFromList.bind(manga))
-    },
-    user: {
-      me: wrap(user.me.bind(user)),
-      get: wrap(user.get.bind(user)),
-      animeList: wrap(user.animeList.bind(user)),
-      mangaList: wrap(user.mangaList.bind(user))
-    },
-    forum: {
-      boards: wrap(forum.boards.bind(forum)),
-      topics: wrap(forum.topics.bind(forum)),
-      topic: wrap(forum.topic.bind(forum))
+    ...groupMembers,
+    auth: {
+      buildAuthorizationUrl: buildMalAuthorizationUrl,
+      exchangeCode: getMalAccessToken
     },
+    // The pagination helpers are provider-owned pure functions over
+    // the shared engine. They need no transport state, so they are
+    // exposed directly alongside the wired groups.
     paginate: malPaginate,
     paginatePages: malPaginatePages
   };
 }
 
+const registerProviderFactory = (factory, resolveCredentials, acceptsLegacyOptions = false) => Object.assign(factory, { resolveCredentials, acceptsLegacyOptions });
 const buildAniListClient = (credentials, legacyOptions, stateOwner) => {
   const resolved = resolveAniListCredentials(credentials);
   return buildAniListApi(
@@ -9900,8 +10630,8 @@ const buildAniListClient = (credentials, legacyOptions, stateOwner) => {
 };
 const buildMalClient = (credentials, _legacyOptions, stateOwner) => buildMyAnimeListApi(credentials, stateOwner);
 const PROVIDER_FACTORIES = {
-  anilist: buildAniListClient,
-  mal: buildMalClient
+  anilist: registerProviderFactory(buildAniListClient, resolveAniListCredentials, true),
+  mal: registerProviderFactory(buildMalClient, resolveMalCredentials)
 };
 function buildProviderClients(credentials = {}, legacyOptions) {
   const clientHookError = credentials.onHookError;
@@ -9921,20 +10651,27 @@ function buildProviderClients(credentials = {}, legacyOptions) {
       ...needsDiagnostics ? { diagnostics: clientDiagnostics } : {}
     };
   };
-  const anilistStateOwner = {};
-  const malStateOwner = {};
-  return {
-    anilist: PROVIDER_FACTORIES.anilist(
-      withDefaultHook(credentials.anilist),
-      legacyOptions,
-      anilistStateOwner
-    ),
-    mal: PROVIDER_FACTORIES.mal(withDefaultHook(credentials.mal), void 0, malStateOwner),
-    stateOwners: { anilist: anilistStateOwner, mal: malStateOwner }
-  };
+  const clients = {};
+  const stateOwners = {};
+  const responseCaches = {};
+  for (const providerId of Object.keys(PROVIDER_FACTORIES)) {
+    const factory = PROVIDER_FACTORIES[providerId];
+    const slot = withDefaultHook(credentials[providerId]);
+    const stateOwner = {};
+    const client = factory(
+      slot,
+      factory.acceptsLegacyOptions ? legacyOptions : void 0,
+      stateOwner
+    );
+    const effectiveOptions = factory.resolveCredentials(slot).options ?? (factory.acceptsLegacyOptions ? legacyOptions : void 0);
+    clients[providerId] = client;
+    stateOwners[providerId] = stateOwner;
+    responseCaches[providerId] = effectiveOptions?.responseCache;
+  }
+  return { ...clients, stateOwners, responseCaches };
 }
 
-const snapshotTransportState = (owner) => {
+const snapshotTransportState = (owner, responseCache) => {
   const circuitScopes = peekCircuitStates(owner);
   const circuit = circuitScopes === void 0 ? [] : Array.from(
     circuitScopes,
@@ -9950,6 +10687,7 @@ const snapshotTransportState = (owner) => {
   const deadlines = peekPaceDeadlines(owner);
   const paceDeadlines = deadlines === void 0 ? [] : Array.from(deadlines, ([host, deadlineMs]) => Object.freeze({ host, deadlineMs }));
   return Object.freeze({
+    capturedAt: Date.now(),
     circuit: Object.freeze(circuit),
     ...budget !== void 0 ? {
       retryBudget: Object.freeze({
@@ -9957,21 +10695,24 @@ const snapshotTransportState = (owner) => {
         windowEndsAt: budget.windowEndsAt
       })
     } : {},
-    paceDeadlines: Object.freeze(paceDeadlines)
+    paceDeadlines: Object.freeze(paceDeadlines),
+    ...responseCache !== void 0 ? { responseCache: responseCache.stats() } : {}
   });
 };
 
 class AniLink {
   /**
-   * The AniList GraphQL API surface, a {@link AniListApi} composed from the
+   * The AniList GraphQL API, a {@link AniListApi} composed from the
    * query, mutation, custom, and helper groups.
    * @public
    */
   anilist;
   /** The MyAnimeList REST API methods, a {@link MyAnimeListApi} exposed under the `mal` namespace. */
   mal;
-  /** The per-provider state owners the clients key their shared transport state (breaker, budget, pacing) through. */
+  /** The per-provider state owners that hold each client's shared transport state (breaker, budget, pacing). */
   stateOwners;
+  /** The per-provider response caches resolved from the transport options, when enabled, for the cache-stats snapshot. */
+  responseCaches;
   /**
    * Creates a new {@link AniLink} instance. The `authToken` parameter is optional and only
    * required for authenticated queries and mutations; without it only public queries are
@@ -9981,9 +10722,9 @@ class AniLink {
    * Alternatively, pass a per-provider {@link AniLinkCredentials} object: each provider
    * owns its own credentials shape, and credentials given under one key are
    * never applied to another provider's requests.
-   * @param {string | AniLinkCredentials} [authToken] - The authentication token to use for AniList API requests, or a per-provider credentials object (`{ anilist?: …, mal?: … }`).
-   * @param {AniLinkOptions} [options] - Transport settings scoped to this instance: `timeout`, `signal` cancellation, automatic retries under the default policy (`retry: false` opts out), `paceWithRateLimit` pacing (on by default), opt-in `circuitBreaker` fast-fail, the `onError`/`onRetry`/`onRequestStart`/`onResponse` observability hooks, and `exposeRawAxiosError` debugging. Options never leak between instances. Only valid when the first argument is a token string or omitted; combining a credentials object with a second argument throws, because the credentials form carries its own per-provider transport settings and a second argument would be silently dropped.
-   * @throws {TypeError} When a per-provider credentials object is combined with a second `options` argument. The credentials form carries transport settings inside each provider slot, so the second argument would be silently ignored — the constructor rejects the ambiguous call instead.
+   * @param {string | AniLinkCredentials} [authToken] - The authentication token to use for AniList API requests, or a per-provider credentials object (`{ anilist?: ..., mal?: ... }`).
+   * @param {AniLinkOptions} [options] - Transport settings scoped to this instance: `timeout`, `signal` cancellation, automatic retries under the default policy (`retry: false` opts out), `paceWithRateLimit` pacing (on by default), opt-in `circuitBreaker` fast-fail, the `onError`/`onRetry`/`onRequestStart`/`onResponse` observability hooks, and `exposeRawAxiosError` debugging. In the legacy `(token, options)` form, these settings apply only to AniList. Configure MAL transport settings in the credentials-object form under `mal`. Options never leak between instances. Only valid when the first argument is a token string or omitted; combining a credentials object with a second argument throws, because the credentials form carries its own per-provider transport settings and a second argument would be silently dropped.
+   * @throws {TypeError} When a per-provider credentials object is combined with a second `options` argument. The credentials form carries transport settings inside each provider slot, so the second argument would be silently ignored. The constructor rejects the ambiguous call instead.
    * @public
    * @example
    * ```typescript
@@ -10022,23 +10763,32 @@ class AniLink {
     this.anilist = clients.anilist;
     this.mal = clients.mal;
     this.stateOwners = clients.stateOwners;
+    this.responseCaches = clients.responseCaches ?? {
+      anilist: void 0,
+      mal: void 0
+    };
   }
   /**
    * Returns a read-only, point-in-time snapshot of each provider client's
-   * shared transport state — the circuit-breaker scopes, retry-budget
-   * window, and rate-limit pacing deadlines keyed through that client's
-   * state owner — so "is the breaker open right now?", "how many budget
-   * retries are spent?", and "when does the pacing deadline elapse?" can
-   * be answered without pre-wiring lifecycle hooks.
+   * shared transport state: the circuit-breaker scopes, retry-budget
+   * window, rate-limit pacing deadlines keyed through that client's
+   * state owner, and (when the provider's transport options enable a
+   * response cache) the cache's live entry count and lifetime
+   * hit/miss/expiration/eviction counters. Callers can check whether a
+   * breaker is open, how many budget retries are spent, when pacing ends,
+   * and how the cache performs
+   * without wiring lifecycle hooks and without holding the
+   * {@link ResponseCache} instance.
    *
    * Each provider's snapshot is built by {@link snapshotTransportState},
-   * which owns the read-only contract: deep-frozen copies that never
-   * alias the live mutable state, and a build step that never mutates
-   * the state it observes. Polling on a schedule is therefore safe
+   * which owns the read-only contract. It returns deep-frozen copies that
+   * never alias or mutate the live state, so polling on a schedule is safe
    * alongside live traffic.
    *
    * @returns A frozen per-provider {@link TransportStateSnapshot} pair:
-   * `{ anilist: {...}, mal: {...} }`.
+   * `{ anilist: {...}, mal: {...} }`. Each snapshot carries `capturedAt`,
+   * the epoch-millisecond build time, so a polled snapshot records when
+   * it was taken.
    * @example
    * ```typescript
    * const aniLink = new AniLink("token", {
@@ -10060,14 +10810,18 @@ class AniLink {
    * for (const deadline of state.anilist.paceDeadlines) {
    *     console.log("pacing until", new Date(deadline.deadlineMs).toISOString(), "for", deadline.host);
    * }
+   * if (state.anilist.responseCache) {
+   *     console.log("cache entries:", state.anilist.responseCache.entries);
+   * }
    * ```
    */
   getTransportState() {
+    const caches = this.responseCaches ?? { anilist: void 0, mal: void 0 };
     return Object.freeze({
-      anilist: snapshotTransportState(this.stateOwners.anilist),
-      mal: snapshotTransportState(this.stateOwners.mal)
+      anilist: snapshotTransportState(this.stateOwners.anilist, caches.anilist),
+      mal: snapshotTransportState(this.stateOwners.mal, caches.mal)
     });
   }
 }
 
-export { ANILIST_AUTHORIZE_URL, ANILIST_TOKEN_URL, AniLink, AniLinkApiError, AniLinkAuthError, AniLinkError, AniLinkErrorCodes, AniLinkGraphQLError, AniLinkNetworkError, AniLinkRestError, AniLinkValidationError, MAL_API_BASE_URL, MAL_API_REFERENCE, MAL_AUTHORIZE_URL, MAL_TOKEN_URL, ResponseCache, buildAuthorizationUrl, buildMalAuthorizationUrl, buildMyAnimeListApi, buildProviderClients, crossLink, destroyCachedAgents, fuzzyDate, fuzzyDateInt, getAccessToken, getMalAccessToken, getMalTokenExpiry, getTokenExpiry, malPaginate, malPaginatePages, paginate, paginateChunks, paginatePages, refreshAccessToken, refreshMalAccessToken, snapshotTransportState };
+export { ANILIST_AUTHORIZE_URL, ANILIST_TOKEN_URL, AniLink, AniLinkApiError, AniLinkAuthError, AniLinkError, AniLinkErrorCodes, AniLinkGraphQLError, AniLinkNetworkError, AniLinkRestError, AniLinkValidationError, MAL_API_BASE_URL, MAL_API_REFERENCE, MAL_AUTHORIZE_URL, MAL_TOKEN_URL, ResponseCache, buildAuthorizationUrl, buildMalAuthorizationUrl, buildMyAnimeListApi, buildProviderClients, crossLink, destroyCachedAgents, fuzzyDate, fuzzyDateInt, getAccessToken, getMalAccessToken, getMalTokenExpiry, getTokenExpiry, malPaginate, malPaginatePages, mapExternalIds, paginate, paginateChunks, paginatePages, refreshAccessToken, refreshMalAccessToken, snapshotTransportState };