anilink-api-wrapper 2.0.0 → 2.2.0

package/dist/AniLink.mjs

@@ -1,6 +1,6 @@
+import { randomInt, randomUUID, createHash } from 'node:crypto';
 import http from 'node:http';
 import https from 'node:https';
-import { randomInt } from 'node:crypto';
 import axios from 'axios';
 
 const AniLinkErrorCodes = {
@@ -15,6 +15,7 @@ const AniLinkErrorCodes = {
   UNKNOWN: "UNKNOWN_ERROR"
 };
 class AniLinkError extends Error {
+  /** Stable code used to classify the failure. */
   code;
   /**
    * Creates a sanitized AniLink error.
@@ -22,19 +23,25 @@ class AniLinkError extends Error {
    * @param message - A safe message intended for application logs.
    * @param code - The stable code used to classify the failure.
    * @param rawAxiosError - The original Axios error when raw diagnostics are enabled.
+   * @param options - Additional error metadata such as the request correlation ID.
    */
-  constructor(message, code, rawAxiosError) {
+  constructor(message, code, rawAxiosError, options) {
     super(message, rawAxiosError instanceof Error ? { cause: rawAxiosError } : void 0);
     this.name = "AniLinkError";
     this.code = code;
     if (rawAxiosError !== void 0) {
       this.rawAxiosError = rawAxiosError;
     }
+    if (options?.requestId !== void 0) {
+      this.requestId = options.requestId;
+    }
     Object.setPrototypeOf(this, new.target.prototype);
   }
 }
 class AniLinkApiError extends AniLinkError {
+  /** HTTP status returned by the upstream API. For GraphQL failures this is the upstream GraphQL error status when available, and the HTTP envelope status (`200`) otherwise. */
   status;
+  /** Response body returned by the upstream API, preserved verbatim. */
   data;
   /**
    * Creates an API error while preserving the upstream response body.
@@ -42,18 +49,32 @@ class AniLinkApiError extends AniLinkError {
    * @param status - The HTTP status returned by AniList.
    * @param data - The response body returned by AniList.
    * @param rawAxiosError - The original Axios error when raw diagnostics are enabled.
-   * @param options - Additional error metadata such as rate-limit headers.
+   * @param options - Additional error metadata such as rate-limit headers and the response content type.
    */
   constructor(status, data, rawAxiosError, options) {
-    super(`API request failed with status ${status}.`, AniLinkErrorCodes.API, rawAxiosError);
+    super(`API request failed with status ${status}.`, AniLinkErrorCodes.API, rawAxiosError, {
+      requestId: options?.requestId
+    });
     this.name = "AniLinkApiError";
     this.status = status;
     this.data = data;
     if (options?.rateLimit !== void 0) {
       this.rateLimit = options.rateLimit;
     }
+    if (options?.contentType !== void 0) {
+      this.contentType = options.contentType;
+    }
   }
 }
+const extractUpstreamStatus = (errors) => {
+  for (const entry of errors) {
+    const status = entry.status;
+    if (typeof status === "number" && Number.isFinite(status)) {
+      return status;
+    }
+  }
+  return void 0;
+};
 class AniLinkGraphQLError extends AniLinkApiError {
   /**
    * The upstream GraphQL `errors` array carried by the envelope, preserved
@@ -68,9 +89,10 @@ class AniLinkGraphQLError extends AniLinkApiError {
    * @param errors - The upstream GraphQL errors; each entry should carry a `message`.
    * @param data - The partial `data` object returned alongside the errors, when any. Exposed as {@link AniLinkGraphQLError.partialData}.
    * @param rawAxiosError - The original Axios error when raw diagnostics are enabled.
+   * @param options - Additional error metadata such as rate-limit headers and the response content type. AniList returns rate-limit headers even on HTTP 200 envelopes carrying GraphQL errors (for example a GraphQL-level `429`), so threading them here keeps {@link AniLinkGraphQLError.rateLimit} consistent with the HTTP-failure path.
    */
-  constructor(errors, data, rawAxiosError) {
-    super(200, data, rawAxiosError);
+  constructor(errors, data, rawAxiosError, options) {
+    super(extractUpstreamStatus(errors) ?? 200, data, rawAxiosError, options);
     this.name = "AniLinkGraphQLError";
     this.code = AniLinkErrorCodes.GRAPHQL;
     this.message = `The request failed with GraphQL errors: ${errors.map((graphqlError) => graphqlError.message).join("; ")}`;
@@ -95,7 +117,7 @@ class AniLinkAuthError extends AniLinkError {
   }
 }
 class AniLinkValidationError extends AniLinkError {
-  /** The individual validation problems, one per line. */
+  /** Individual validation problems, one per entry. */
   details;
   /**
    * Creates a validation error for invalid operation variables.
@@ -113,6 +135,18 @@ ${details.join("\n")}`,
   }
 }
 class AniLinkRestError extends AniLinkApiError {
+  /**
+   * Creates a REST error carrying the upstream HTTP status and body.
+   *
+   * @param status - The HTTP status returned by the upstream REST API.
+   * @param data - The response body returned by the upstream REST API.
+   * @param rawAxiosError - The original Axios error when raw diagnostics are enabled.
+   * @param options - Additional error metadata such as rate-limit headers, the response content type, and the request correlation ID.
+   */
+  constructor(status, data, rawAxiosError, options) {
+    super(status, data, rawAxiosError, options);
+    this.name = "AniLinkRestError";
+  }
 }
 class AniLinkNetworkError extends AniLinkError {
   /**
@@ -121,21 +155,104 @@ class AniLinkNetworkError extends AniLinkError {
    * @param code - The stable code for the transport failure.
    * @param message - A safe message intended for application logs.
    * @param rawAxiosError - The original Axios error when raw diagnostics are enabled.
-   * @param options - Additional transport metadata such as the effective timeout duration.
+   * @param options - Additional transport metadata such as the effective timeout duration and the request correlation ID.
    */
   constructor(code, message, rawAxiosError, options) {
-    super(message, code, rawAxiosError);
+    super(message, code, rawAxiosError, { requestId: options?.requestId });
     this.name = "AniLinkNetworkError";
     if (options?.timeoutMs !== void 0) {
       this.timeoutMs = options.timeoutMs;
     }
+    if (options?.abortedDuringPacing !== void 0) {
+      this.abortedDuringPacing = options.abortedDuringPacing;
+    }
   }
 }
 
 const DEFAULT_REQUEST_TIMEOUT = 3e4;
-const MAX_RETRY_AFTER_MS = 6e4;
 const MAX_FREE_SOCKETS = 5;
 const MAX_SOCKETS = 20;
+
+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 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) {
+      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 || !Number.isFinite(value) || !Number.isInteger(value)) {
+      return Math.max(min, fallback);
+    }
+    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,
   baseDelayMs: 250,
@@ -144,21 +261,6 @@ const DEFAULT_RETRY_POLICY = {
   retryOnNetworkError: true,
   jitter: true
 };
-const axiosClient = axios.create({
-  timeout: DEFAULT_REQUEST_TIMEOUT,
-  httpAgent: new http.Agent({
-    keepAlive: true,
-    maxSockets: MAX_SOCKETS,
-    maxFreeSockets: MAX_FREE_SOCKETS,
-    scheduling: "lifo"
-  }),
-  httpsAgent: new https.Agent({
-    keepAlive: true,
-    maxSockets: MAX_SOCKETS,
-    maxFreeSockets: MAX_FREE_SOCKETS,
-    scheduling: "lifo"
-  })
-});
 const resolveRetryPolicy = (retry) => {
   if (retry === false) {
     return null;
@@ -166,47 +268,190 @@ const resolveRetryPolicy = (retry) => {
   if (retry === void 0 || retry === true) {
     return { ...DEFAULT_RETRY_POLICY };
   }
-  return { ...DEFAULT_RETRY_POLICY, ...retry };
+  const filtered = {};
+  for (const [key, value] of Object.entries(retry)) {
+    if (value !== void 0) {
+      filtered[key] = value;
+    }
+  }
+  return { ...DEFAULT_RETRY_POLICY, ...filtered };
+};
+const parseRetryAfter = (header, now) => {
+  if (header === void 0 || header === null || header === "") {
+    return null;
+  }
+  const seconds = Number(header);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.min(seconds * 1e3, MAX_RETRY_AFTER_MS);
+  }
+  const date = Date.parse(header);
+  if (Number.isFinite(date)) {
+    return Math.max(0, Math.min(date - now, MAX_RETRY_AFTER_MS));
+  }
+  return null;
 };
+const getRetryAfterDelay = (error) => {
+  if (axios.isAxiosError(error)) {
+    const header = error.response?.headers?.["retry-after"];
+    if (typeof header === "string" || header === void 0) {
+      return parseRetryAfter(header, Date.now());
+    }
+  }
+  return null;
+};
+const getBackoffDelay = (attempt, policy) => Math.min(policy.baseDelayMs * 2 ** attempt, policy.maxDelayMs);
+const applyJitter = (cap, policy) => policy.jitter === false ? cap : randomInt(0, cap + 1);
+const getRetryDelay = (error, rawError, attempt, policy) => {
+  if (attempt >= policy.maxRetries) {
+    return null;
+  }
+  if (error instanceof AniLinkGraphQLError) {
+    if (error.status === 429) {
+      return getRetryAfterDelay(rawError) ?? applyJitter(getBackoffDelay(attempt, policy), policy);
+    }
+    if (policy.retryOnStatus.includes(error.status)) {
+      return applyJitter(getBackoffDelay(attempt, policy), policy);
+    }
+    return null;
+  }
+  if (error instanceof AniLinkApiError) {
+    if (error.status === 429) {
+      return getRetryAfterDelay(rawError) ?? applyJitter(getBackoffDelay(attempt, policy), policy);
+    }
+    if (policy.retryOnStatus.includes(error.status)) {
+      return applyJitter(getBackoffDelay(attempt, policy), policy);
+    }
+    return null;
+  }
+  if (error instanceof AniLinkNetworkError) {
+    if (error.code === AniLinkErrorCodes.ABORTED) {
+      return null;
+    }
+    if (policy.retryOnNetworkError) {
+      return applyJitter(getBackoffDelay(attempt, policy), policy);
+    }
+  }
+  return null;
+};
+const computeNextRetryDelay = (input) => {
+  const { normalized, rawError, attempt, policy, budgetState, budget, wasProbe } = input;
+  if (wasProbe || policy === null) {
+    return null;
+  }
+  if (budgetState !== void 0 && budget !== void 0 && budgetState.retriesUsed >= budget.maxRetriesPerWindow) {
+    return null;
+  }
+  return getRetryDelay(normalized, rawError, attempt, policy);
+};
+const retryBudgetStates = /* @__PURE__ */ new WeakMap();
+const getRetryBudgetState = (owner, budget) => {
+  if (owner === void 0 || budget === void 0) {
+    return void 0;
+  }
+  let state = retryBudgetStates.get(owner);
+  if (state === void 0) {
+    state = { retriesUsed: 0, windowEndsAt: 0 };
+    retryBudgetStates.set(owner, state);
+  }
+  if (Date.now() >= state.windowEndsAt) {
+    state.retriesUsed = 0;
+    state.windowEndsAt = Date.now() + budget.windowMs;
+  }
+  return state;
+};
+
 const resolveRequestOptions = (options = {}) => {
   const timeout = options.timeout ?? DEFAULT_REQUEST_TIMEOUT;
   if (!Number.isFinite(timeout) || timeout < 0) {
     throw new TypeError("timeout must be a finite number greater than or equal to 0");
   }
+  const agents = resolveAgents(options.maxSockets, options.maxFreeSockets);
   return {
     timeout,
     signal: options.signal,
     exposeRawAxiosError: options.exposeRawAxiosError ?? false,
     retry: resolveRetryPolicy(options.retry),
-    paceWithRateLimit: options.paceWithRateLimit ?? false,
+    paceWithRateLimit: options.paceWithRateLimit ?? true,
     rateLimitFloor: Math.max(1, options.rateLimitFloor ?? 1),
     circuitBreaker: options.circuitBreaker,
+    retryBudget: options.retryBudget,
+    httpAgent: agents.httpAgent,
+    httpsAgent: agents.httpsAgent,
     onError: options.onError,
     onRetry: options.onRetry,
     onRequestStart: options.onRequestStart,
-    onResponse: options.onResponse
+    onResponse: options.onResponse,
+    onPace: options.onPace,
+    onHookError: options.onHookError,
+    onCircuitOpen: options.onCircuitOpen,
+    onCircuitClose: options.onCircuitClose,
+    ignorePaceDeadline: options.ignorePaceDeadline ?? false,
+    responseCache: options.responseCache
   };
 };
-const unwrapSingleRootField = (response) => {
-  const envelope = response;
-  const queryData = envelope?.data;
-  if (!queryData || typeof queryData !== "object") {
-    return void 0;
+
+const SENSITIVE_HEADER_KEYS = /^(authorization|cookie|set-cookie|proxy-authorization|proxy-auth|authentication|(x-)?api[-_]?key|(x-)?auth[-_]?token|(x-)?session(-id)?|session)$/i;
+const redactAxiosError = (error) => {
+  const config = error.config;
+  const response = error.response;
+  const isHeaderMap = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+  const configNeedsRedaction = config !== void 0 && (isHeaderMap(config.headers) || config.data !== void 0 || config.auth !== void 0);
+  const responseNeedsRedaction = response !== void 0 && (response.config !== void 0 || isHeaderMap(response.headers) || response.request !== void 0);
+  const requestNeedsRedaction = error.request !== void 0;
+  if (!configNeedsRedaction && !responseNeedsRedaction && !requestNeedsRedaction) {
+    return error;
   }
-  const fields = Object.keys(queryData);
-  if (fields.length === 1) {
-    return queryData[fields[0]];
+  const redactHeaders = (headers) => {
+    const scrubbed = {};
+    for (const [key, value] of Object.entries(headers)) {
+      if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        scrubbed[key] = redactHeaders(value);
+      } else {
+        scrubbed[key] = SENSITIVE_HEADER_KEYS.test(key) ? "[REDACTED]" : value;
+      }
+    }
+    return scrubbed;
+  };
+  const redactConfig = (source) => {
+    const cloned2 = { ...source };
+    const headers = source.headers;
+    if (isHeaderMap(headers)) {
+      cloned2.headers = redactHeaders(headers);
+    }
+    if (source.data !== void 0) {
+      cloned2.data = "[REDACTED]";
+    }
+    if (source.auth !== void 0) {
+      cloned2.auth = "[REDACTED]";
+    }
+    return cloned2;
+  };
+  const cloned = { ...error };
+  const clonedRecord = cloned;
+  if (requestNeedsRedaction) {
+    clonedRecord.request = "[REDACTED]";
   }
-  return void 0;
-};
-const unwrapGraphQLResponse = (response) => {
-  const envelope = response;
-  if (Array.isArray(envelope?.errors) && envelope.errors.length > 0) {
-    throw new AniLinkGraphQLError(envelope.errors, envelope?.data);
+  if (config !== void 0) {
+    clonedRecord.config = redactConfig(config);
+  }
+  if (response !== void 0) {
+    const clonedResponse = { ...response };
+    const responseConfig = response.config;
+    if (responseConfig !== void 0) {
+      clonedResponse.config = redactConfig(responseConfig);
+    }
+    const responseHeaders = response.headers;
+    if (isHeaderMap(responseHeaders)) {
+      clonedResponse.headers = redactHeaders(responseHeaders);
+    }
+    if (response.request !== void 0) {
+      clonedResponse.request = "[REDACTED]";
+    }
+    clonedRecord.response = clonedResponse;
   }
-  return unwrapSingleRootField(response) ?? response;
+  return cloned;
 };
-const getRawAxiosError = (resolved, error) => resolved.exposeRawAxiosError ? error : void 0;
+const getRawAxiosError = (resolved, error) => resolved.exposeRawAxiosError ? axios.isAxiosError(error) ? redactAxiosError(error) : error : void 0;
 const getRateLimitInfo = (headers) => {
   if (!headers) {
     return void 0;
@@ -219,133 +464,163 @@ const getRateLimitInfo = (headers) => {
   }
   return { limit, remaining, reset };
 };
-const normalizeAxiosError = (resolved, error) => {
+const getResponseContentType = (headers) => {
+  if (!headers) return void 0;
+  const raw = headers["content-type"] ?? headers["Content-Type"];
+  return typeof raw === "string" ? raw : void 0;
+};
+const normalizeAxiosError = (resolved, error, isRestCall = false, requestId) => {
   if (axios.isCancel(error)) {
     return new AniLinkNetworkError(
       AniLinkErrorCodes.ABORTED,
       "The request was cancelled.",
-      getRawAxiosError(resolved, error)
+      getRawAxiosError(resolved, error),
+      { requestId }
     );
   }
   if (error.response?.status !== void 0) {
-    return new AniLinkApiError(
-      error.response.status,
-      error.response.data,
-      getRawAxiosError(resolved, error),
-      { rateLimit: getRateLimitInfo(error.response.headers) }
-    );
+    const status = error.response.status;
+    const data = error.response.data;
+    const rawAxiosError = getRawAxiosError(resolved, error);
+    const options = {
+      rateLimit: getRateLimitInfo(error.response.headers),
+      contentType: getResponseContentType(error.response.headers),
+      requestId
+    };
+    return isRestCall ? new AniLinkRestError(status, data, rawAxiosError, options) : new AniLinkApiError(status, data, rawAxiosError, options);
   }
   if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
     return new AniLinkNetworkError(
       AniLinkErrorCodes.TIMEOUT,
       "The request timed out.",
       getRawAxiosError(resolved, error),
-      resolved.timeout > 0 ? { timeoutMs: resolved.timeout } : void 0
+      { timeoutMs: resolved.timeout > 0 ? resolved.timeout : void 0, requestId }
     );
   }
   return new AniLinkNetworkError(
     AniLinkErrorCodes.NETWORK,
     "The request failed due to a network error.",
-    getRawAxiosError(resolved, error)
+    getRawAxiosError(resolved, error),
+    { requestId }
   );
 };
-const normalizeRequestError = (resolved, error) => {
+const stampRequestId = (error, requestId) => {
+  if (requestId === void 0 || error.requestId !== void 0) {
+    return;
+  }
+  Object.defineProperty(error, "requestId", {
+    value: requestId,
+    writable: false,
+    enumerable: true,
+    configurable: false
+  });
+};
+const normalizeRequestError = (resolved, error, isRestCall = false, requestId) => {
   if (error instanceof AniLinkError) {
+    stampRequestId(error, requestId);
     return error;
   }
   if (axios.isAxiosError(error)) {
-    return normalizeAxiosError(resolved, error);
+    return normalizeAxiosError(resolved, error, isRestCall, requestId);
   }
   return new AniLinkError(
     "The request failed.",
     AniLinkErrorCodes.UNKNOWN,
-    getRawAxiosError(resolved, error)
+    getRawAxiosError(resolved, error),
+    { requestId }
   );
 };
-const parseRetryAfter = (header, now) => {
-  if (header === void 0 || header === null || header === "") {
-    return null;
-  }
-  const seconds = Number(header);
-  if (Number.isFinite(seconds) && seconds >= 0) {
-    return Math.min(seconds * 1e3, MAX_RETRY_AFTER_MS);
-  }
-  const date = Date.parse(header);
-  if (Number.isFinite(date)) {
-    return Math.max(0, Math.min(date - now, MAX_RETRY_AFTER_MS));
+
+const unwrapSingleRootField = (response) => {
+  const envelope = response;
+  const queryData = envelope?.data;
+  if (!queryData || typeof queryData !== "object") {
+    return void 0;
   }
-  return null;
-};
-const getRetryAfterDelay = (error) => {
-  if (axios.isAxiosError(error)) {
-    const header = error.response?.headers?.["retry-after"];
-    if (typeof header === "string" || header === void 0) {
-      return parseRetryAfter(header, Date.now());
-    }
+  const fields = Object.keys(queryData);
+  if (fields.length === 1) {
+    return queryData[fields[0]];
   }
-  return null;
+  return void 0;
 };
-const getBackoffDelay = (attempt, policy) => Math.min(policy.baseDelayMs * 2 ** attempt, policy.maxDelayMs);
-const applyJitter = (cap, policy) => policy.jitter === false ? cap : randomInt(0, cap + 1);
-const getRetryDelay = (error, rawError, attempt, policy) => {
-  if (attempt >= policy.maxRetries) {
-    return null;
-  }
-  if (error instanceof AniLinkApiError) {
-    if (error.status === 429) {
-      return getRetryAfterDelay(rawError) ?? applyJitter(getBackoffDelay(attempt, policy), policy);
-    }
-    if (policy.retryOnStatus.includes(error.status)) {
-      return applyJitter(getBackoffDelay(attempt, policy), policy);
-    }
-    return null;
-  }
-  if (error instanceof AniLinkNetworkError) {
-    if (error.code === AniLinkErrorCodes.ABORTED) {
-      return null;
-    }
-    if (policy.retryOnNetworkError) {
-      return applyJitter(getBackoffDelay(attempt, policy), policy);
-    }
+const unwrapGraphQLResponse = (response, headers) => {
+  const envelope = response;
+  if (Array.isArray(envelope?.errors) && envelope.errors.length > 0) {
+    throw new AniLinkGraphQLError(envelope.errors, envelope?.data, void 0, {
+      rateLimit: getRateLimitInfo(headers),
+      contentType: getResponseContentType(headers ?? {})
+    });
   }
-  return null;
+  const unwrapped = unwrapSingleRootField(response);
+  return unwrapped === void 0 ? response : unwrapped;
 };
-const sleep = (ms, signal) => new Promise((resolve, reject) => {
-  const timeout = setTimeout(() => {
-    signal?.removeEventListener("abort", abort);
-    resolve();
-  }, ms);
-  const abort = () => {
-    clearTimeout(timeout);
-    reject(
-      new AniLinkNetworkError(AniLinkErrorCodes.ABORTED, "The request was cancelled.")
-    );
-  };
-  if (signal?.aborted) {
-    abort();
-    return;
-  }
-  signal?.addEventListener("abort", abort, { once: true });
-});
-const safeInvoke = (hook, name, ...args) => {
+
+const safeInvoke = (hook, name, onHookError, ...args) => {
   if (hook === void 0) {
     return;
   }
   try {
     hook(...args);
   } catch (hookError) {
+    if (onHookError !== void 0) {
+      try {
+        onHookError(name, hookError);
+      } catch {
+      }
+      return;
+    }
+    const firstArg = args[0];
+    const requestId = firstArg !== null && typeof firstArg === "object" && "requestId" in firstArg && typeof firstArg.requestId === "string" ? firstArg.requestId : void 0;
+    const correlation = requestId === void 0 ? "" : ` (requestId: ${requestId})`;
     console.warn(
-      `[AniLink] ${name} hook threw and was ignored:`,
+      `[AniLink] ${name} hook threw and was ignored${correlation}:`,
       hookError instanceof Error ? hookError.message : 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,
+      normalized,
+      context
+    );
+    return;
+  }
+  safeInvoke(resolved.onError, "onError", resolved.onHookError, normalized, context);
+};
+
 const circuitStates = /* @__PURE__ */ new WeakMap();
-const circuitScopeOf = (url) => {
+const isAvailabilityFailure = (error) => {
+  if (error instanceof AniLinkNetworkError) {
+    return error.code !== AniLinkErrorCodes.ABORTED;
+  }
+  if (error instanceof AniLinkApiError) {
+    return error.status === 429 || error.status >= 500;
+  }
+  return false;
+};
+const MAX_CIRCUIT_SCOPES_PER_OWNER = 64;
+const circuitScopeOf = (url, requestId) => {
   try {
     return new URL(url).host;
   } catch {
-    return "";
+    const error = new AniLinkValidationError(["Unparseable request URL"]);
+    stampRequestId(error, requestId);
+    throw error;
   }
 };
 const getCircuitState = (owner, scope) => {
@@ -355,67 +630,178 @@ const getCircuitState = (owner, scope) => {
     circuitStates.set(owner, scopes);
   }
   let state = scopes.get(scope);
-  if (state === void 0) {
-    state = { consecutiveFailures: 0, openedAt: null };
+  if (state !== void 0) {
+    scopes.delete(scope);
     scopes.set(scope, state);
+    return state;
   }
+  if (scopes.size >= MAX_CIRCUIT_SCOPES_PER_OWNER) {
+    const oldestScope = scopes.keys().next().value;
+    if (oldestScope !== void 0) {
+      scopes.delete(oldestScope);
+    }
+  }
+  state = {
+    consecutiveFailures: 0,
+    openedAt: null,
+    probeInFlight: false
+  };
+  scopes.set(scope, state);
   return state;
 };
-const throwIfCircuitOpen = (circuit, breaker) => {
-  if (circuit === void 0 || breaker === void 0 || circuit.openedAt === null) {
-    return;
+const checkCircuitOpen = (circuit, breaker) => {
+  if (circuit === void 0 || breaker === void 0) {
+    return void 0;
+  }
+  if (circuit.probeInFlight) {
+    return new AniLinkNetworkError(
+      AniLinkErrorCodes.CIRCUIT,
+      `The request failed fast: the circuit breaker is probing the upstream after ${breaker.threshold} consecutive failures. Retrying is possible once the probe settles.`
+    );
+  }
+  if (circuit.openedAt === null) {
+    return void 0;
   }
   if (Date.now() - circuit.openedAt < breaker.cooldownMs) {
-    throw new AniLinkNetworkError(
+    return new AniLinkNetworkError(
       AniLinkErrorCodes.CIRCUIT,
       `The request failed fast: the circuit breaker is open after ${breaker.threshold} consecutive failures. Retrying is possible after the cooldown elapses.`
     );
   }
   circuit.openedAt = null;
+  circuit.probeInFlight = true;
+  return void 0;
 };
-const recordCircuitSuccess = (circuit) => {
-  if (circuit !== void 0) {
-    circuit.consecutiveFailures = 0;
+const recordCircuitSuccess = (circuit, resolved, hookContext, host) => {
+  if (circuit === void 0) {
+    return;
+  }
+  const wasOpen = circuit.openedAt !== null || circuit.probeInFlight;
+  circuit.probeInFlight = false;
+  circuit.consecutiveFailures = 0;
+  circuit.openedAt = null;
+  if (wasOpen && resolved.onCircuitClose !== void 0) {
+    safeInvoke(resolved.onCircuitClose, "onCircuitClose", resolved.onHookError, {
+      ...hookContext,
+      host
+    });
   }
 };
-const recordCircuitFailure = (circuit, breaker) => {
+const recordCircuitFailure = (circuit, breaker, normalized, resolved, hookContext, host) => {
   if (circuit === void 0 || breaker === void 0) {
     return;
   }
+  if (!isAvailabilityFailure(normalized)) {
+    recordCircuitSuccess(circuit, resolved, hookContext, host);
+    return;
+  }
+  if (circuit.probeInFlight) {
+    circuit.probeInFlight = false;
+    circuit.openedAt = Date.now();
+    return;
+  }
   circuit.consecutiveFailures += 1;
-  if (circuit.consecutiveFailures >= breaker.threshold) {
+  if (circuit.consecutiveFailures >= breaker.threshold && circuit.openedAt === null) {
     circuit.openedAt = Date.now();
+    if (resolved.onCircuitOpen !== void 0) {
+      safeInvoke(resolved.onCircuitOpen, "onCircuitOpen", resolved.onHookError, {
+        ...hookContext,
+        host,
+        failures: circuit.consecutiveFailures
+      });
+    }
   }
 };
-const buildErrorContext = (url, method, attempt, normalized, nextDelayMs) => ({
-  url,
-  method,
-  attempt,
-  code: normalized.code,
-  ...normalized instanceof AniLinkApiError ? { status: normalized.status } : {},
-  ...nextDelayMs === void 0 ? {} : { nextDelayMs }
+
+const sleep = (ms, signal, requestId) => new Promise((resolve, reject) => {
+  const timeout = setTimeout(() => {
+    signal?.removeEventListener("abort", abort);
+    resolve();
+  }, ms);
+  timeout.unref();
+  const abort = () => {
+    clearTimeout(timeout);
+    const error = new AniLinkNetworkError(
+      AniLinkErrorCodes.ABORTED,
+      "The request was cancelled."
+    );
+    stampRequestId(error, requestId);
+    reject(error);
+  };
+  if (signal?.aborted) {
+    abort();
+    return;
+  }
+  signal?.addEventListener("abort", abort, { once: true });
 });
-const paceAfterSuccess = async (response, resolved) => {
-  if (!resolved.paceWithRateLimit) {
+
+const paceDeadlines = /* @__PURE__ */ new WeakMap();
+const MAX_PACE_WAIT_MS = 5 * 60 * 1e3;
+const sleepForPacing = async (delayMs, resolved, hookContext) => {
+  try {
+    await sleep(delayMs, resolved.signal, hookContext.requestId);
+  } catch (error) {
+    if (error instanceof AniLinkNetworkError && error.code === AniLinkErrorCodes.ABORTED && !axios.isCancel(error)) {
+      const pacingError = new AniLinkNetworkError(
+        AniLinkErrorCodes.ABORTED,
+        "The request was cancelled while waiting for the rate-limit window to reset.",
+        void 0,
+        { abortedDuringPacing: true }
+      );
+      stampRequestId(pacingError, hookContext.requestId);
+      throw pacingError;
+    }
+    throw error;
+  }
+};
+const recordPaceDeadline = (owner, host, deadlineMs) => {
+  let scopes = paceDeadlines.get(owner);
+  if (scopes === void 0) {
+    scopes = /* @__PURE__ */ new Map();
+    paceDeadlines.set(owner, scopes);
+  }
+  if (deadlineMs <= Date.now()) {
+    scopes.delete(host);
     return;
   }
-  const info = getRateLimitInfo(response.headers);
-  if (info !== void 0 && info.remaining < resolved.rateLimitFloor) {
-    await sleep(Math.max(0, info.reset * 1e3 - Date.now()), resolved.signal);
+  const existing = scopes.get(host);
+  if (existing !== void 0 && deadlineMs <= existing) {
+    return;
   }
+  scopes.set(host, deadlineMs);
 };
-const reportFailure = (url, method, attempt, normalized, resolved, nextDelayMs) => {
-  const context = buildErrorContext(url, method, attempt, normalized, nextDelayMs);
-  if (nextDelayMs !== void 0) {
-    safeInvoke(
-      resolved.onRetry ?? resolved.onError,
-      resolved.onRetry === void 0 ? "onError" : "onRetry",
-      normalized,
-      context
-    );
+const awaitPaceDeadline = async (owner, host, resolved, hookContext) => {
+  if (owner === void 0 || !resolved.paceWithRateLimit || resolved.ignorePaceDeadline) {
+    return;
+  }
+  const deadlineMs = paceDeadlines.get(owner)?.get(host);
+  if (deadlineMs === void 0) {
+    return;
+  }
+  const delayMs = deadlineMs - Date.now();
+  if (delayMs <= 0) {
+    paceDeadlines.get(owner)?.delete(host);
     return;
   }
-  safeInvoke(resolved.onError, "onError", normalized, context);
+  safeInvoke(resolved.onPace, "onPace", resolved.onHookError, { ...hookContext, delayMs });
+  await sleepForPacing(delayMs, resolved, hookContext);
+};
+const paceAfterSuccess = async (response, resolved, hookContext, 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 now = Date.now();
+    const deadlineMs = Math.min(rawDeadlineMs, now + MAX_PACE_WAIT_MS);
+    const delayMs = Math.max(0, deadlineMs - now);
+    if (owner !== void 0 && host !== void 0) {
+      recordPaceDeadline(owner, host, deadlineMs);
+    }
+    safeInvoke(resolved.onPace, "onPace", resolved.onHookError, { ...hookContext, delayMs });
+    await sleepForPacing(delayMs, resolved, hookContext);
+  }
 };
 const isPacingAbort = (resolved, error) => resolved.paceWithRateLimit && error instanceof AniLinkNetworkError && error.code === AniLinkErrorCodes.ABORTED && !axios.isCancel(error);
 const rethrowIfPacingAbort = (resolved, error) => {
@@ -423,16 +809,46 @@ const rethrowIfPacingAbort = (resolved, error) => {
     throw error;
   }
 };
-const executeWithRetry = async (options, resolved, stateKey, rawPassthrough = false) => {
+
+const executeWithRetry = async (options, resolved, stateOwner, rawPassthrough = false) => {
   const { url, method, data, headers } = options;
   const policy = resolved.retry;
-  const circuit = resolved.circuitBreaker !== void 0 && stateKey !== void 0 ? getCircuitState(stateKey, circuitScopeOf(url)) : void 0;
+  const requestId = randomUUID();
+  const host = circuitScopeOf(url, requestId);
+  const circuit = resolved.circuitBreaker !== void 0 && stateOwner !== void 0 ? getCircuitState(stateOwner, host) : void 0;
+  const budgetState = getRetryBudgetState(stateOwner, resolved.retryBudget);
   let attempt = 0;
   for (; ; ) {
-    throwIfCircuitOpen(circuit, resolved.circuitBreaker);
     const startedAt = Date.now();
-    const hookContext = { url, method, attempt: attempt + 1 };
-    safeInvoke(resolved.onRequestStart, "onRequestStart", hookContext);
+    const hookContext = { requestId, url, method, attempt: attempt + 1 };
+    const circuitError = checkCircuitOpen(circuit, resolved.circuitBreaker);
+    if (circuitError !== void 0) {
+      safeInvoke(
+        resolved.onRequestStart,
+        "onRequestStart",
+        resolved.onHookError,
+        hookContext
+      );
+      stampRequestId(circuitError, requestId);
+      safeInvoke(
+        resolved.onError,
+        "onError",
+        resolved.onHookError,
+        circuitError,
+        buildErrorContext(requestId, url, method, attempt + 1, circuitError)
+      );
+      throw circuitError;
+    }
+    try {
+      await awaitPaceDeadline(stateOwner, host, resolved, hookContext);
+    } catch (paceError) {
+      if (circuit !== void 0 && circuit.probeInFlight) {
+        recordCircuitSuccess(circuit, resolved, hookContext, host);
+      }
+      throw paceError;
+    }
+    safeInvoke(resolved.onRequestStart, "onRequestStart", resolved.onHookError, hookContext);
+    let responseReported = false;
     try {
       const response = await axiosClient({
         url,
@@ -440,50 +856,162 @@ const executeWithRetry = async (options, resolved, stateKey, rawPassthrough = fa
         data,
         headers,
         timeout: resolved.timeout,
-        signal: resolved.signal
+        signal: resolved.signal,
+        httpAgent: resolved.httpAgent,
+        httpsAgent: resolved.httpsAgent
       });
-      safeInvoke(resolved.onResponse, "onResponse", {
+      const rateLimit = getRateLimitInfo(response.headers);
+      safeInvoke(resolved.onResponse, "onResponse", resolved.onHookError, {
         ...hookContext,
-        durationMs: Date.now() - startedAt
+        durationMs: Date.now() - startedAt,
+        ...rateLimit !== void 0 ? { rateLimit } : {}
       });
-      recordCircuitSuccess(circuit);
-      await paceAfterSuccess(response, resolved);
-      return rawPassthrough ? response.data : unwrapGraphQLResponse(response.data);
+      responseReported = true;
+      const result = rawPassthrough ? response.data : unwrapGraphQLResponse(
+        response.data,
+        response.headers
+      );
+      recordCircuitSuccess(circuit, resolved, hookContext, host);
+      await paceAfterSuccess(response, resolved, hookContext, rateLimit, stateOwner, host);
+      return result;
     } catch (error) {
       rethrowIfPacingAbort(resolved, error);
-      safeInvoke(resolved.onResponse, "onResponse", {
-        ...hookContext,
-        durationMs: Date.now() - startedAt
+      if (!responseReported) {
+        safeInvoke(resolved.onResponse, "onResponse", resolved.onHookError, {
+          ...hookContext,
+          durationMs: Date.now() - startedAt
+        });
+      }
+      const normalized = normalizeRequestError(resolved, error, rawPassthrough, requestId);
+      const wasProbe = circuit?.probeInFlight === true;
+      recordCircuitFailure(
+        circuit,
+        resolved.circuitBreaker,
+        normalized,
+        resolved,
+        hookContext,
+        host
+      );
+      const delay = computeNextRetryDelay({
+        normalized,
+        rawError: error,
+        attempt,
+        policy,
+        budgetState,
+        budget: resolved.retryBudget,
+        wasProbe
       });
-      const normalized = normalizeRequestError(resolved, error);
-      recordCircuitFailure(circuit, resolved.circuitBreaker);
-      const delay = policy === null ? null : getRetryDelay(normalized, error, attempt, policy);
-      reportFailure(url, method, attempt + 1, normalized, resolved, delay ?? void 0);
+      if (delay !== null && budgetState !== void 0) {
+        budgetState.retriesUsed += 1;
+      }
+      reportFailure(
+        requestId,
+        url,
+        method,
+        attempt + 1,
+        normalized,
+        resolved,
+        delay ?? void 0
+      );
       if (delay === null) {
         throw normalized;
       }
       attempt += 1;
-      await sleep(delay, resolved.signal);
+      await sleep(delay, resolved.signal, requestId);
     }
   }
 };
-const sendRequest = async (url, method, data, token, requiresAuth = false, options, operation, contentType) => {
-  if (requiresAuth && (token === null || token === void 0 || token === "")) {
+const buildAuthCacheKey = (token) => token === void 0 ? "none" : `bearer:${createHash("sha256").update(token).digest("hex").slice(0, 16)}`;
+const buildCacheAuthKey = (hasBearerToken, hasCredentialHeaders, token) => {
+  if (hasCredentialHeaders) {
+    return void 0;
+  }
+  if (hasBearerToken) {
+    return buildAuthCacheKey(token);
+  }
+  return buildAuthCacheKey(void 0);
+};
+let warnedOptionsKeyedState = false;
+const warnOptionsKeyedState = (onHookError) => {
+  if (warnedOptionsKeyedState) {
+    return;
+  }
+  warnedOptionsKeyedState = true;
+  const message = "[AniLink] circuit-breaker/retry-budget state is keyed by the per-request options object because no stateOwner was passed. Pass a stable stateOwner (or reuse one options object across calls) so failure streaks accumulate.";
+  if (onHookError !== void 0) {
+    try {
+      onHookError("stateOwner", new Error(message));
+    } catch {
+    }
+    return;
+  }
+  console.warn(message);
+};
+const sendRequest = async (url, method, data, auth, sendOptions) => {
+  const {
+    requiresAuth = false,
+    options,
+    operation,
+    protocol,
+    contentType,
+    stateOwner
+  } = sendOptions ?? {};
+  const isRestCall = protocol === "rest" || protocol === void 0 && contentType !== void 0;
+  const resolvedAuth = typeof auth === "string" ? { token: auth } : auth;
+  const hasBearerToken = resolvedAuth?.token !== void 0 && resolvedAuth.token !== "";
+  const hasAuthorizationHeader = Object.entries(resolvedAuth?.headers ?? {}).some(
+    ([key, value]) => key.toLowerCase() === "authorization" && value !== ""
+  );
+  const hasCredentialHeaders = Object.entries(resolvedAuth?.headers ?? {}).some(
+    ([, value]) => value !== ""
+  );
+  const hasAuthMaterial = hasBearerToken || hasAuthorizationHeader;
+  if (requiresAuth && !hasAuthMaterial) {
     throw new AniLinkAuthError(operation);
   }
   const headers = contentType === void 0 ? {
     "Content-Type": "application/json",
     Accept: "application/json"
   } : { "Content-Type": contentType };
-  if (token !== null && token !== void 0 && token !== "") {
-    headers.Authorization = `Bearer ${token}`;
+  Object.assign(headers, resolvedAuth?.headers);
+  if (hasBearerToken && !hasAuthorizationHeader) {
+    headers.Authorization = `Bearer ${resolvedAuth.token}`;
+  }
+  const resolved = resolveRequestOptions(options);
+  if (stateOwner === void 0 && options !== void 0 && (resolved.circuitBreaker !== void 0 || resolved.retryBudget !== void 0)) {
+    warnOptionsKeyedState(resolved.onHookError);
+  }
+  const cacheEnabled = resolved.responseCache !== void 0 && method === "GET";
+  const cacheAuthKey = cacheEnabled ? buildCacheAuthKey(hasBearerToken, hasCredentialHeaders, resolvedAuth?.token) : void 0;
+  const cacheActive = cacheEnabled && cacheAuthKey !== void 0;
+  if (cacheActive) {
+    const cached = resolved.responseCache.get(method, url, data, cacheAuthKey);
+    if (cached !== void 0) {
+      const requestId = randomUUID();
+      const hookContext = { requestId, url, method, attempt: 1 };
+      safeInvoke(
+        resolved.onRequestStart,
+        "onRequestStart",
+        resolved.onHookError,
+        hookContext
+      );
+      safeInvoke(resolved.onResponse, "onResponse", resolved.onHookError, {
+        ...hookContext,
+        durationMs: 0,
+        cacheHit: true
+      });
+      return cached;
+    }
   }
   const result = await executeWithRetry(
     { url, method, data, headers },
-    resolveRequestOptions(options),
-    options,
-    contentType !== void 0
+    resolved,
+    stateOwner ?? options,
+    isRestCall
   );
+  if (cacheActive) {
+    resolved.responseCache.set(method, url, data, cacheAuthKey, result);
+  }
   return result;
 };
 
@@ -497,10 +1025,17 @@ const resolveOperationLabel = (operation) => {
   return typeof name === "string" && name.length > 0 ? name : void 0;
 };
 class BaseOperation {
+  /**
+   * Stable per-instance object keying cross-request transport state (the
+   * circuit breaker and retry budget). One per instance so failure streaks
+   * accumulate across every request this operation dispatches, regardless
+   * of per-request option objects.
+   */
+  stateOwner = {};
   /**
    * The authentication token shared by all operations of an instance.
    */
-  authToken;
+  requestAuth;
   /**
    * The transport settings resolved at construction time.
    */
@@ -508,21 +1043,33 @@ class BaseOperation {
   /**
    * Constructs a new `BaseOperation` instance.
    *
-   * @param authToken - The authentication token used for API requests.
+   * @param authToken - The authentication material used for API requests. A string is treated as a bearer token for backwards compatibility.
    * @param options - Transport settings scoped to this instance (timeout, cancellation, retry policy, lifecycle hooks).
    */
   constructor(authToken, options) {
-    this.authToken = authToken;
+    this.requestAuth = authToken;
     this.resolvedOptions = options;
   }
   /**
    * The instance authentication token, readable by protocol subclasses.
+   *
+   * @returns The bearer token from {@link RequestAuthInput}, or `undefined`.
    */
   get token() {
-    return this.authToken;
+    return typeof this.requestAuth === "string" ? this.requestAuth : this.requestAuth?.token;
+  }
+  /**
+   * The provider-specific authentication material, readable by protocol subclasses.
+   *
+   * @returns The configured {@link RequestAuthInput}, or `undefined`.
+   */
+  get auth() {
+    return this.requestAuth;
   }
   /**
    * The instance transport settings, readable by protocol subclasses.
+   *
+   * @returns The configured {@link RequestOptions}, or `undefined`.
    */
   get instanceOptions() {
     return this.resolvedOptions;
@@ -538,25 +1085,24 @@ class BaseOperation {
    * @typeParam T - The parsed response type returned verbatim by the pipeline.
    * @param url - The absolute endpoint URL to call.
    * @param method - The HTTP method for the call.
-   * @param data - The request body payload, when the call carries one.
-   * @param requiresAuth - Whether the operation requires an authentication token.
-   * @param operation - Human-readable operation name included in missing-token auth errors. Defaults to the concrete subclass name.
-   * @param transportOptions - Optional per-request transport settings merged over the instance-level ones. A field set here wins; unset fields keep the instance value.
-   * @param contentType - Optional `Content-Type` override. When provided, the response body is returned verbatim instead of being unwrapped as a GraphQL envelope.
+   * @param data - The request body payload, when the call carries one: a JSON-serializable object, or a pre-encoded string body (for example form-urlencoded OAuth grants).
+   * @param options - Named trailing options; see {@link DispatchOptions}.
    * @returns Whatever the shared pipeline resolves for the call.
-   * @throws An `AniLinkAuthError` when `requiresAuth` is true and no token is set, or a normalized `AniLinkError` when the request fails.
+   * @throws An {@link AniLinkAuthError} when `requiresAuth` is true and no token is set, or a normalized {@link AniLinkError} when the request fails.
    */
-  async dispatch(url, method, data, requiresAuth = false, operation, transportOptions, contentType) {
-    return await sendRequest(
-      url,
-      method,
-      data,
-      this.authToken,
-      requiresAuth || void 0,
-      mergeOptions(this.resolvedOptions, transportOptions),
-      operation ?? resolveOperationLabel(this),
-      contentType
-    );
+  async dispatch(url, method, data, options = {}) {
+    const { requiresAuth, operation, transportOptions, contentType, protocol } = options;
+    return await sendRequest(url, method, data, this.requestAuth, {
+      requiresAuth: requiresAuth || void 0,
+      options: mergeOptions(this.resolvedOptions, transportOptions),
+      operation: operation ?? resolveOperationLabel(this),
+      contentType,
+      protocol,
+      // The instance keys cross-request transport state (circuit
+      // breaker, retry budget) so failure streaks accumulate across
+      // requests even when each call carries fresh per-request options.
+      stateOwner: this.stateOwner
+    });
   }
 }
 
@@ -565,12 +1111,42 @@ const isPrimitive = (mapping) => typeof mapping === "string" && PRIMITIVES.inclu
 const isArrayType = (mapping) => typeof mapping === "string" && mapping.endsWith("[]");
 const isAllowlist = (mapping) => Array.isArray(mapping);
 const isObjectMapping = (mapping) => typeof mapping === "object" && mapping !== null && !Array.isArray(mapping);
-const describeValue = (value) => {
+const SENSITIVE_KEY_PATTERN = /token|secret|password|authorization|cookie|credential|api[-_]?key|pass|session|otp|bearer/i;
+const isPlainObject$1 = (value) => {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+const redactValue = (key, value) => {
+  if (SENSITIVE_KEY_PATTERN.test(key)) {
+    return "[REDACTED]";
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactValue(key, item));
+  }
+  if (value !== null && typeof value === "object" && !isPlainObject$1(value)) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) {
+      return value;
+    }
+    return Object.assign(
+      Object.create(Object.getPrototypeOf(value)),
+      Object.fromEntries(entries.map(([k, v]) => [k, redactValue(k, v)]))
+    );
+  }
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactValue(k, v)]));
+  }
+  return value;
+};
+const describeValue = (path, value) => {
+  if (SENSITIVE_KEY_PATTERN.test(path)) {
+    return "[REDACTED]";
+  }
   if (value === null || typeof value !== "object" && typeof value !== "function") {
     return String(value);
   }
   try {
-    return JSON.stringify(value) ?? String(value);
+    return JSON.stringify(redactValue(path, value)) ?? String(value);
   } catch {
     return `[${typeof value}]`;
   }
@@ -578,14 +1154,18 @@ const describeValue = (value) => {
 const validateValue = (path, value, mapping, errors, rejectUnknownKeys) => {
   if (isPrimitive(mapping)) {
     if (typeof value !== mapping) {
-      errors.push(`Invalid ${path}: ${describeValue(value)}. Expected type: ${mapping}`);
+      errors.push(
+        `Invalid ${path}: ${describeValue(path, value)}. Expected type: ${mapping}`
+      );
     }
     return;
   }
   if (isArrayType(mapping)) {
     const elementType = mapping.slice(0, -2);
     if (!Array.isArray(value) || !value.every((element) => typeof element === elementType)) {
-      errors.push(`Invalid ${path}: ${describeValue(value)}. Expected type: ${mapping}`);
+      errors.push(
+        `Invalid ${path}: ${describeValue(path, value)}. Expected type: ${mapping}`
+      );
     }
     return;
   }
@@ -594,13 +1174,13 @@ const validateValue = (path, value, mapping, errors, rejectUnknownKeys) => {
       value.forEach((item, index) => {
         if (!mapping.includes(item)) {
           errors.push(
-            `Invalid ${path}[${index}]: ${describeValue(item)}. Expected one of: ${mapping.join(", ")}`
+            `Invalid ${path}[${index}]: ${describeValue(`${path}[${index}]`, item)}. Expected one of: ${mapping.join(", ")}`
           );
         }
       });
     } else if (!mapping.includes(value)) {
       errors.push(
-        `Invalid ${path}: ${describeValue(value)}. Expected one of: ${mapping.join(", ")}`
+        `Invalid ${path}: ${describeValue(path, value)}. Expected one of: ${mapping.join(", ")}`
       );
     }
     return;
@@ -617,7 +1197,7 @@ const validateValue = (path, value, mapping, errors, rejectUnknownKeys) => {
 };
 const validateObject = (path, value, mapping, errors, rejectUnknownKeys) => {
   if (value === null || typeof value !== "object") {
-    errors.push(`Invalid ${path}: ${describeValue(value)}. Expected an object.`);
+    errors.push(`Invalid ${path}: ${describeValue(path, value)}. Expected an object.`);
     return;
   }
   for (const [prop, propValue] of Object.entries(value)) {
@@ -686,22 +1266,18 @@ class GraphQLOperation extends BaseOperation {
    *
    * @param query - The GraphQL document to execute.
    * @param variables - The variables for the document. When omitted the request body contains only the query.
-   * @param requiresAuth - Whether the operation requires an authentication token.
-   * @param operation - Optional human-readable operation name included in missing-token auth errors. Defaults to the concrete operation class name.
-   * @param transportOptions - Optional per-request transport settings merged over the instance-level ones. A field set here wins; unset fields keep the instance value.
+   * @param options - Named trailing options; see {@link GraphQLRequestOptions}.
    * @returns The unwrapped response data. For documents with a single root field this is the bare field value; otherwise it is the full `{ data }` envelope.
-   * @throws An `AniLinkAuthError` when `requiresAuth` is true and no token is set, or a normalized `AniLinkError` when the request fails.
+   * @throws An {@link AniLinkAuthError} when `requiresAuth` is true and no token is set, or a normalized {@link AniLinkError} when the request fails.
    */
-  async request(query, variables, requiresAuth = false, operation, transportOptions) {
+  async request(query, variables, options = {}) {
+    const { requiresAuth, operation, transportOptions } = options;
     const data = variables === void 0 ? { query } : { query, variables };
-    return await this.dispatch(
-      this.graphqlUrl,
-      "POST",
-      data,
+    return await this.dispatch(this.graphqlUrl, "POST", data, {
       requiresAuth,
       operation,
       transportOptions
-    );
+    });
   }
   /**
    * Runs the shared validate-then-dispatch pipeline for an operation.
@@ -717,7 +1293,7 @@ class GraphQLOperation extends BaseOperation {
    * @param options - The declarative validation and auth contract.
    * @returns The unwrapped response data, as described by {@link GraphQLOperation.request}.
    * @throws An {@link AniLinkValidationError} when a requirement or type check
-   * fails, or a normalized `AniLinkError` when the request fails.
+   * fails, or a normalized {@link AniLinkError} when the request fails.
    */
   async execute(query, variables, options) {
     const { requirements, mappings, requiresAuth, transportOptions } = options;
@@ -729,7 +1305,7 @@ class GraphQLOperation extends BaseOperation {
     if (mappings && variables !== void 0) {
       validateVariables(variables, mappings);
     }
-    return await this.request(query, variables, requiresAuth, void 0, transportOptions);
+    return await this.request(query, variables, { requiresAuth, transportOptions });
   }
 }
 
@@ -766,8 +1342,8 @@ class CustomRequest extends AniListOperation {
    * @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 `AniLinkValidationError` when the query is empty or does not declare a `query` or `mutation` operation.
-   * @throws An `AniLinkError` when the request fails.
+   * @throws An {@link AniLinkValidationError} when the query is empty or does not declare a `query` or `mutation` operation.
+   * @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
    */
@@ -777,7 +1353,7 @@ class CustomRequest extends AniListOperation {
         "custom() requires a GraphQL document declaring a query or mutation operation"
       ]);
     }
-    return await this.request(query, variables, false, void 0, options);
+    return await this.request(query, variables, { transportOptions: options });
   }
 }
 
@@ -836,34 +1412,70 @@ function resolvePositiveInt(value, fallback) {
 function resolveCappedInt(value, max, fallback) {
   return Math.min(resolvePositiveInt(value, fallback), max);
 }
-async function fetchWithLookAhead(fetch, extractHasMore, ...rest) {
-  let extractNextKey;
-  let firstKey;
-  let numericStart;
-  let maxEntries;
-  let concurrency;
-  if (rest.length === 4) {
-    [extractNextKey, firstKey, maxEntries, concurrency] = rest;
-    if (extractNextKey === void 0) {
-      numericStart = firstKey;
-    }
-  } else {
-    [numericStart, maxEntries, concurrency] = rest;
-    firstKey = numericStart;
+function bridgeAbortSignal(external) {
+  const controller = new AbortController();
+  if (external === void 0) {
+    return { signal: controller.signal, dispose: () => controller.abort() };
+  }
+  if (external.aborted) {
+    controller.abort();
+    return { signal: controller.signal, dispose: () => {
+    } };
+  }
+  const onAbort = () => controller.abort();
+  external.addEventListener("abort", onAbort, { once: true });
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      controller.abort();
+      external.removeEventListener("abort", onAbort);
+    }
+  };
+}
+async function fetchWithLookAhead(fetch, extractHasMore, extractNextKeyOrStartNumber, firstKeyOrMaxEntries, maxEntriesOrConcurrency, concurrencyOrSignal, maybeSignal) {
+  if (extractNextKeyOrStartNumber === void 0) {
+    return fetchNumericWithLookAhead(
+      fetch,
+      extractHasMore,
+      firstKeyOrMaxEntries,
+      maxEntriesOrConcurrency,
+      concurrencyOrSignal,
+      maybeSignal
+    );
+  }
+  if (typeof extractNextKeyOrStartNumber === "function") {
+    return fetchCursorChain(
+      fetch,
+      extractHasMore,
+      extractNextKeyOrStartNumber,
+      firstKeyOrMaxEntries,
+      maxEntriesOrConcurrency);
   }
+  return fetchNumericWithLookAhead(
+    fetch,
+    extractHasMore,
+    extractNextKeyOrStartNumber,
+    firstKeyOrMaxEntries,
+    maxEntriesOrConcurrency,
+    typeof concurrencyOrSignal === "number" ? void 0 : concurrencyOrSignal
+  );
+}
+async function fetchNumericWithLookAhead(fetch, extractHasMore, startNumber, maxEntries, concurrency, signal) {
   const responses = [];
   const pending = [];
   let launched = 0;
   let count = 0;
   let truncated = false;
-  let pendingCursorKey = extractNextKey === void 0 ? void 0 : firstKey;
-  const effectiveConcurrency = extractNextKey === void 0 ? concurrency : 1;
   while (count < maxEntries) {
-    while (launched < maxEntries && launched - count < effectiveConcurrency) {
+    if (signal?.aborted) {
+      await Promise.allSettled(pending.slice(count));
+      responses.length = count;
+      return { responses, count, truncated: false };
+    }
+    while (launched < maxEntries && launched - count < concurrency) {
       const slot = launched;
-      const key = extractNextKey === void 0 ? numericStart + slot : pendingCursorKey;
       launched += 1;
-      const request = fetch(key).then((response) => {
+      const request = fetch(startNumber + slot).then((response) => {
         responses[slot] = response;
       });
       pending[slot] = request;
@@ -871,18 +1483,22 @@ async function fetchWithLookAhead(fetch, extractHasMore, ...rest) {
       });
     }
     if (count >= launched) break;
-    await pending[count];
+    try {
+      await pending[count];
+    } catch (err) {
+      if (signal?.aborted) {
+        await Promise.allSettled(pending.slice(count + 1));
+        responses.length = count;
+        return { responses, count, truncated: false };
+      }
+      throw err;
+    }
     count += 1;
-    const consumed = responses[count - 1];
-    const hasMore = extractHasMore(consumed);
-    if (!hasMore) {
+    if (!extractHasMore(responses[count - 1])) {
       await Promise.allSettled(pending.slice(count));
       responses.length = count;
       return { responses, count, truncated: false };
     }
-    if (extractNextKey !== void 0) {
-      pendingCursorKey = extractNextKey(consumed);
-    }
     if (count >= maxEntries) {
       await Promise.allSettled(pending.slice(count));
       truncated = true;
@@ -891,6 +1507,32 @@ async function fetchWithLookAhead(fetch, extractHasMore, ...rest) {
   }
   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) {
+    let entry;
+    try {
+      entry = await fetch(key);
+    } catch (err) {
+      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
+  };
+}
 
 const DEFAULT_PER_PAGE = 50;
 const MAX_PER_PAGE = DEFAULT_PER_PAGE;
@@ -898,6 +1540,10 @@ const DEFAULT_MAX_PAGES = 100;
 const DEFAULT_PER_CHUNK = 500;
 const MAX_PER_CHUNK = DEFAULT_PER_CHUNK;
 const DEFAULT_MAX_CHUNKS = 100;
+const safeCallback = (callback, name, payload) => {
+  safeInvoke(callback, name, void 0, payload);
+};
+const DEFAULT_CONCURRENCY = 3;
 const MAX_CONCURRENCY = 8;
 function extractHasMore(response) {
   if (typeof response !== "object" || response === null) return false;
@@ -914,59 +1560,130 @@ async function paginate(fetchPage, itemsKey, options) {
   const perPage = resolveCappedInt(options?.perPage, MAX_PER_PAGE, DEFAULT_PER_PAGE);
   const startPage = resolvePositiveInt(options?.startPage, 1);
   const maxPages = resolvePositiveInt(options?.maxPages, DEFAULT_MAX_PAGES);
-  const concurrency = resolveCappedInt(options?.concurrency, MAX_CONCURRENCY, 1);
-  const { responses, count, truncated } = await fetchWithLookAhead(
-    (number) => fetchPage(number, perPage),
-    extractHasMore,
-    startPage,
-    maxPages,
-    concurrency
+  const concurrency = resolveCappedInt(
+    options?.concurrency,
+    MAX_CONCURRENCY,
+    DEFAULT_CONCURRENCY
   );
-  const items = [];
-  const pages = [];
-  for (const response of responses) {
-    const pageItems = response[itemsKey];
-    pages.push({ pageInfo: response.pageInfo, items: pageItems });
-    items.push(...pageItems);
-  }
-  return { items, pages, pageCount: count, truncated };
+  const { signal, dispose } = bridgeAbortSignal(options?.signal);
+  try {
+    const { responses, count, truncated } = await fetchWithLookAhead(
+      (number) => fetchPage(number, perPage, signal),
+      extractHasMore,
+      startPage,
+      maxPages,
+      concurrency,
+      signal
+    );
+    const items = [];
+    const pages = [];
+    for (const response of responses) {
+      const pageItems = response[itemsKey];
+      pages.push({ pageInfo: response.pageInfo, items: pageItems });
+      items.push(...pageItems);
+      safeCallback(options?.onPage, "onPage", {
+        pageInfo: response.pageInfo,
+        items: pageItems
+      });
+    }
+    return { items, pages, pageCount: count, truncated };
+  } finally {
+    dispose();
+  }
 }
 async function* paginatePages(fetchPage, options) {
   const perPage = resolveCappedInt(options?.perPage, MAX_PER_PAGE, DEFAULT_PER_PAGE);
   const startPage = resolvePositiveInt(options?.startPage, 1);
   const maxPages = resolvePositiveInt(options?.maxPages, DEFAULT_MAX_PAGES);
-  let page = startPage;
-  let pageCount = 0;
-  while (pageCount < maxPages) {
-    const response = await fetchPage(page, perPage);
-    pageCount += 1;
-    yield response;
-    if (!response.pageInfo.hasNextPage || pageCount >= maxPages) {
-      break;
+  const concurrency = resolveCappedInt(
+    options?.concurrency,
+    MAX_CONCURRENCY,
+    DEFAULT_CONCURRENCY
+  );
+  const { signal, dispose } = bridgeAbortSignal(options?.signal);
+  if (signal.aborted) {
+    dispose();
+    return;
+  }
+  const pending = /* @__PURE__ */ new Map();
+  let nextToLaunch = startPage;
+  let nextToYield = startPage;
+  let terminal = false;
+  const launchWindow = () => {
+    while (!terminal && nextToLaunch - startPage < maxPages && pending.size < concurrency) {
+      const page = nextToLaunch;
+      nextToLaunch += 1;
+      const request = fetchPage(page, perPage, signal);
+      pending.set(page, request);
+      void request.catch(() => {
+      });
     }
-    page += 1;
+  };
+  try {
+    while (nextToYield - startPage < maxPages) {
+      launchWindow();
+      const page = nextToYield;
+      const request = pending.get(page);
+      if (request === void 0) {
+        break;
+      }
+      let response;
+      try {
+        response = await request;
+      } catch (err) {
+        if (signal.aborted) {
+          break;
+        }
+        throw err;
+      }
+      pending.delete(page);
+      nextToYield += 1;
+      yield response;
+      if (!response.pageInfo.hasNextPage) {
+        terminal = true;
+        await Promise.allSettled([...pending.values()]);
+        break;
+      }
+    }
+  } finally {
+    dispose();
+    pending.clear();
   }
 }
 async function paginateChunks(fetchChunk, itemsKey, options) {
   const perChunk = resolveCappedInt(options?.perChunk, MAX_PER_CHUNK, DEFAULT_PER_CHUNK);
   const startChunk = resolvePositiveInt(options?.startChunk, 1);
   const maxChunks = resolvePositiveInt(options?.maxChunks, DEFAULT_MAX_CHUNKS);
-  const concurrency = resolveCappedInt(options?.concurrency, MAX_CONCURRENCY, 1);
-  const { responses, count, truncated } = await fetchWithLookAhead(
-    (number) => fetchChunk(number, perChunk),
-    extractHasMore,
-    startChunk,
-    maxChunks,
-    concurrency
+  const concurrency = resolveCappedInt(
+    options?.concurrency,
+    MAX_CONCURRENCY,
+    DEFAULT_CONCURRENCY
   );
-  const items = [];
-  const chunks = [];
-  for (const response of responses) {
-    const chunkItems = response[itemsKey];
-    chunks.push({ hasNextChunk: response.hasNextChunk, items: chunkItems });
-    items.push(...chunkItems);
-  }
-  return { items, chunks, chunkCount: count, truncated };
+  const { signal, dispose } = bridgeAbortSignal(options?.signal);
+  try {
+    const { responses, count, truncated } = await fetchWithLookAhead(
+      (number) => fetchChunk(number, perChunk, signal),
+      extractHasMore,
+      startChunk,
+      maxChunks,
+      concurrency,
+      signal
+    );
+    const items = [];
+    const chunks = [];
+    for (const response of responses) {
+      const chunkItems = response[itemsKey];
+      chunks.push({ hasNextChunk: response.hasNextChunk, items: chunkItems });
+      items.push(...chunkItems);
+      safeCallback(options?.onChunk, "onChunk", {
+        hasNextChunk: response.hasNextChunk,
+        items: chunkItems
+      });
+    }
+    return { items, chunks, chunkCount: count, truncated };
+  } finally {
+    dispose();
+  }
 }
 
 const MediaSortMappings = [
@@ -1635,12 +2352,16 @@ const ActivityMappings = {
 };
 class ActivityQuery extends AniListOperation {
   /**
-   * `activity` is a method that sends a query request to get activities.
+   * {@link ActivityQuery.activity} sends a query request to get activities.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link ActivityVariables} for the query.
+   * @returns The {@link Activity} returned by the query.
    * @see https://docs.anilist.co/reference/union/activityunion
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ActivityQuery().activity({ userId: 1 });
+   * ```
    */
   async activity(variables, options) {
     const query = `
@@ -1671,12 +2392,16 @@ const ActivityReplyMappings = {
 };
 class ActivityReplyQuery extends AniListOperation {
   /**
-   * `activityReply` is a method that sends a query request to get activity replies.
+   * {@link ActivityReplyQuery.activityReply} sends a query request to get activity replies.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link ActivityReplyVariables} for the query.
+   * @returns The {@link ActivityReply} returned by the query.
    * @see https://docs.anilist.co/reference/object/activityreply
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ActivityReplyQuery().activityReply({ activityId: 1 });
+   * ```
    */
   async activityReply(variables, options) {
     const query = `
@@ -1711,10 +2436,14 @@ class ActivityRepliesQuery extends AniListOperation {
   /**
    * `activityReplies` is a method that sends a query request to get activity replies.
    *
-   * @param variables - The variables for the query.
-   * @returns The activity replies for the requested page with pagination metadata.
+   * @param variables - Values from {@link ActivityRepliesVariables} for the query.
+   * @returns The {@link ActivityRepliesPageResponse} for the requested page, with pagination metadata.
    * @see https://docs.anilist.co/reference/object/activityreply
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ActivityRepliesQuery().activityReplies({ page: 1, perPage: 10 });
+   * ```
    */
   async activityReplies(variables, options) {
     const query = `
@@ -1775,10 +2504,14 @@ class ActivitiesQuery extends AniListOperation {
   /**
    * `activities` is a method that sends a query request to get activities.
    *
-   * @param variables - The variables for the query.
-   * @returns The activities for the requested page with pagination metadata.
+   * @param variables - Values from {@link ActivitiesVariables} for the query.
+   * @returns The {@link ActivitiesPageResponse} for the requested page, with pagination metadata.
    * @see https://docs.anilist.co/reference/union/activityunion
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ActivitiesQuery().activities({ page: 1, perPage: 10 });
+   * ```
    */
   async activities(variables, options) {
     const query = `
@@ -2142,12 +2875,16 @@ const AiringScheduleMappings = {
 };
 class AiringScheduleQuery extends AniListOperation {
   /**
-   * `airingSchedule` is a method that sends a query request to get airing schedules.
+   * {@link AiringScheduleQuery.airingSchedule} sends a query request to get airing schedules.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link AiringScheduleVariables} for the query.
+   * @returns The {@link AiringScheduleResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/airingschedule
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new AiringScheduleQuery().airingSchedule({ mediaId: 1 });
+   * ```
    */
   async airingSchedule(variables, options) {
     const query = `
@@ -2199,10 +2936,14 @@ class AiringSchedulesQuery extends AniListOperation {
   /**
    * `airingSchedules` is a method that sends a query request to get airing schedules.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link AiringSchedulesVariables} for the query.
+   * @returns The {@link AiringSchedulesPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/airingschedule
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new AiringSchedulesQuery().airingSchedules({ page: 1, perPage: 10 });
+   * ```
    */
   async airingSchedules(variables, options) {
     const query = `
@@ -2230,11 +2971,15 @@ class AiringSchedulesQuery extends AniListOperation {
 
 class AniChartUserQuery extends AniListOperation {
   /**
-   * `aniChartUser` is a method that sends a query request to get AniChart users.
+   * {@link AniChartUserQuery.aniChartUser} sends a query request to get AniChart users.
    *
-   * @returns The response from the query request.
+   * @returns The {@link AniChartUserResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/anichartuser
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new AniChartUserQuery("authToken").aniChartUser();
+   * ```
    */
   async aniChartUser(options) {
     const query = `
@@ -2295,12 +3040,16 @@ const CharacterMappings = {
 };
 class CharacterQuery extends AniListOperation {
   /**
-   * `character` is a method that sends a query request to get characters.
+   * {@link CharacterQuery.character} sends a query request to get characters.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link CharacterVariables} for the query.
+   * @returns The {@link CharacterResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/character
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new CharacterQuery().character({ id: 1 });
+   * ```
    */
   async character(variables, options) {
     const query = `
@@ -2337,10 +3086,14 @@ class CharactersQuery extends AniListOperation {
   /**
    * `characters` is a method that sends a query request to get characters.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link CharactersVariables} for the query.
+   * @returns The {@link CharactersPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/character
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new CharactersQuery().characters({ page: 1, perPage: 10 });
+   * ```
    */
   async characters(variables, options) {
     const query = `
@@ -2400,12 +3153,16 @@ const ExternalLinkSourceCollectionMappings = {
 };
 class ExternalLinkSourceCollectionQuery extends AniListOperation {
   /**
-   * `externalLinkSourceCollection` is a method that sends a query request to get external link source collections.
+   * {@link ExternalLinkSourceCollectionQuery.externalLinkSourceCollection} sends a query request to get external link source collections.
    *
-   * @param variables - The variables for the query. If not provided, an empty object will be used.
-   * @returns The response from the query request.
+   * @param variables - Optional values from {@link ExternalLinkSourceCollectionVariables}; defaults to an empty object.
+   * @returns The {@link ExternalLinkSourceCollectionResponse} returned by the query.
    * @see https://docs.anilist.co/reference/query
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ExternalLinkSourceCollectionQuery().externalLinkSourceCollection({});
+   * ```
    */
   async externalLinkSourceCollection(variables = {}, options) {
     const query = `
@@ -2818,12 +3575,16 @@ const FollowerMappings = {
 };
 class FollowerQuery extends AniListOperation {
   /**
-   * `follower` is a method that sends a query request to get followers.
+   * {@link FollowerQuery.follower} sends a query request to get followers.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link FollowerVariables} for the query.
+   * @returns The {@link UserResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/user
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new FollowerQuery().follower({ userId: 1 });
+   * ```
    */
   async follower(variables, options) {
     const query = `
@@ -2862,10 +3623,14 @@ class FollowersQuery extends AniListOperation {
   /**
    * `followers` is a method that sends a query request to get followers.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link FollowersVariables} for the query.
+   * @returns The {@link FollowersPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/user
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new FollowersQuery().followers({ userId: 1, page: 1, perPage: 10 });
+   * ```
    */
   async followers(variables, options) {
     const query = `
@@ -2909,12 +3674,16 @@ const FollowingMappings = {
 };
 class FollowingQuery extends AniListOperation {
   /**
-   * `following` is a method that sends a query request to get following users.
+   * {@link FollowingQuery.following} sends a query request to get following users.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link FollowingVariables} for the query.
+   * @returns The {@link UserResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/user
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new FollowingQuery().following({ userId: 1 });
+   * ```
    */
   async following(variables, options) {
     const query = `
@@ -2953,10 +3722,14 @@ class FollowingsQuery extends AniListOperation {
   /**
    * `followings` is a method that sends a query request to get followings.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link FollowingsVariables} for the query.
+   * @returns The {@link FollowingsPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/user
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new FollowingsQuery().followings({ userId: 1, page: 1, perPage: 10 });
+   * ```
    */
   async followings(variables, options) {
     const query = `
@@ -2991,11 +3764,15 @@ class FollowingsQuery extends AniListOperation {
 
 class GenreCollectionQuery extends AniListOperation {
   /**
-   * `genreCollection` is a method that sends a query request to get genre collections.
+   * {@link GenreCollectionQuery.genreCollection} sends a query request to get genre collections.
    *
-   * @returns The response from the query request.
+   * @returns The list of genre strings returned by AniList.
    * @see https://docs.anilist.co/reference/query
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const genres = await new GenreCollectionQuery().genreCollection();
+   * ```
    */
   async genreCollection(options) {
     const query = `
@@ -3017,10 +3794,14 @@ class LikesQuery extends AniListOperation {
   /**
    * `likes` is a method that sends a query request to get likes.
    *
-   * @param variables - The variables for the query.
-   * @returns The users who liked the item for the requested page, with pagination metadata.
+   * @param variables - Values from {@link LikesVariables} for the query.
+   * @returns The {@link LikesPageResponse} for the requested page, with pagination metadata.
    * @see https://docs.anilist.co/reference/union/likeableunion
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new LikesQuery().likes({ likeableId: 1, type: "ACTIVITY" });
+   * ```
    */
   async likes(variables, options) {
     const query = `
@@ -3055,12 +3836,16 @@ class LikesQuery extends AniListOperation {
 
 class MarkdownQuery extends AniListOperation {
   /**
-   * `markdown` is a method that sends a query request to convert Markdown text to HTML.
+   * {@link MarkdownQuery.markdown} sends a query request to convert Markdown text to HTML.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link MarkdownVariables} for the query.
+   * @returns The converted HTML string returned by AniList.
    * @see https://docs.anilist.co/reference/object/parsedmarkdown
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const html = await new MarkdownQuery().markdown({ markdown: "# AniList" });
+   * ```
    */
   async markdown(variables, options) {
     const query = `
@@ -3194,7 +3979,7 @@ const MediaListCollectionMappings = {
 };
 class MediaListCollectionQuery extends AniListOperation {
   /**
-   * `mediaListCollection` is a method that sends a query request to get media list collection data.
+   * {@link MediaListCollectionQuery.mediaListCollection} sends a query request to get media list collection data.
    *
    * Chunk semantics: AniList returns large user lists in chunks. Set `chunk` (1-based) and
    * `perChunk` (entries per chunk) to fetch a single chunk; the response's `hasNextChunk` flag
@@ -3212,10 +3997,17 @@ class MediaListCollectionQuery extends AniListOperation {
    * );
    * ```
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request, including `lists` and `hasNextChunk`.
+   * @param variables - Values from {@link MediaListCollectionVariables} for the query.
+   * @returns The {@link MediaListCollectionResponse} from the query request, including `lists` and `hasNextChunk`.
    * @see https://docs.anilist.co/reference/object/medialistcollection
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new MediaListCollectionQuery().mediaListCollection({
+   *     type: "ANIME",
+   *     userId: 1,
+   * });
+   * ```
    */
   async mediaListCollection(variables, options) {
     const query = MediaListCollectionQuerySchema;
@@ -3298,12 +4090,16 @@ const MediaListMappings = {
 };
 class MediaListQuery extends AniListOperation {
   /**
-   * `mediaList` is a method that sends a query request to get media list data.
+   * {@link MediaListQuery.mediaList} sends a query request to get media list data.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link MediaListVariables} for the query.
+   * @returns The {@link MediaListResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/medialist
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new MediaListQuery().mediaList({ id: 1 });
+   * ```
    */
   async mediaList(variables, options) {
     const query = `
@@ -3356,10 +4152,14 @@ class MediaListsQuery extends AniListOperation {
   /**
    * `mediaLists` is a method that sends a query request to get media lists.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link MediaListsVariables} for the query.
+   * @returns The {@link MediaListsPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/medialist
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new MediaListsQuery().mediaLists({ userId: 1, page: 1, perPage: 10 });
+   * ```
    */
   async mediaLists(variables, options) {
     const query = `
@@ -3487,12 +4287,16 @@ const MediaMappings = {
 };
 class MediaQuery extends AniListOperation {
   /**
-   * `media` is a method that sends a query request to get media data.
+   * {@link MediaQuery.media} sends a query request to get media data.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link MediaVariables} for the query.
+   * @returns The {@link MediaResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/media
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new MediaQuery().media({ id: 1 });
+   * ```
    */
   async media(variables, options) {
     const query = `
@@ -3521,12 +4325,16 @@ const MediaTagCollectionMappings = {
 };
 class MediaTagCollectionQuery extends AniListOperation {
   /**
-   * `mediaTagCollection` is a method that sends a query request to get media tag collection data.
+   * {@link MediaTagCollectionQuery.mediaTagCollection} sends a query request to get media tag collection data.
    *
-   * @param variables - The variables for the query. If not provided, an empty object will be used.
-   * @returns The response from the query request.
+   * @param variables - Optional values from {@link MediaTagCollectionVariables}; defaults to an empty object.
+   * @returns The {@link MediaTagCollectionResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/mediatag
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new MediaTagCollectionQuery().mediaTagCollection({});
+   * ```
    */
   async mediaTagCollection(variables = {}, options) {
     const query = `
@@ -3587,12 +4395,16 @@ const MediaTrendMappings = {
 };
 class MediaTrendQuery extends AniListOperation {
   /**
-   * `mediaTrend` is a method that sends a query request to get media trend data.
+   * {@link MediaTrendQuery.mediaTrend} sends a query request to get media trend data.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link MediaTrendVariables} for the query.
+   * @returns The {@link MediaTrendResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/mediatrend
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new MediaTrendQuery().mediaTrend({ mediaId: 1 });
+   * ```
    */
   async mediaTrend(variables, options) {
     const query = `
@@ -3650,10 +4462,14 @@ class MediaTrendsQuery extends AniListOperation {
   /**
    * `mediaTrends` is a method that sends a query request to get media trends.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link MediaTrendsVariables} for the query.
+   * @returns The {@link MediaTrendsPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/mediatrend
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new MediaTrendsQuery().mediaTrends({ mediaId: 1, page: 1, perPage: 10 });
+   * ```
    */
   async mediaTrends(variables, options) {
     const query = `
@@ -3755,11 +4571,15 @@ const MediasMappings = {
 };
 class MediasQuery extends AniListOperation {
   /**
-   * Returns a `MediaResponse` object.
-   * @param variables - A `MediasVariables` object representing the variables for the query.
-   * @returns A `MediaResponse` object.
+   * Returns a {@link MediasPageResponse} object.
+   * @param variables - Values from {@link MediasVariables} for the query.
+   * @returns The {@link MediasPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/media
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new MediasQuery().medias({ search: "Cowboy Bebop", page: 1 });
+   * ```
    */
   async medias(variables, options) {
     const query = `
@@ -3967,12 +4787,16 @@ const NotificationMappings = {
 };
 class NotificationQuery extends AniListOperation {
   /**
-   * `notification` is a method that sends a query request to get notification data.
+   * {@link NotificationQuery.notification} sends a query request to get notification data.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link NotificationVariables} for the query.
+   * @returns The {@link NotificationResponse} returned by the query.
    * @see https://docs.anilist.co/reference/union/notificationunion
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new NotificationQuery("authToken").notification({});
+   * ```
    */
   async notification(variables, options) {
     const query = `
@@ -4002,10 +4826,14 @@ class NotificationsQuery extends AniListOperation {
   /**
    * `notifications` is a method that sends a query request to get notifications.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link NotificationsVariables} for the query.
+   * @returns The {@link NotificationsPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/union/notificationunion
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new NotificationsQuery().notifications({ page: 1, perPage: 10 });
+   * ```
    */
   async notifications(variables, options) {
     const query = `
@@ -4060,12 +4888,16 @@ const RecommendationMappings = {
 };
 class RecommendationQuery extends AniListOperation {
   /**
-   * `recommendation` is a method that sends a query request to get recommendation data.
+   * {@link RecommendationQuery.recommendation} sends a query request to get recommendation data.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link RecommendationVariables} for the query.
+   * @returns The {@link RecommendationResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/recommendation
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new RecommendationQuery().recommendation({ mediaId: 1 });
+   * ```
    */
   async recommendation(variables, options) {
     const query = `
@@ -4107,10 +4939,14 @@ class RecommendationsQuery extends AniListOperation {
   /**
    * `recommendations` is a method that sends a query request to get recommendations.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link RecommendationsVariables} for the query.
+   * @returns The {@link RecommendationsPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/recommendation
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new RecommendationsQuery().recommendations({ mediaId: 1, page: 1 });
+   * ```
    */
   async recommendations(variables, options) {
     const query = `
@@ -4168,12 +5004,16 @@ const ReviewMappings = {
 };
 class ReviewQuery extends AniListOperation {
   /**
-   * `review` is a method that sends a query request to get review data.
+   * {@link ReviewQuery.review} sends a query request to get review data.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link ReviewVariables} for the query.
+   * @returns The {@link ReviewResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/review
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ReviewQuery().review({ mediaId: 1 });
+   * ```
    */
   async review(variables, options) {
     const query = `
@@ -4211,10 +5051,14 @@ class ReviewsQuery extends AniListOperation {
   /**
    * `reviews` is a method that sends a query request to get reviews.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link ReviewsVariables} for the query.
+   * @returns The {@link ReviewsPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/review
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ReviewsQuery().reviews({ mediaId: 1, page: 1 });
+   * ```
    */
   async reviews(variables, options) {
     const query = `
@@ -4312,12 +5156,16 @@ const SiteStatisticsMappings = {
 };
 class SiteStatisticsQuery extends AniListOperation {
   /**
-   * `siteStatistics` is a method that sends a query request to get site statistics data.
+   * {@link SiteStatisticsQuery.siteStatistics} sends a query request to get site statistics data.
    *
-   * @param variables - The variables for the query. If not provided, an empty object will be used.
-   * @returns The response from the query request.
+   * @param variables - Optional values from {@link SiteStatisticsVariables}; defaults to an empty object.
+   * @returns The {@link SiteStatisticsResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/sitestatistics
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new SiteStatisticsQuery().siteStatistics({});
+   * ```
    */
   async siteStatistics(variables = {}, options) {
     const query = `
@@ -4407,12 +5255,16 @@ const StaffMappings = {
 };
 class StaffQuery extends AniListOperation {
   /**
-   * `staff` is a method that sends a query request to get staff data.
+   * {@link StaffQuery.staff} sends a query request to get staff data.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link StaffVariables} for the query.
+   * @returns The {@link StaffResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/staff
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new StaffQuery().staff({ id: 1 });
+   * ```
    */
   async staff(variables, options) {
     const query = `
@@ -4457,10 +5309,14 @@ class StaffsQuery extends AniListOperation {
   /**
    * `staffs` is a method that sends a query request to get staffs.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link StaffsVariables} for the query.
+   * @returns The {@link StaffsPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/staff
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new StaffsQuery().staffs({ search: "Hayao Miyazaki", page: 1 });
+   * ```
    */
   async staffs(variables, options) {
     const query = `
@@ -4563,12 +5419,16 @@ const StudioMappings = {
 };
 class StudioQuery extends AniListOperation {
   /**
-   * `studio` is a method that sends a query request to get studio data.
+   * {@link StudioQuery.studio} sends a query request to get studio data.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link StudioVariables} for the query.
+   * @returns The {@link StudioResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/studio
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new StudioQuery().studio({ id: 1 });
+   * ```
    */
   async studio(variables, options) {
     const query = `
@@ -4617,10 +5477,14 @@ class StudiosQuery extends AniListOperation {
   /**
    * `studios` is a method that sends a query request to get studios.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link StudiosVariables} for the query.
+   * @returns The {@link StudiosPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/studio
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new StudiosQuery().studios({ search: "Bones", page: 1 });
+   * ```
    */
   async studios(variables, options) {
     const query = `
@@ -4714,12 +5578,16 @@ const ThreadCommentMappings = {
 };
 class ThreadCommentQuery extends AniListOperation {
   /**
-   * `threadComment` is a method that sends a query request to get thread comment data.
+   * {@link ThreadCommentQuery.threadComment} sends a query request to get thread comment data.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link ThreadCommentVariables} for the query.
+   * @returns The {@link ThreadCommentResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/threadcomment
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ThreadCommentQuery().threadComment({ threadId: 1 });
+   * ```
    */
   async threadComment(variables, options) {
     const query = `
@@ -4756,10 +5624,14 @@ class ThreadCommentsQuery extends AniListOperation {
   /**
    * `threadComments` is a method that sends a query request to get thread comments.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link ThreadCommentsVariables} for the query.
+   * @returns The {@link ThreadCommentsPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/threadcomment
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ThreadCommentsQuery().threadComments({ threadId: 1, page: 1 });
+   * ```
    */
   async threadComments(variables, options) {
     const query = `
@@ -4806,12 +5678,16 @@ const ThreadMappings = {
 };
 class ThreadQuery extends AniListOperation {
   /**
-   * `thread` is a method that sends a query request to get thread data.
+   * {@link ThreadQuery.thread} sends a query request to get thread data.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link ThreadVariables} for the query.
+   * @returns The {@link ThreadResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/thread
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ThreadQuery().thread({ id: 1 });
+   * ```
    */
   async thread(variables, options) {
     const query = `
@@ -4853,10 +5729,14 @@ class ThreadsQuery extends AniListOperation {
   /**
    * `threads` is a method that sends a query request to get threads.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link ThreadsVariables} for the query.
+   * @returns The {@link ThreadsPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/thread
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ThreadsQuery().threads({ page: 1, perPage: 10 });
+   * ```
    */
   async threads(variables, options) {
     const query = `
@@ -4896,12 +5776,16 @@ const UserMappings = {
 };
 class UserQuery extends AniListOperation {
   /**
-   * `user` is a method that sends a query request to get user data.
+   * {@link UserQuery.user} sends a query request to get user data.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link UserVariables} for the query.
+   * @returns The {@link UserResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/user
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new UserQuery().user({ id: 1 });
+   * ```
    */
   async user(variables, options) {
     const query = `
@@ -4936,10 +5820,14 @@ class UsersQuery extends AniListOperation {
   /**
    * `users` is a method that sends a query request to get users.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Values from {@link UsersVariables} for the query.
+   * @returns The {@link UsersPageResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/user
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new UsersQuery().users({ search: "AniList", page: 1 });
+   * ```
    */
   async users(variables, options) {
     const query = `
@@ -4974,12 +5862,16 @@ const ViewerMappings = {
 };
 class ViewerQuery extends AniListOperation {
   /**
-   * `viewer` is a method that sends a query request to get viewer data.
+   * {@link ViewerQuery.viewer} sends a query request to get viewer data.
    *
-   * @param variables - The variables for the query.
-   * @returns The response from the query request.
+   * @param variables - Optional values from {@link ViewerVariables}; defaults to an empty object.
+   * @returns The {@link UserResponse} returned by the query.
    * @see https://docs.anilist.co/reference/object/user
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ViewerQuery("authToken").viewer({});
+   * ```
    */
   async viewer(variables = {}, options) {
     const query = `
@@ -5002,18 +5894,22 @@ const DeleteMediaListEntryMappings = {
 };
 class DeleteMediaListEntryMutation extends AniListOperation {
   /**
-   * `deleteMediaListEntry` is a method that sends a mutation request to delete a media list entry.
+   * {@link DeleteMediaListEntryMutation.deleteMediaListEntry} sends a mutation request to delete a media list entry.
    *
    * The response is `{ deleted: boolean }`. A `true` value means the entry was deleted by this
    * call; a `false` value means the entry was not present (already deleted or never existed).
    * The mutation is therefore safe to retry after a partial failure: a `false` result confirms
    * the target is gone rather than reporting an error.
    *
-   * @param variables - An object of type `DeleteMediaListEntryVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to `{ deleted }`, where `deleted` is `true` when the entry was deleted by this call and `false` when it was already absent.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link DeleteMediaListEntryVariables} for the mutation.
+   * @returns The {@link DeleteMediaListEntryResponse} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` is missing or invalid, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/deleted
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new DeleteMediaListEntryMutation("your-token").deleteMediaListEntry({ id: 1 });
+   * ```
    */
   async deleteMediaListEntry(variables, options) {
     const mutation = `
@@ -5044,18 +5940,22 @@ const DeleteCustomListMappings = {
 };
 class DeleteCustomListMutation extends AniListOperation {
   /**
-   * `deleteCustomList` is a method that sends a mutation request to delete a custom list.
+   * {@link DeleteCustomListMutation.deleteCustomList} sends a mutation request to delete a custom list.
    *
    * The response is `{ deleted: boolean }`. A `true` value means the custom list was deleted by
    * this call; a `false` value means the list was not present (already deleted or never existed).
    * The mutation is therefore safe to retry after a partial failure: a `false` result confirms
    * the target is gone rather than reporting an error.
    *
-   * @param variables - An object of type `DeleteCustomListVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to `{ deleted }`, where `deleted` is `true` when the custom list was deleted by this call and `false` when it was already absent.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link DeleteCustomListVariables} for the mutation.
+   * @returns The {@link DeleteResult} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `customList` or `type` is missing or invalid, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/deleted
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new DeleteCustomListMutation("your-token").deleteCustomList({ customList: "watching", type: "ANIME" });
+   * ```
    */
   async deleteCustomList(variables, options) {
     const mutation = `
@@ -5088,13 +5988,17 @@ const SaveTextActivityMappings = {
 };
 class SaveTextActivityMutation extends AniListOperation {
   /**
-   * `saveTextActivity` is a method that sends a mutation request to save a text activity.
+   * {@link SaveTextActivityMutation.saveTextActivity} sends a mutation request to save a text activity.
    *
-   * @param variables - An object of type `SaveTextActivityVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
-   *   * @see https://docs.anilist.co/reference/union/activityunion
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param variables - Values from {@link SaveTextActivityVariables} for the mutation.
+   * @returns The {@link Activity} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` or `text` is missing or invalid, or the mutation request fails.
+   * @see https://docs.anilist.co/reference/union/activityunion
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new SaveTextActivityMutation("your-token").saveTextActivity({ id: 1, text: "Hello, world!" });
+   * ```
    */
   async saveTextActivity(variables, options) {
     const mutation = `
@@ -5130,13 +6034,17 @@ const SaveMessageActivityMappings = {
 };
 class SaveMessageActivityMutation extends AniListOperation {
   /**
-   * `saveMessageActivity` is a method that sends a mutation request to save a message activity.
+   * {@link SaveMessageActivityMutation.saveMessageActivity} sends a mutation request to save a message activity.
    *
-   * @param variables - An object of type `SaveMessageActivityVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
-   *   * @see https://docs.anilist.co/reference/union/activityunion
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param variables - Values from {@link SaveMessageActivityVariables} for the mutation.
+   * @returns The {@link Activity} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` or `message` is missing or invalid, or the mutation request fails.
+   * @see https://docs.anilist.co/reference/union/activityunion
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new SaveMessageActivityMutation("your-token").saveMessageActivity({ id: 1, message: "Hello, world!" });
+   * ```
    */
   async saveMessageActivity(variables, options) {
     const mutation = `
@@ -5168,13 +6076,17 @@ const SaveListActivityMappings = {
 };
 class SaveListActivityMutation extends AniListOperation {
   /**
-   * `saveListActivity` is a method that sends a mutation request to save a list activity.
+   * {@link SaveListActivityMutation.saveListActivity} sends a mutation request to save a list activity.
    *
-   * @param variables - An object of type `SaveListActivityVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
-   *   * @see https://docs.anilist.co/reference/union/activityunion
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param variables - Values from {@link SaveListActivityVariables} for the mutation.
+   * @returns The {@link Activity} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` is missing or invalid, or the mutation request fails.
+   * @see https://docs.anilist.co/reference/union/activityunion
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new SaveListActivityMutation("your-token").saveListActivity({ id: 1 });
+   * ```
    */
   async saveListActivity(variables, options) {
     const mutation = `
@@ -5203,18 +6115,22 @@ const DeleteActivityMappings = {
 };
 class DeleteActivityMutation extends AniListOperation {
   /**
-   * `deleteActivity` is a method that sends a mutation request to delete a activity.
+   * {@link DeleteActivityMutation.deleteActivity} sends a mutation request to delete an activity.
    *
    * The response is `{ deleted: boolean }`. A `true` value means the activity was deleted by
    * this call; a `false` value means the activity was not present (already deleted or never
    * existed). The mutation is therefore safe to retry after a partial failure: a `false` result
    * confirms the target is gone rather than reporting an error.
    *
-   * @param variables - An object of type `DeleteActivityVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to `{ deleted }`, where `deleted` is `true` when the activity was deleted by this call and `false` when it was already absent.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link DeleteActivityVariables} for the mutation.
+   * @returns The {@link DeleteResult} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` is missing or invalid, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/deleted
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new DeleteActivityMutation("your-token").deleteActivity({ id: 1 });
+   * ```
    */
   async deleteActivity(variables, options) {
     const mutation = `
@@ -5246,13 +6162,17 @@ const ToggleActivitySubscriptionMappings = {
 };
 class ToggleActivitySubscriptionMutation extends AniListOperation {
   /**
-   * `toggleActivitySubscription` is a method that sends a mutation request to subscribe to an activity.
+   * {@link ToggleActivitySubscriptionMutation.toggleActivitySubscription} sends a mutation request to subscribe to an activity.
    *
-   * @param variables - An object of type `ToggleActivitySubscriptionVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
-   *   * @see https://docs.anilist.co/reference/union/activityunion
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param variables - Values from {@link ToggleActivitySubscriptionVariables} for the mutation.
+   * @returns The {@link Activity} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `activityId` or `subscribe` is missing or invalid, or the mutation request fails.
+   * @see https://docs.anilist.co/reference/union/activityunion
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ToggleActivitySubscriptionMutation("your-token").toggleActivitySubscription({ activityId: 1, subscribe: true });
+   * ```
    */
   async toggleActivitySubscription(variables, options) {
     const mutation = `
@@ -5284,13 +6204,17 @@ const ToggleActivityPinMappings = {
 };
 class ToggleActivityPinMutation extends AniListOperation {
   /**
-   * `toggleActivityPin` is a method that sends a mutation request to pin an activity.
+   * {@link ToggleActivityPinMutation.toggleActivityPin} sends a mutation request to pin an activity.
    *
-   * @param variables - An object of type `ToggleActivityPinVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
-   *   * @see https://docs.anilist.co/reference/union/activityunion
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param variables - Values from {@link ToggleActivityPinVariables} for the mutation.
+   * @returns The {@link Activity} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` or `pinned` is missing or invalid, or the mutation request fails.
+   * @see https://docs.anilist.co/reference/union/activityunion
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ToggleActivityPinMutation("your-token").toggleActivityPin({ id: 1, pinned: true });
+   * ```
    */
   async toggleActivityPin(variables, options) {
     const mutation = `
@@ -5324,13 +6248,17 @@ const SaveActivityReplyMappings = {
 };
 class SaveActivityReplyMutation extends AniListOperation {
   /**
-   * `SaveActivityReply` is a method that sends a mutation request to save an activity reply.
+   * {@link SaveActivityReplyMutation.saveActivityReply} sends a mutation request to save an activity reply.
    *
-   * @param variables - An object of type `SaveActivityReplyVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
-   *   * @see https://docs.anilist.co/reference/object/activityreply
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param variables - Values from {@link SaveActivityReplyVariables} for the mutation.
+   * @returns The {@link ActivityReply} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` or `text` is missing or invalid, or the mutation request fails.
+   * @see https://docs.anilist.co/reference/object/activityreply
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new SaveActivityReplyMutation("your-token").saveActivityReply({ id: 1, text: "Hello, world!" });
+   * ```
    */
   async saveActivityReply(variables, options) {
     const mutation = `
@@ -5360,18 +6288,22 @@ const DeleteActivityReplyMappings = {
 };
 class DeleteActivityReplyMutation extends AniListOperation {
   /**
-   * `DeleteActivityReply` is a method that sends a mutation request to delete an activity reply.
+   * {@link DeleteActivityReplyMutation.deleteActivityReply} sends a mutation request to delete an activity reply.
    *
    * The response is `{ deleted: boolean }`. A `true` value means the reply was deleted by this
    * call; a `false` value means the reply was not present (already deleted or never existed).
    * The mutation is therefore safe to retry after a partial failure: a `false` result confirms
    * the target is gone rather than reporting an error.
    *
-   * @param variables - An object of type `DeleteActivityReplyVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to `{ deleted }`, where `deleted` is `true` when the reply was deleted by this call and `false` when it was already absent.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link DeleteActivityReplyVariables} for the mutation.
+   * @returns The {@link DeleteResult} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` is missing or invalid, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/deleted
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new DeleteActivityReplyMutation("your-token").deleteActivityReply({ id: 1 });
+   * ```
    */
   async deleteActivityReply(variables, options) {
     const mutation = `
@@ -5402,13 +6334,18 @@ const ToggleLikeMappings = {
 };
 class ToggleLikeMutation extends AniListOperation {
   /**
-   * `ToggleLike` is a method that sends a mutation request to toggle a like.
+   * {@link ToggleLikeMutation.toggleLike} sends a mutation request to toggle a like.
    *
-   * @param variables - An object of type `ToggleLikeVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the user who performed the like toggle.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
-   *   * @see https://docs.anilist.co/reference/object/user
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @deprecated Prefer `ToggleLikeV2Mutation.toggleLikeV2`, which returns the richer `Likeable` union (activity, activity reply, thread, or thread comment) instead of a bare user.
+   * @param variables - Values from {@link ToggleLikeVariables} for the mutation.
+   * @returns The {@link BasicUser} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` or `type` is missing or invalid, or the mutation request fails.
+   * @see https://docs.anilist.co/reference/object/user
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ToggleLikeMutation("your-token").toggleLike({ id: 1, type: "ACTIVITY" });
+   * ```
    */
   async toggleLike(variables, options) {
     const mutation = `
@@ -5440,14 +6377,17 @@ const ToggleLikeV2Mappings = {
 };
 class ToggleLikeV2Mutation extends AniListOperation {
   /**
-   * `ToggleLikeV2` is a method that sends a mutation request to toggle a like.
+   * {@link ToggleLikeV2Mutation.toggleLikeV2} sends a mutation request to toggle a like.
    *
-   * @param variables - An object of type `ToggleLikeV2Variables` representing the variables for the mutation.
-   * @returns A Promise that resolves to a `Likeable` — one of an activity, activity reply, thread,
-   * or thread comment, depending on which likeable entity the mutation toggled.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
-   *   * @see https://docs.anilist.co/reference/union/likeableunion
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param variables - Values from {@link ToggleLikeV2Variables} for the mutation.
+   * @returns The {@link Likeable} returned by the mutation: an activity, activity reply, thread, or thread comment.
+   * @throws Throws if no authentication token is configured, `id` or `type` is missing or invalid, or the mutation request fails.
+   * @see https://docs.anilist.co/reference/union/likeableunion
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ToggleLikeV2Mutation("your-token").toggleLikeV2({ id: 1, type: "ACTIVITY" });
+   * ```
    */
   async toggleLikeV2(variables, options) {
     const mutation = `
@@ -5477,13 +6417,17 @@ const ToggleFollowMappings = {
 };
 class ToggleFollowMutation extends AniListOperation {
   /**
-   * `ToggleFollow` is a method that sends a mutation request to toggle a follow.
+   * {@link ToggleFollowMutation.toggleFollow} sends a mutation request to toggle a follow.
    *
-   * @param variables - An object of type `ToggleFollowVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
-   *   * @see https://docs.anilist.co/reference/object/user
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param variables - Values from {@link ToggleFollowVariables} for the mutation.
+   * @returns The {@link UserResponse} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `userId` is missing or invalid, or the mutation request fails.
+   * @see https://docs.anilist.co/reference/object/user
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ToggleFollowMutation("your-token").toggleFollow({ userId: 1 });
+   * ```
    */
   async toggleFollow(variables, options) {
     const mutation = `
@@ -5593,13 +6537,17 @@ const ToggleFavouriteMappings = {
 };
 class ToggleFavouriteMutation extends AniListOperation {
   /**
-   * `toggleFavourite` is a method that sends a mutation request to toggle a favourite.
+   * {@link ToggleFavouriteMutation.toggleFavourite} sends a mutation request to toggle a favourite.
    *
-   * @param variables - An object of type `ToggleFavouriteVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link ToggleFavouriteVariables} for the mutation.
+   * @returns The {@link Favourites} returned by the mutation.
+   * @throws Throws if no authentication token is configured, at least one favourite ID is missing or invalid, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/favourites
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ToggleFavouriteMutation("your-token").toggleFavourite({ animeId: 1, mangaId: 1, characterId: 1, staffId: 1, studioId: 1 });
+   * ```
    */
   async toggleFavourite(variables, options) {
     const mutation = `
@@ -5638,13 +6586,17 @@ const UpdateFavouriteOrderMappings = {
 };
 class UpdateFavouriteOrderMutation extends AniListOperation {
   /**
-   * `updateFavouriteOrder` is a method that sends a mutation request to update the order of the favourites.
+   * {@link UpdateFavouriteOrderMutation.updateFavouriteOrder} sends a mutation request to update the order of favourites.
    *
-   * @param variables - An object of type `UpdateFavouriteOrderVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if authentication is missing, validation fails, or the mutation request fails.
+   * @param variables - Values from {@link UpdateFavouriteOrderVariables} for the mutation.
+   * @returns The {@link Favourites} returned by the mutation.
+   * @throws Throws if no authentication token is configured, an order array lacks its corresponding ID array, a variable has an invalid type, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/favourites
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new UpdateFavouriteOrderMutation("your-token").updateFavouriteOrder({ animeIds: [1], mangaIds: [], characterIds: [], staffIds: [], studioIds: [], animeOrder: [1], mangaOrder: [], characterOrder: [], staffOrder: [], studioOrder: [] });
+   * ```
    */
   async updateFavouriteOrder(variables, options) {
     if (!variables.animeIds && variables.animeOrder || !variables.mangaIds && variables.mangaOrder || !variables.characterIds && variables.characterOrder || !variables.staffIds && variables.staffOrder || !variables.studioIds && variables.studioOrder) {
@@ -5678,13 +6630,17 @@ const SaveReviewMappings = {
 };
 class SaveReviewMutation extends AniListOperation {
   /**
-   * `saveReview` is a method that sends a mutation request to save a review.
+   * {@link SaveReviewMutation.saveReview} sends a mutation request to save a review.
    *
-   * @param variables - An object of type `SaveReviewVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link SaveReviewVariables} for the mutation.
+   * @returns The {@link ReviewResponse} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` or `mediaId` is missing, a variable has an invalid type, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/review
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new SaveReviewMutation("your-token").saveReview({ id: 1, mediaId: 1, body: "Example review", summary: "Example", score: 8, private: false });
+   * ```
    */
   async saveReview(variables, options) {
     const mutation = `
@@ -5717,13 +6673,17 @@ const RateReviewMappings = {
 };
 class RateReviewMutation extends AniListOperation {
   /**
-   * `rateReview` is a method that sends a mutation request to rate a review.
+   * {@link RateReviewMutation.rateReview} sends a mutation request to rate a review.
    *
-   * @param variables - An object of type `RateReviewVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if authentication is missing, validation fails, or the mutation request fails.
+   * @param variables - Values from {@link RateReviewVariables} for the mutation.
+   * @returns The {@link ReviewResponse} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `reviewId` or `rating` is missing or invalid, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/review
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new RateReviewMutation("your-token").rateReview({ reviewId: 1, rating: "UP_VOTE" });
+   * ```
    */
   async rateReview(variables, options) {
     const mutation = `
@@ -5753,18 +6713,22 @@ const DeleteReviewMappings = {
 };
 class DeleteReviewMutation extends AniListOperation {
   /**
-   * `deleteReview` is a method that sends a mutation request to delete a review.
+   * {@link DeleteReviewMutation.deleteReview} sends a mutation request to delete a review.
    *
    * The response is `{ deleted: boolean }`. A `true` value means the review was deleted by this
    * call; a `false` value means the review was not present (already deleted or never existed).
    * The mutation is therefore safe to retry after a partial failure: a `false` result confirms
    * the target is gone rather than reporting an error.
    *
-   * @param variables - An object of type `DeleteReviewVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to `{ deleted }`, where `deleted` is `true` when the review was deleted by this call and `false` when it was already absent.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link DeleteReviewVariables} for the mutation.
+   * @returns The {@link DeleteResult} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` is missing or invalid, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/deleted
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new DeleteReviewMutation("your-token").deleteReview({ id: 1 });
+   * ```
    */
   async deleteReview(variables, options) {
     const mutation = `
@@ -5803,13 +6767,17 @@ const SaveRecommendationMappings = {
 };
 class SaveRecommendationMutation extends AniListOperation {
   /**
-   * `saveReview` is a method that sends a mutation request to save a recommendation.
+   * {@link SaveRecommendationMutation.saveRecommendation} sends a mutation request to save a recommendation.
    *
-   * @param variables - An object of type `SaveRecommendationVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link SaveRecommendationVariables} for the mutation.
+   * @returns The {@link RecommendationResponse} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `mediaId`, `mediaRecommendationId`, or `rating` is missing or invalid, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/recommendation
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new SaveRecommendationMutation("your-token").saveRecommendation({ mediaId: 1, mediaRecommendationId: 2, rating: "RATE_UP" });
+   * ```
    */
   async saveRecommendation(variables, options) {
     const mutation = `
@@ -5846,13 +6814,17 @@ const SaveThreadMappings = {
 };
 class SaveThreadMutation extends AniListOperation {
   /**
-   * `SaveThread` is a method that sends a mutation request to save a thread.
+   * {@link SaveThreadMutation.saveThread} sends a mutation request to save a thread.
    *
-   * @param variables - An object of type `SaveThreadVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
-   *   * @see https://docs.anilist.co/reference/object/thread
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param variables - Values from {@link SaveThreadVariables} for the mutation.
+   * @returns The {@link ThreadResponse} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` or `title` is missing, a variable has an invalid type, or the mutation request fails.
+   * @see https://docs.anilist.co/reference/object/thread
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new SaveThreadMutation("your-token").saveThread({ id: 1, title: "Example thread", body: "Hello, world!", categories: [], mediaCategories: [], sticky: false, locked: false, asHtml: true });
+   * ```
    */
   async saveThread(variables, options) {
     const mutation = `
@@ -5882,18 +6854,22 @@ const DeleteThreadMappings = {
 };
 class DeleteThreadMutation extends AniListOperation {
   /**
-   * `deleteThread` is a method that sends a mutation request to delete a thread.
+   * {@link DeleteThreadMutation.deleteThread} sends a mutation request to delete a thread.
    *
    * The response is `{ deleted: boolean }`. A `true` value means the thread was deleted by this
    * call; a `false` value means the thread was not present (already deleted or never existed).
    * The mutation is therefore safe to retry after a partial failure: a `false` result confirms
    * the target is gone rather than reporting an error.
    *
-   * @param variables - An object of type `DeleteThreadVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to `{ deleted }`, where `deleted` is `true` when the thread was deleted by this call and `false` when it was already absent.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link DeleteThreadVariables} for the mutation.
+   * @returns The {@link DeleteResult} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` is missing or invalid, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/deleted
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new DeleteThreadMutation("your-token").deleteThread({ id: 1 });
+   * ```
    */
   async deleteThread(variables, options) {
     const mutation = `
@@ -5925,13 +6901,17 @@ const ToggleThreadSubscriptionMappings = {
 };
 class ToggleThreadSubscriptionMutation extends AniListOperation {
   /**
-   * `toggleThreadSubscription` is a method that sends a mutation request to subscribe to an activity.
+   * {@link ToggleThreadSubscriptionMutation.toggleThreadSubscription} sends a mutation request to subscribe to a thread.
    *
-   * @param variables - An object of type `ToggleThreadSubscriptionVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
-   *   * @see https://docs.anilist.co/reference/object/thread
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param variables - Values from {@link ToggleThreadSubscriptionVariables} for the mutation.
+   * @returns The {@link ThreadResponse} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `threadId` or `subscribe` is missing or invalid, or the mutation request fails.
+   * @see https://docs.anilist.co/reference/object/thread
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new ToggleThreadSubscriptionMutation("your-token").toggleThreadSubscription({ threadId: 1, subscribe: true });
+   * ```
    */
   async toggleThreadSubscription(variables, options) {
     const mutation = `
@@ -5966,13 +6946,17 @@ const SaveThreadCommentMappings = {
 };
 class SaveThreadCommentMutation extends AniListOperation {
   /**
-   * `saveThreadComment` is a method that sends a mutation request to save a thread comment.
+   * {@link SaveThreadCommentMutation.saveThreadComment} sends a mutation request to save a thread comment.
    *
-   * @param variables - An object of type `SaveThreadCommentVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
-   *   * @see https://docs.anilist.co/reference/object/threadcomment
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param variables - Values from {@link SaveThreadCommentVariables} for the mutation.
+   * @returns The {@link ThreadCommentResponse} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` or `threadId` is missing, a variable has an invalid type, or the mutation request fails.
+   * @see https://docs.anilist.co/reference/object/threadcomment
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new SaveThreadCommentMutation("your-token").saveThreadComment({ id: 1, threadId: 1, parentCommentId: 0, comment: "Hello, world!", locked: false, asHtml: true });
+   * ```
    */
   async saveThreadComment(variables, options) {
     const mutation = `
@@ -6002,18 +6986,22 @@ const DeleteThreadCommentMappings = {
 };
 class DeleteThreadCommentMutation extends AniListOperation {
   /**
-   * `deleteThreadComment` is a method that sends a mutation request to delete a thread comment.
+   * {@link DeleteThreadCommentMutation.deleteThreadComment} sends a mutation request to delete a thread comment.
    *
    * The response is `{ deleted: boolean }`. A `true` value means the comment was deleted by this
    * call; a `false` value means the comment was not present (already deleted or never existed).
    * The mutation is therefore safe to retry after a partial failure: a `false` result confirms
    * the target is gone rather than reporting an error.
    *
-   * @param variables - An object of type `DeleteThreadCommentVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to `{ deleted }`, where `deleted` is `true` when the comment was deleted by this call and `false` when it was already absent.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link DeleteThreadCommentVariables} for the mutation.
+   * @returns The {@link DeleteResult} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `id` is missing or invalid, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/deleted
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new DeleteThreadCommentMutation("your-token").deleteThreadComment({ id: 1 });
+   * ```
    */
   async deleteThreadComment(variables, options) {
     const mutation = `
@@ -6046,13 +7034,17 @@ const UpdateAniChartSettingsMappings = {
 };
 class UpdateAniChartSettingsMutation extends AniListOperation {
   /**
-   * `updateAniChartSettings` is a method that sends a mutation request to update the AniChart settings.
+   * {@link UpdateAniChartSettingsMutation.updateAniChartSettings} sends a mutation request to update the AniChart settings.
    *
-   * @param variables - An object of type `UpdateAniChartSettingsVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the updated AniChart settings string.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link UpdateAniChartSettingsVariables} for the mutation.
+   * @returns The updated AniChart settings string returned by the mutation.
+   * @throws Throws if no authentication token is configured, a setting has an invalid type, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/anichartuser
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new UpdateAniChartSettingsMutation("your-token").updateAniChartSettings({ titleLanguage: "romaji", outgoingLinkProvider: "ANILIST", theme: "dark", sort: "POPULARITY" });
+   * ```
    */
   async updateAniChartSettings(variables, options) {
     const mutation = `
@@ -6076,13 +7068,17 @@ const UpdateAniChartHighlightsMappings = {
 };
 class UpdateAniChartHighlightsMutation extends AniListOperation {
   /**
-   * `updateAniChartHighlights` is a method that sends a mutation request to update the AniChart highlights.
+   * {@link UpdateAniChartHighlightsMutation.updateAniChartHighlights} sends a mutation request to update the AniChart highlights.
    *
-   * @param variables - An object of type `UpdateAniChartHighlightsVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the updated AniChart highlights string.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link UpdateAniChartHighlightsVariables} for the mutation.
+   * @returns The updated AniChart highlights string returned by the mutation.
+   * @throws Throws if no authentication token is configured, `highlights` is missing or invalid, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/anichartuser
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new UpdateAniChartHighlightsMutation("your-token").updateAniChartHighlights({ highlights: { mediaId: 1, highlight: true } });
+   * ```
    */
   async updateAniChartHighlights(variables, options) {
     const mutation = `
@@ -6123,13 +7119,17 @@ const UpdateMediaListEntriesMappings = {
 };
 class UpdateMediaListEntriesMutation extends AniListOperation {
   /**
-   * `updateMediaListEntries` is a method that sends a mutation request to update media list entries.
+   * {@link UpdateMediaListEntriesMutation.updateMediaListEntries} sends a mutation request to update media list entries.
    *
-   * @param variables - An object of type `UpdateMediaListEntriesVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
-   *   * @see https://docs.anilist.co/reference/object/medialist
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param variables - Values from {@link UpdateMediaListEntriesVariables} for the mutation.
+   * @returns The updated {@link MediaListResponse} entries returned by the mutation.
+   * @throws Throws if no authentication token is configured, `ids` is missing or invalid, or the mutation request fails.
+   * @see https://docs.anilist.co/reference/object/medialist
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new UpdateMediaListEntriesMutation("your-token").updateMediaListEntries({ ids: [1], status: "CURRENT", progress: 1 });
+   * ```
    */
   async updateMediaListEntries(variables, options) {
     const mutation = `
@@ -6245,13 +7245,17 @@ const UpdateUserMappings = {
 };
 class UpdateUserMutation extends AniListOperation {
   /**
-   * `updateUser` is a method that sends a mutation request to update a user.
+   * {@link UpdateUserMutation.updateUser} sends a mutation request to update a user.
    *
-   * @param variables - An object of type `UpdateUserVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to an object of type `UpdateUserResponse`. This object includes the updated user details
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link UpdateUserVariables} for the mutation.
+   * @returns The {@link UpdateUserResponse} returned by the mutation.
+   * @throws Throws if no authentication token is configured, a variable has an invalid type, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/user
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new UpdateUserMutation("your-token").updateUser({ about: "Updated profile" });
+   * ```
    */
   async updateUser(variables, options) {
     const mutation = `
@@ -6337,13 +7341,17 @@ const SaveMediaListEntryMappings = {
 };
 class SaveMediaListEntryMutation extends AniListOperation {
   /**
-   * `saveMediaListEntry` is a method that sends a mutation request to save a media list entry.
+   * {@link SaveMediaListEntryMutation.saveMediaListEntry} sends a mutation request to save a media list entry.
    *
-   * @param variables - An object of type `SaveMediaListEntryVariables` representing the variables for the mutation.
-   * @returns A Promise that resolves to the response from the mutation request.
-   * @throws Will throw an error if the mutation request fails or if the provided variables do not pass the validation checks.
+   * @param variables - Values from {@link SaveMediaListEntryVariables} for the mutation.
+   * @returns The {@link MediaListResponse} returned by the mutation.
+   * @throws Throws if no authentication token is configured, `mediaId` is missing or invalid, or the mutation request fails.
    * @see https://docs.anilist.co/reference/object/medialist
-   * @param options - Optional per-request transport settings merged over the instance-level ones for this call only.
+   * @param options - Optional {@link RequestOptions} merged over the instance-level settings for this call only.
+   * @example
+   * ```typescript
+   * const result = await new SaveMediaListEntryMutation("your-token").saveMediaListEntry({ mediaId: 1, status: "COMPLETED" });
+   * ```
    */
   async saveMediaListEntry(variables, options) {
     const mutation = `
@@ -6387,7 +7395,7 @@ class SaveMediaListEntryMutation extends AniListOperation {
 }
 
 function op(name, operationClass) {
-  return { name, operationClass };
+  return { name, operationClass, methodName: name };
 }
 function opAs(name, operationClass, methodName) {
   return { name, operationClass, methodName };
@@ -6473,118 +7481,571 @@ const ANILIST_OPERATION_REGISTRY = {
   ]
 };
 
-function instantiateCategory(category, authToken, options) {
-  return ANILIST_OPERATION_REGISTRY[category].map((entry) => ({
-    name: entry.name,
-    methodName: entry.methodName,
-    instance: new entry.operationClass(authToken, options)
-  }));
-}
-function bindEntries(entries) {
-  const bound = {};
-  for (const { name, instance, methodName } of entries) {
-    const method = instance[methodName ?? name];
+function validateCategoryMethods(category) {
+  for (const entry of ANILIST_OPERATION_REGISTRY[category]) {
+    const method = entry.operationClass.prototype[entry.methodName];
     if (typeof method !== "function") {
       throw new TypeError(
-        `Operation "${name}" does not expose a "${methodName ?? name}" method to bind.`
+        `Operation "${entry.name}" does not expose a "${entry.methodName}" method to bind.`
       );
     }
-    bound[name] = method.bind(instance);
   }
-  return bound;
+}
+function buildLazyGroup(category, authToken, options) {
+  const entries = ANILIST_OPERATION_REGISTRY[category];
+  const descriptors = {};
+  for (const entry of entries) {
+    let bound;
+    descriptors[entry.name] = {
+      enumerable: true,
+      configurable: false,
+      get() {
+        if (bound === void 0) {
+          const instance = new entry.operationClass(
+            authToken,
+            options
+          );
+          const method = instance[entry.methodName];
+          if (typeof method !== "function") {
+            throw new TypeError(
+              `Operation "${entry.name}" does not expose a "${entry.methodName}" method to bind.`
+            );
+          }
+          bound = method.bind(instance);
+        }
+        return bound;
+      }
+    };
+  }
+  return Object.defineProperties({}, descriptors);
 }
 function buildAniListWiring(authToken, options) {
-  const customInstance = new CustomRequest(authToken, options);
-  const [queryEntries, pageEntries, mutationEntries] = ["query", "page", "mutation"].map((category) => instantiateCategory(category, authToken, options));
-  return {
-    custom: customInstance.custom.bind(customInstance),
-    query: {
-      ...bindEntries(queryEntries),
-      page: bindEntries(pageEntries)
+  for (const category of ["query", "page", "mutation"]) {
+    validateCategoryMethods(category);
+  }
+  const queryFacade = buildLazyGroup("query", authToken, options);
+  const pageFacade = buildLazyGroup("page", authToken, options);
+  const mutationFacade = buildLazyGroup("mutation", authToken, options);
+  Object.defineProperty(queryFacade, "page", {
+    value: pageFacade,
+    enumerable: true,
+    configurable: false,
+    writable: false
+  });
+  let customBound;
+  return Object.defineProperties(
+    {
+      query: queryFacade,
+      mutation: mutationFacade,
+      paginate,
+      paginatePages,
+      paginateChunks,
+      fuzzyDate,
+      flattenMediaListCollection
     },
-    mutation: bindEntries(mutationEntries),
-    paginate,
-    paginatePages,
-    paginateChunks,
-    fuzzyDate,
-    flattenMediaListCollection
-  };
+    {
+      custom: {
+        enumerable: true,
+        configurable: false,
+        get() {
+          if (customBound === void 0) {
+            const customInstance = new CustomRequest(authToken, options);
+            customBound = customInstance.custom.bind(customInstance);
+          }
+          return customBound;
+        }
+      }
+    }
+  );
 }
 
 function buildAniListApi(authToken, options) {
   return buildAniListWiring(authToken, options);
 }
 
-function resolveProviderCredentials(credentials) {
-  if (credentials === void 0) return void 0;
-  const { authToken, ...transportOptions } = credentials;
-  return authToken === void 0 ? { ...transportOptions } : { ...transportOptions, authToken };
+const TRANSPORT_OPTION_KEYS = [
+  "timeout",
+  "signal",
+  "exposeRawAxiosError",
+  "retry",
+  "paceWithRateLimit",
+  "rateLimitFloor",
+  "circuitBreaker",
+  "retryBudget",
+  "maxSockets",
+  "maxFreeSockets",
+  "onError",
+  "onRetry",
+  "onRequestStart",
+  "onResponse",
+  "onPace",
+  "onHookError",
+  "onCircuitOpen",
+  "onCircuitClose",
+  "ignorePaceDeadline",
+  "responseCache"
+];
+
+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"])
+  };
+}
+function resolveMalCredentials(credentials) {
+  if (credentials === void 0) return {};
+  const headers = credentials.clientId === void 0 ? void 0 : { "X-MAL-CLIENT-ID": credentials.clientId };
+  return {
+    auth: credentials.accessToken === void 0 && headers === void 0 ? void 0 : { token: credentials.accessToken, headers },
+    options: resolveTransportOptions(credentials, [
+      "accessToken",
+      "refreshToken",
+      "clientId",
+      "clientSecret"
+    ])
+  };
 }
 
-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 buildAuthorizationUrl = (clientId, redirectUri, state) => {
-  let url = `${ANILIST_AUTHORIZE_URL}?client_id=${encodeURIComponent(
-    clientId
-  )}&redirect_uri=${encodeURIComponent(redirectUri)}&response_type=code`;
-  if (state !== void 0) {
-    url += `&state=${encodeURIComponent(state)}`;
+const buildQueryString = (params) => {
+  const segments = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) {
+      continue;
+    }
+    const encodedKey = encodeURIComponent(key);
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item !== void 0 && item !== null) {
+          segments.push(`${encodedKey}=${encodeURIComponent(String(item))}`);
+        }
+      }
+    } else {
+      segments.push(`${encodedKey}=${encodeURIComponent(String(value))}`);
+    }
   }
-  return url;
+  return segments.length > 0 ? `?${segments.join("&")}` : "";
+};
+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.
+   *
+   * @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, or a normalized {@link AniLinkError} (typically `AniLinkRestError`) when the request fails.
+   */
+  async execute(path, options = {}) {
+    const {
+      method = "GET",
+      requiresAuth = false,
+      contentType,
+      query,
+      body,
+      pathParams = {},
+      transportOptions
+    } = options;
+    const interpolatedPath = path.replace(/\{(\w+)\}/g, (match, name) => {
+      const value = pathParams[name];
+      return value === void 0 ? match : encodeURIComponent(String(value));
+    });
+    const url = `${this.baseUrl}${interpolatedPath}${buildQueryString(query ?? {})}`;
+    const carriesBody = method === "POST" || method === "PUT" || method === "PATCH";
+    const effectiveContentType = contentType ?? "application/json";
+    return await this.dispatch(url, method, carriesBody ? body : void 0, {
+      requiresAuth,
+      transportOptions,
+      contentType: effectiveContentType,
+      protocol: "rest"
+    });
+  }
+}
+
+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";
+
+class MalAnimeOperation extends RestOperation {
+  /** The base URL for MyAnimeList API v2, from {@link MAL_API_BASE_URL}. */
+  baseUrl = MAL_API_BASE_URL;
+  /**
+   * {@link MalAnimeOperation.get} gets one anime by its MyAnimeList ID.
+   *
+   * It calls `GET /anime/{id}` through `RestOperation.execute` and returns a {@link MalAnime} shaped by {@link MalRequestOptions.fields}. The facade alias is `MyAnimeListAnimeApi.get`.
+   *
+   * @param id - The MyAnimeList anime ID.
+   * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
+   * @returns The requested {@link MalAnime}.
+   * @throws A normalized `AniLinkError` when the request fails.
+   * @example
+   * ```typescript
+   * const api = new AniLink({ mal: { accessToken: "mal-token" } }).mal;
+   * const anime = await api.anime.get(21, { fields: ["id", "title"] });
+   * ```
+   * @see https://myanimelist.net/apiconfig/references/api/v2#tag/anime/operation/anime_anime_id_get
+   */
+  async get(id, options = {}) {
+    const { fields, ...transportOptions } = options;
+    return await this.execute("/anime/{id}", {
+      transportOptions,
+      query: fields === void 0 ? void 0 : { fields: Array.isArray(fields) ? fields.join(",") : fields },
+      pathParams: { id }
+    });
+  }
+  /**
+   * Encodes a {@link MalAnimeListStatusUpdate} as the form-urlencoded body
+   * 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. Array values
+   * (`tags`) are joined 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`.
+   */
+  encodeListStatusBody(payload) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(payload)) {
+      if (value === void 0) continue;
+      if (Array.isArray(value)) {
+        if (Array.isArray(value)) {
+          params.set(key, value.join(","));
+        }
+      } else {
+        params.set(key, String(value));
+      }
+    }
+    return params.toString();
+  }
+  /**
+   * {@link MalAnimeOperation.updateMyListStatus} updates the authenticated user's anime list status.
+   *
+   * It calls `PATCH /anime/{id}/my_list_status` through `RestOperation.execute` with `requiresAuth` and a form-urlencoded {@link MalAnimeListStatusUpdate} body (MAL rejects JSON on this endpoint), returning the updated {@link MalAnimeListStatus}. The facade alias is `MyAnimeListAnimeApi.updateMyListStatus` and it requires `MalCredentials.accessToken`.
+   *
+   * @param id - The MyAnimeList anime ID.
+   * @param payload - The list-status fields to update; a {@link MalAnimeListStatusUpdate} of only the fields to change.
+   * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
+   * @returns The updated {@link MalAnimeListStatus}.
+   * @throws An `AniLinkAuthError` without an access token, or a normalized request error.
+   * @example
+   * ```typescript
+   * const api = new AniLink({ mal: { accessToken: "mal-token" } }).mal;
+   * const status = await api.anime.updateMyListStatus(21, {
+   *   status: "watching",
+   *   num_watched_episodes: 10,
+   *   score: 9,
+   * });
+   * ```
+   * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-animelist/operation/anime_anime_id_my_list_status_put
+   */
+  async updateMyListStatus(id, payload, options = {}) {
+    const { fields, ...transportOptions } = options;
+    return await this.execute("/anime/{id}/my_list_status", {
+      method: "PATCH",
+      requiresAuth: true,
+      transportOptions,
+      contentType: "application/x-www-form-urlencoded",
+      body: this.encodeListStatusBody(payload),
+      query: fields === void 0 ? void 0 : { fields: Array.isArray(fields) ? fields.join(",") : fields },
+      pathParams: { id }
+    });
+  }
+  /**
+   * {@link MalAnimeOperation.deleteFromList} removes an anime from the authenticated user's list.
+   *
+   * It calls `DELETE /anime/{id}/my_list_status` through `RestOperation.execute` with `requiresAuth` and resolves with no body. The facade alias is `MyAnimeListAnimeApi.deleteFromList` and it requires `MalCredentials.accessToken`.
+   *
+   * @param id - The MyAnimeList anime ID.
+   * @param options - Optional transport settings; a {@link MalRequestOptions} merged over the instance defaults.
+   * @returns Resolves once the entry is deleted; the response carries no body.
+   * @throws An `AniLinkAuthError` without an access token, or a normalized request error.
+   * @example
+   * ```typescript
+   * const api = new AniLink({ mal: { accessToken: "mal-token" } }).mal;
+   * await api.anime.deleteFromList(21);
+   * ```
+   * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-animelist/operation/anime_anime_id_my_list_status_delete
+   */
+  async deleteFromList(id, options = {}) {
+    const { fields: _ignoredFields, ...transportOptions } = options;
+    await this.execute("/anime/{id}/my_list_status", {
+      method: "DELETE",
+      requiresAuth: true,
+      transportOptions,
+      pathParams: { id }
+    });
+  }
+}
+
+class MalMangaOperation extends RestOperation {
+  /** The base URL for MyAnimeList API v2, from {@link MAL_API_BASE_URL}. */
+  baseUrl = MAL_API_BASE_URL;
+  /**
+   * {@link MalMangaOperation.get} gets one manga by its MyAnimeList ID.
+   *
+   * It calls `GET /manga/{id}` through `RestOperation.execute` and returns a {@link MalManga} shaped by {@link MalRequestOptions.fields}. The facade alias is `MyAnimeListMangaApi.get`.
+   *
+   * @param id - The MyAnimeList manga ID.
+   * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
+   * @returns The requested {@link MalManga}.
+   * @throws A normalized `AniLinkError` when the request fails.
+   * @example
+   * ```typescript
+   * const api = new AniLink({ mal: { accessToken: "mal-token" } }).mal;
+   * const manga = await api.manga.get(1, { fields: ["id", "title"] });
+   * ```
+   * @see https://myanimelist.net/apiconfig/references/api/v2#tag/manga/operation/manga_manga_id_get
+   */
+  async get(id, options = {}) {
+    const { fields, ...transportOptions } = options;
+    return await this.execute("/manga/{id}", {
+      transportOptions,
+      query: fields === void 0 ? void 0 : { fields: Array.isArray(fields) ? fields.join(",") : fields },
+      pathParams: { id }
+    });
+  }
+  /**
+   * Encodes a {@link MalMangaListStatusUpdate} as the form-urlencoded body
+   * 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. Array values
+   * (`tags`) are joined 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`.
+   */
+  encodeListStatusBody(payload) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(payload)) {
+      if (value === void 0) continue;
+      if (Array.isArray(value)) {
+        params.set(key, value.join(","));
+      } else {
+        params.set(key, String(value));
+      }
+    }
+    return params.toString();
+  }
+  /**
+   * {@link MalMangaOperation.updateMyListStatus} updates the authenticated user's manga list status.
+   *
+   * It calls `PATCH /manga/{id}/my_list_status` through `RestOperation.execute` with `requiresAuth` and a form-urlencoded {@link MalMangaListStatusUpdate} body (MAL rejects JSON on this endpoint), returning the updated {@link MalMangaListStatus}. The facade alias is `MyAnimeListMangaApi.updateMyListStatus` and it requires `MalCredentials.accessToken`.
+   *
+   * @param id - The MyAnimeList manga ID.
+   * @param payload - The list-status fields to update; a {@link MalMangaListStatusUpdate} of only the fields to change.
+   * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
+   * @returns The updated {@link MalMangaListStatus}.
+   * @throws An `AniLinkAuthError` without an access token, or a normalized request error.
+   * @example
+   * ```typescript
+   * const api = new AniLink({ mal: { accessToken: "mal-token" } }).mal;
+   * const status = await api.manga.updateMyListStatus(1, {
+   *   status: "reading",
+   *   num_chapters_read: 10,
+   *   score: 9,
+   * });
+   * ```
+   * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-mangalist/operation/manga_manga_id_my_list_status_put
+   */
+  async updateMyListStatus(id, payload, options = {}) {
+    const { fields, ...transportOptions } = options;
+    return await this.execute("/manga/{id}/my_list_status", {
+      method: "PATCH",
+      requiresAuth: true,
+      transportOptions,
+      contentType: "application/x-www-form-urlencoded",
+      body: this.encodeListStatusBody(payload),
+      query: fields === void 0 ? void 0 : { fields: Array.isArray(fields) ? fields.join(",") : fields },
+      pathParams: { id }
+    });
+  }
+  /**
+   * {@link MalMangaOperation.deleteFromList} removes a manga from the authenticated user's list.
+   *
+   * It calls `DELETE /manga/{id}/my_list_status` through `RestOperation.execute` with `requiresAuth` and resolves with no body. The facade alias is `MyAnimeListMangaApi.deleteFromList` and it requires `MalCredentials.accessToken`.
+   *
+   * @param id - The MyAnimeList manga ID.
+   * @param options - Optional transport settings; a {@link MalRequestOptions} merged over the instance defaults.
+   * @returns Resolves once the entry is deleted; the response carries no body.
+   * @throws An `AniLinkAuthError` without an access token, or a normalized request error.
+   * @example
+   * ```typescript
+   * const api = new AniLink({ mal: { accessToken: "mal-token" } }).mal;
+   * await api.manga.deleteFromList(1);
+   * ```
+   * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-mangalist/operation/manga_manga_id_my_list_status_delete
+   */
+  async deleteFromList(id, options = {}) {
+    const { fields: _ignoredFields, ...transportOptions } = options;
+    await this.execute("/manga/{id}/my_list_status", {
+      method: "DELETE",
+      requiresAuth: true,
+      transportOptions,
+      pathParams: { id }
+    });
+  }
+}
+
+class MalUserOperation extends RestOperation {
+  /** The base URL for MyAnimeList API v2, from {@link MAL_API_BASE_URL}. */
+  baseUrl = MAL_API_BASE_URL;
+  /**
+   * {@link MalUserOperation.me} gets the currently authenticated MyAnimeList user.
+   *
+   * It calls `GET /users/@me` through `RestOperation.execute` with `requiresAuth` and returns a {@link MalUser} shaped by {@link MalRequestOptions.fields}. The facade alias is `MyAnimeListUserApi.me` and it requires `MalCredentials.accessToken`.
+   *
+   * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
+   * @returns The authenticated {@link MalUser}.
+   * @throws An `AniLinkAuthError` without an access token, or a normalized request error.
+   * @example
+   * ```typescript
+   * const api = new AniLink({ mal: { accessToken: "mal-token" } }).mal;
+   * const user = await api.user.me({ fields: ["id", "name"] });
+   * ```
+   * @see https://myanimelist.net/apiconfig/references/api/v2#tag/users/operation/users_user_id_get
+   */
+  async me(options = {}) {
+    const { fields, ...transportOptions } = options;
+    return await this.execute("/users/@me", {
+      requiresAuth: true,
+      transportOptions,
+      query: fields === void 0 ? void 0 : { fields: Array.isArray(fields) ? fields.join(",") : fields }
+    });
+  }
+}
+
+function buildMyAnimeListApi(credentials) {
+  const { auth, options } = resolveMalCredentials(credentials);
+  const anime = new MalAnimeOperation(auth, options);
+  const manga = new MalMangaOperation(auth, options);
+  const user = new MalUserOperation(auth, options);
+  return {
+    anime: {
+      get: anime.get.bind(anime),
+      updateMyListStatus: anime.updateMyListStatus.bind(anime),
+      deleteFromList: anime.deleteFromList.bind(anime)
+    },
+    manga: {
+      get: manga.get.bind(manga),
+      updateMyListStatus: manga.updateMyListStatus.bind(manga),
+      deleteFromList: manga.deleteFromList.bind(manga)
+    },
+    user: { me: user.me.bind(user) }
+  };
+}
+
+const buildAniListClient = (credentials, legacyOptions) => {
+  const resolved = resolveAniListCredentials(credentials);
+  return buildAniListApi(resolved.auth, resolved.options ?? legacyOptions);
 };
-const normalizeTokenRequestError = (error) => {
+const buildMalClient = (credentials) => buildMyAnimeListApi(credentials);
+const PROVIDER_FACTORIES = {
+  anilist: buildAniListClient,
+  mal: buildMalClient
+};
+function buildProviderClients(credentials = {}, legacyOptions) {
+  const clientHookError = credentials.onHookError;
+  const anilistSlot = clientHookError !== void 0 && credentials.anilist?.onHookError === void 0 ? { ...credentials.anilist, onHookError: clientHookError } : credentials.anilist;
+  const malSlot = clientHookError !== void 0 && credentials.mal?.onHookError === void 0 ? { ...credentials.mal, onHookError: clientHookError } : credentials.mal;
+  return {
+    anilist: PROVIDER_FACTORIES.anilist(anilistSlot, legacyOptions),
+    mal: PROVIDER_FACTORIES.mal(malSlot)
+  };
+}
+
+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
+    });
+    relabeled.message = `${label} failed with status ${error.status}.`;
+    return relabeled;
+  }
   if (error instanceof AniLinkApiError) {
-    error.message = `Token request failed with status ${error.status}.`;
-    return error;
+    const relabeled = new AniLinkApiError(error.status, error.data, void 0, {
+      rateLimit: error.rateLimit,
+      contentType: error.contentType,
+      requestId: error.requestId
+    });
+    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,
-      "The token request was cancelled."
-    );
+    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 = `Token request failed with status ${status}.`;
+      apiError.message = `${label} failed with status ${status}.`;
       return apiError;
     }
     if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
-      return new AniLinkNetworkError(
-        AniLinkErrorCodes.TIMEOUT,
-        "The token request timed out."
-      );
+      return new AniLinkNetworkError(AniLinkErrorCodes.TIMEOUT, `${label} timed out.`);
     }
     return new AniLinkNetworkError(
       AniLinkErrorCodes.NETWORK,
-      "The token request failed due to a network error."
+      `${label} failed due to a network error.`
     );
   }
-  return new AniLinkError("The token request failed.", AniLinkErrorCodes.UNKNOWN);
+  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 buildAuthorizationUrl = (clientId, redirectUri, state) => {
+  let url = `${ANILIST_AUTHORIZE_URL}?client_id=${encodeURIComponent(
+    clientId
+  )}&redirect_uri=${encodeURIComponent(redirectUri)}&response_type=code`;
+  if (state !== void 0) {
+    url += `&state=${encodeURIComponent(state)}`;
+  }
+  return url;
 };
+const normalizeTokenRequestError = (error) => sanitizeTokenError(error, "AniList token request");
 const requestToken = async (params, signal) => {
   const options = {
-    // Token exchanges block the login flow, so they fail faster than
-    // GraphQL operations unless the caller tunes the timeout explicitly.
     timeout: AUTH_TOKEN_TIMEOUT_MS,
-    signal
+    signal,
+    exposeRawAxiosError: false
   };
   try {
-    return await sendRequest(
-      ANILIST_TOKEN_URL,
-      "POST",
-      new URLSearchParams(params).toString(),
-      void 0,
-      false,
+    const body = new URLSearchParams(params).toString();
+    return await sendRequest(ANILIST_TOKEN_URL, "POST", body, void 0, {
+      requiresAuth: false,
       options,
-      void 0,
-      "application/x-www-form-urlencoded"
-    );
+      contentType: "application/x-www-form-urlencoded"
+    });
   } catch (error) {
     throw normalizeTokenRequestError(error);
   }
@@ -6610,22 +8071,236 @@ const refreshAccessToken = async (clientId, clientSecret, refreshToken, signal)
 );
 const getTokenExpiry = (response, now = Date.now()) => new Date(now + response.expires_in * 1e3);
 
+const isPlainObject = (value) => {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+const stableStringify = (value, seen = /* @__PURE__ */ new Set()) => {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "undefined";
+  }
+  if (seen.has(value)) {
+    return '"[Circular]"';
+  }
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return `[${value.map((item) => stableStringify(item, seen)).join(",")}]`;
+    }
+    if (!isPlainObject(value)) {
+      return JSON.stringify(value) ?? "undefined";
+    }
+    const keys = Object.keys(value).sort();
+    return `{${keys.map(
+      (key) => `${JSON.stringify(key)}:${stableStringify(value[key], seen)}`
+    ).join(",")}}`;
+  } finally {
+    seen.delete(value);
+  }
+};
+class ResponseCache {
+  entries = /* @__PURE__ */ new Map();
+  ttlMs;
+  maxEntries;
+  /**
+   * Creates a response cache.
+   *
+   * @param options - Cache configuration; `ttlMs` defaults to 60_000, `maxEntries` to 128.
+   */
+  constructor(options) {
+    const rawTtl = options?.ttlMs ?? 6e4;
+    if (!Number.isFinite(rawTtl) || rawTtl < 0) {
+      throw new TypeError("ttlMs must be a finite, non-negative number");
+    }
+    this.ttlMs = rawTtl;
+    const rawMax = options?.maxEntries ?? 128;
+    if (!Number.isFinite(rawMax) || rawMax <= 0 || !Number.isInteger(rawMax)) {
+      throw new TypeError("maxEntries must be a finite, positive integer");
+    }
+    this.maxEntries = rawMax;
+  }
+  /**
+   * Builds the cache key for a request.
+   *
+   * 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
+   * 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.
+   *
+   * @param method - The HTTP method.
+   * @param url - The request URL.
+   * @param data - The request body, when present.
+   * @param authKey - An authentication-safe credential identity, so cached
+   * responses never cross bearer-token identities.
+   * @returns The cache key.
+   */
+  static buildKey(method, url, data, authKey) {
+    const body = data === void 0 ? "none" : `sha256:${createHash("sha256").update(stableStringify(data)).digest("hex").slice(0, 16)}`;
+    return `${method}:${url}:${body}:${authKey ?? "none"}`;
+  }
+  /**
+   * Reads a cached response for the given request, or `undefined` when the
+   * entry is absent or expired. Expired entries are evicted on read. The
+   * returned value is a deep clone of the cached entry, so a caller that
+   * mutates it cannot corrupt the cached copy or affect subsequent reads.
+   *
+   * @param method - The HTTP method.
+   * @param url - The request URL.
+   * @param data - The request body, when present.
+   * @param authKey - An authentication-safe credential identity, so cached
+   * responses never cross bearer-token identities.
+   * @returns A deep clone of the cached response body, or `undefined`.
+   */
+  get(method, url, data, authKey) {
+    const key = ResponseCache.buildKey(method, url, data, authKey);
+    const entry = this.entries.get(key);
+    if (entry === void 0) {
+      return void 0;
+    }
+    if (Date.now() >= entry.expiresAt) {
+      this.entries.delete(key);
+      return void 0;
+    }
+    this.entries.delete(key);
+    this.entries.set(key, entry);
+    return structuredClone(entry.data);
+  }
+  /**
+   * Stores a response in the cache, evicting the LRU entry when the cap is
+   * reached. Only `GET` responses are cached; other methods are no-ops.
+   * The value is deep-copied on write; the cache never aliases the
+   * caller's object.
+   *
+   * @param method - The HTTP method.
+   * @param url - The request URL.
+   * @param data - The request body, when present.
+   * @param authKey - An authentication-safe credential identity, so cached
+   * responses never cross bearer-token identities.
+   * @param response - The response body to cache.
+   */
+  set(method, url, data, authKey, response) {
+    if (method !== "GET") return;
+    const key = ResponseCache.buildKey(method, url, data, authKey);
+    let snapshot;
+    try {
+      snapshot = structuredClone(response);
+    } catch {
+      return;
+    }
+    if (this.entries.has(key)) {
+      this.entries.delete(key);
+    } else if (this.entries.size >= this.maxEntries) {
+      this.evictLru();
+    }
+    this.entries.set(key, {
+      data: snapshot,
+      expiresAt: Date.now() + this.ttlMs
+    });
+  }
+  /**
+   * 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 `GET` entries are tracked, so non-`GET` methods are a no-op and
+   * return `false`.
+   *
+   * @param method - The HTTP method.
+   * @param url - The request URL.
+   * @param data - The request body, when present.
+   * @param authKey - An authentication-safe credential identity, so cached
+   * responses never cross bearer-token identities.
+   * @returns `true` when an entry was removed, `false` when it was absent
+   *          or the method is not cached.
+   */
+  delete(method, url, data, authKey) {
+    if (method !== "GET") return false;
+    const key = ResponseCache.buildKey(method, url, data, authKey);
+    return this.entries.delete(key);
+  }
+  /**
+   * Evicts the least-recently-used entry.
+   */
+  evictLru() {
+    const oldestKey = this.entries.keys().next().value;
+    if (oldestKey !== void 0) {
+      this.entries.delete(oldestKey);
+    }
+  }
+  /**
+   * Clears all cached entries.
+   */
+  clear() {
+    this.entries.clear();
+  }
+}
+
+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: "S256"
+  });
+  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,
+        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()) => new Date(now + response.expires_in * 1e3);
+
 class AniLink {
   /**
-   * Anilist API methods.
+   * The AniList GraphQL API surface, a {@link AniListApi} composed from the
+   * query, mutation, custom, and helper groups.
    * @public
    */
   anilist;
-  /**
-   * MyAnimeList API methods. Populated once the MAL provider module ships;
-   * the constructor already accepts and stores MAL credentials so adding
-   * the provider requires no further constructor change.
-   */
+  /** The MyAnimeList REST API methods, a {@link MyAnimeListApi} exposed under the `mal` namespace. */
   mal;
   /**
-   * Creates a new AniLink instance. The `authToken` parameter is optional and only required for authenticated queries and mutations. If no `authToken` is provided, only public queries will be available. You are able to create multiple AniLink instances with different `authToken`s.
+   * 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
+   * available. Multiple instances can hold different `authToken`s, each exposing an
+   * {@link AniListApi} under `anilist` and a {@link MyAnimeListApi} under `mal`.
    *
-   * Alternatively, pass a per-provider credentials object: each provider
+   * 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?: … }`).
@@ -6652,13 +8327,17 @@ class AniLink {
    * ```
    */
   constructor(authToken, options) {
-    if (typeof authToken === "string" || authToken === void 0) {
-      this.anilist = buildAniListApi(authToken, options);
-      return;
+    let clients;
+    if (typeof authToken === "string") {
+      clients = buildProviderClients({ anilist: { authToken } }, options);
+    } else if (authToken === void 0) {
+      clients = buildProviderClients({}, options);
+    } else {
+      clients = buildProviderClients(authToken);
     }
-    const anilistCredentials = resolveProviderCredentials(authToken.anilist);
-    this.anilist = buildAniListApi(anilistCredentials?.authToken, anilistCredentials);
+    this.anilist = clients.anilist;
+    this.mal = clients.mal;
   }
 }
 
-export { ANILIST_AUTHORIZE_URL, ANILIST_TOKEN_URL, AniLink, AniLinkApiError, AniLinkAuthError, AniLinkError, AniLinkErrorCodes, AniLinkGraphQLError, AniLinkNetworkError, AniLinkRestError, AniLinkValidationError, buildAuthorizationUrl, getAccessToken, getTokenExpiry, paginate, paginateChunks, paginatePages, refreshAccessToken };
+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, destroyCachedAgents, getAccessToken, getMalAccessToken, getMalTokenExpiry, getTokenExpiry, paginate, paginateChunks, paginatePages, refreshAccessToken, refreshMalAccessToken };