anilink-api-wrapper 2.0.0 → 2.1.0

package/dist/AniLink.mjs

@@ -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.
@@ -34,7 +35,9 @@ class AniLinkError extends Error {
   }
 }
 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.
@@ -54,6 +57,15 @@ class AniLinkApiError extends AniLinkError {
     }
   }
 }
+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
@@ -70,7 +82,7 @@ class AniLinkGraphQLError extends AniLinkApiError {
    * @param rawAxiosError - The original Axios error when raw diagnostics are enabled.
    */
   constructor(errors, data, rawAxiosError) {
-    super(200, data, rawAxiosError);
+    super(extractUpstreamStatus(errors) ?? 200, data, rawAxiosError);
     this.name = "AniLinkGraphQLError";
     this.code = AniLinkErrorCodes.GRAPHQL;
     this.message = `The request failed with GraphQL errors: ${errors.map((graphqlError) => graphqlError.message).join("; ")}`;
@@ -95,7 +107,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 +125,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.
+   */
+  constructor(status, data, rawAxiosError, options) {
+    super(status, data, rawAxiosError, options);
+    this.name = "AniLinkRestError";
+  }
 }
 class AniLinkNetworkError extends AniLinkError {
   /**
@@ -144,20 +168,22 @@ const DEFAULT_RETRY_POLICY = {
   retryOnNetworkError: true,
   jitter: true
 };
+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: 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"
-  })
+  httpAgent: defaultHttpAgent,
+  httpsAgent: defaultHttpsAgent
 });
 const resolveRetryPolicy = (retry) => {
   if (retry === false) {
@@ -168,19 +194,40 @@ const resolveRetryPolicy = (retry) => {
   }
   return { ...DEFAULT_RETRY_POLICY, ...retry };
 };
+const resolveAgents = (maxSockets, maxFreeSockets) => {
+  if (maxSockets === void 0 && maxFreeSockets === void 0) {
+    return { httpAgent: defaultHttpAgent, httpsAgent: defaultHttpsAgent };
+  }
+  const sockets = Math.max(1, maxSockets ?? MAX_SOCKETS);
+  const freeSockets = Math.max(0, maxFreeSockets ?? MAX_FREE_SOCKETS);
+  const agentOptions = {
+    keepAlive: true,
+    maxSockets: sockets,
+    maxFreeSockets: freeSockets,
+    scheduling: "lifo"
+  };
+  return {
+    httpAgent: new http.Agent(agentOptions),
+    httpsAgent: new https.Agent(agentOptions)
+  };
+};
 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,
@@ -219,7 +266,7 @@ const getRateLimitInfo = (headers) => {
   }
   return { limit, remaining, reset };
 };
-const normalizeAxiosError = (resolved, error) => {
+const normalizeAxiosError = (resolved, error, isRestCall = false) => {
   if (axios.isCancel(error)) {
     return new AniLinkNetworkError(
       AniLinkErrorCodes.ABORTED,
@@ -228,12 +275,11 @@ const normalizeAxiosError = (resolved, error) => {
     );
   }
   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) };
+    return isRestCall ? new AniLinkRestError(status, data, rawAxiosError, options) : new AniLinkApiError(status, data, rawAxiosError, options);
   }
   if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
     return new AniLinkNetworkError(
@@ -249,12 +295,12 @@ const normalizeAxiosError = (resolved, error) => {
     getRawAxiosError(resolved, error)
   );
 };
-const normalizeRequestError = (resolved, error) => {
+const normalizeRequestError = (resolved, error, isRestCall = false) => {
   if (error instanceof AniLinkError) {
     return error;
   }
   if (axios.isAxiosError(error)) {
-    return normalizeAxiosError(resolved, error);
+    return normalizeAxiosError(resolved, error, isRestCall);
   }
   return new AniLinkError(
     "The request failed.",
@@ -341,6 +387,22 @@ const safeInvoke = (hook, name, ...args) => {
   }
 };
 const circuitStates = /* @__PURE__ */ new WeakMap();
+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 circuitScopeOf = (url) => {
   try {
     return new URL(url).host;
@@ -427,6 +489,7 @@ const executeWithRetry = async (options, resolved, stateKey, rawPassthrough = fa
   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 budgetState = getRetryBudgetState(stateKey, resolved.retryBudget);
   let attempt = 0;
   for (; ; ) {
     throwIfCircuitOpen(circuit, resolved.circuitBreaker);
@@ -440,7 +503,9 @@ 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", {
         ...hookContext,
@@ -455,9 +520,12 @@ const executeWithRetry = async (options, resolved, stateKey, rawPassthrough = fa
         ...hookContext,
         durationMs: Date.now() - startedAt
       });
-      const normalized = normalizeRequestError(resolved, error);
+      const normalized = normalizeRequestError(resolved, error, rawPassthrough);
       recordCircuitFailure(circuit, resolved.circuitBreaker);
-      const delay = policy === null ? null : getRetryDelay(normalized, error, attempt, policy);
+      const delay = policy === null || budgetState === void 0 ? policy === null ? null : getRetryDelay(normalized, error, attempt, policy) : budgetState.retriesUsed >= resolved.retryBudget.maxRetriesPerWindow ? null : getRetryDelay(normalized, error, attempt, policy);
+      if (delay !== null && budgetState !== void 0) {
+        budgetState.retriesUsed += 1;
+      }
       reportFailure(url, method, attempt + 1, normalized, resolved, delay ?? void 0);
       if (delay === null) {
         throw normalized;
@@ -467,16 +535,24 @@ const executeWithRetry = async (options, resolved, stateKey, rawPassthrough = fa
     }
   }
 };
-const sendRequest = async (url, method, data, token, requiresAuth = false, options, operation, contentType) => {
-  if (requiresAuth && (token === null || token === void 0 || token === "")) {
+const sendRequest = async (url, method, data, auth, ...requestOptions) => {
+  const [requiresAuth = false, options, operation, contentType] = requestOptions;
+  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 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 result = await executeWithRetry(
     { url, method, data, headers },
@@ -500,7 +576,7 @@ class BaseOperation {
   /**
    * The authentication token shared by all operations of an instance.
    */
-  authToken;
+  requestAuth;
   /**
    * The transport settings resolved at construction time.
    */
@@ -508,21 +584,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;
@@ -544,14 +632,14 @@ class BaseOperation {
    * @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.
    * @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,
+      this.requestAuth,
       requiresAuth || void 0,
       mergeOptions(this.resolvedOptions, transportOptions),
       operation ?? resolveOperationLabel(this),
@@ -690,7 +778,7 @@ class GraphQLOperation extends BaseOperation {
    * @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.
    * @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) {
     const data = variables === void 0 ? { query } : { query, variables };
@@ -717,7 +805,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;
@@ -766,8 +854,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 {@link 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
    */
@@ -1635,12 +1723,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 +1763,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 +1807,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 +1875,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 +2246,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 +2307,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 +2342,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 +2411,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 +2457,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 +2524,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 +2946,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 +2994,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 +3045,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 +3093,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 +3135,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 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 +3165,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 +3207,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 +3350,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 +3368,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 +3461,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 +3523,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 +3658,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 +3696,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 +3766,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 +3833,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 +3942,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 +4158,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 +4197,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 +4259,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 +4310,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 +4375,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 +4422,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 +4527,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 +4626,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 +4680,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 +4790,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 +4848,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 +4949,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 +4995,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 +5049,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 +5100,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 +5147,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 +5191,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 +5233,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 +5265,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 +5311,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 +5359,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 +5405,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 +5447,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 +5486,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 +5533,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 +5575,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 +5619,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 +5659,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 +5705,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 {@link ToggleLikeV2Mutation.toggleLikeV2}, which returns the richer {@link 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 +5748,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 +5788,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 +5908,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 +5957,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 +6001,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 +6044,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 +6084,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 +6138,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 +6185,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 +6225,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 +6272,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 +6317,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 +6357,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 +6405,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 +6439,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 +6490,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 +6616,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 +6712,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 = `
@@ -6515,10 +6894,178 @@ 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 resolveTransportOptions = (credentials, providerFields) => {
+  const options = Object.fromEntries(
+    Object.entries(credentials).filter(([key]) => !providerFields.includes(key))
+  );
+  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 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 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 and
+   * PUT 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, and per-request transport settings.
+   * @param query - Query parameters appended to the URL (GET/DELETE), when provided.
+   * @param body - The JSON request body (POST/PUT), when provided.
+   * @param pathParams - Values substituted into `{placeholder}` segments of `path`. Defaults to an empty map so paths without placeholders need none.
+   * @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 = {}, query, body, pathParams = {}) {
+    const { method = "GET", requiresAuth = false, contentType, 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";
+    const effectiveContentType = contentType ?? "application/json";
+    return await this.dispatch(
+      url,
+      method,
+      carriesBody ? body : void 0,
+      requiresAuth,
+      void 0,
+      transportOptions,
+      effectiveContentType
+    );
+  }
+}
+
+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 },
+      fields === void 0 ? void 0 : { fields: Array.isArray(fields) ? fields.join(",") : fields },
+      void 0,
+      { 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 },
+      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 user = new MalUserOperation(auth, options);
+  return {
+    anime: { get: anime.get.bind(anime) },
+    user: { me: user.me.bind(user) }
+  };
+}
+
+const buildAniListClient = (credentials, legacyOptions) => {
+  const resolved = resolveAniListCredentials(credentials);
+  return buildAniListApi(resolved.auth, resolved.options ?? legacyOptions);
+};
+const buildMalClient = (credentials) => buildMyAnimeListApi(credentials);
+const PROVIDER_FACTORIES = {
+  anilist: buildAniListClient,
+  mal: buildMalClient
+};
+function buildProviderClients(credentials = {}, legacyOptions) {
+  return {
+    anilist: PROVIDER_FACTORIES.anilist(credentials.anilist, legacyOptions),
+    mal: PROVIDER_FACTORIES.mal(credentials.mal)
+  };
 }
 
 const AUTH_TOKEN_TIMEOUT_MS = 1e4;
@@ -6610,22 +7157,105 @@ const refreshAccessToken = async (clientId, clientSecret, refreshToken, signal)
 );
 const getTokenExpiry = (response, now = Date.now()) => new Date(now + response.expires_in * 1e3);
 
+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) => {
+  if (error instanceof AniLinkApiError) {
+    error.message = `MAL token request failed with status ${error.status}.`;
+    return error;
+  }
+  if (error instanceof AniLinkError) return error;
+  if (axios.isCancel(error)) {
+    return new AniLinkNetworkError(
+      AniLinkErrorCodes.ABORTED,
+      "The MAL token request was cancelled."
+    );
+  }
+  if (axios.isAxiosError(error)) {
+    if (error.response?.status !== void 0) {
+      const apiError = new AniLinkApiError(error.response.status, error.response.data);
+      apiError.message = `MAL token request failed with status ${error.response.status}.`;
+      return apiError;
+    }
+    if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
+      return new AniLinkNetworkError(
+        AniLinkErrorCodes.TIMEOUT,
+        "The MAL token request timed out."
+      );
+    }
+    return new AniLinkNetworkError(
+      AniLinkErrorCodes.NETWORK,
+      "The MAL token request failed due to a network error."
+    );
+  }
+  return new AniLinkError("The MAL token request failed.", AniLinkErrorCodes.UNKNOWN);
+};
+const requestMalToken = async (params, options) => {
+  try {
+    return await sendRequest(
+      MAL_TOKEN_URL,
+      "POST",
+      new URLSearchParams(params).toString(),
+      void 0,
+      false,
+      {
+        ...options,
+        timeout: options?.timeout ?? MAL_AUTH_TIMEOUT_MS,
+        exposeRawAxiosError: false
+      },
+      void 0,
+      "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 +7282,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, buildAuthorizationUrl, buildMalAuthorizationUrl, buildMyAnimeListApi, buildProviderClients, getAccessToken, getMalAccessToken, getMalTokenExpiry, getTokenExpiry, paginate, paginateChunks, paginatePages, refreshAccessToken, refreshMalAccessToken };