anilink-api-wrapper 2.1.0 → 2.2.0

package/dist/AniLink.d.ts

@@ -42,14 +42,26 @@ declare class AniLinkError extends Error {
     code: AniLinkErrorCode;
     /** Original Axios or transport error when raw diagnostics were enabled. */
     readonly rawAxiosError?: unknown;
+    /**
+     * Library-generated correlation ID joining this failure to the
+     * `onRequestStart`/`onResponse`/`onRetry`/`onError` hook events it
+     * produced, so a caught error can be matched to its lifecycle stream in a
+     * metrics or logging backend. Absent on errors raised outside the
+     * request pipeline (for example validation errors thrown before any
+     * request is sent).
+     */
+    readonly requestId?: string;
     /**
      * Creates a sanitized AniLink error.
      *
      * @param message - A safe message intended for application logs.
      * @param code - The stable code used to classify the failure.
      * @param rawAxiosError - The original Axios error when raw diagnostics are enabled.
+     * @param options - Additional error metadata such as the request correlation ID.
      */
-    constructor(message: string, code: AniLinkErrorCode, rawAxiosError?: unknown);
+    constructor(message: string, code: AniLinkErrorCode, rawAxiosError?: unknown, options?: {
+        requestId?: string;
+    });
 }
 /**
  * Rate-limit accounting parsed from provider response headers.
@@ -89,16 +101,27 @@ declare class AniLinkApiError extends AniLinkError {
      * included in the error message so logs stay clean.
      */
     readonly rateLimit?: RateLimitInfo;
+    /**
+     * The `Content-Type` of the failing response, parsed from the upstream
+     * response headers. REST providers such as MyAnimeList return HTML or
+     * plain-text bodies on rate-limit and gateway error paths; this field lets
+     * consumers distinguish a structured JSON failure payload (where
+     * `data.message` is meaningful) from a non-JSON one without guessing.
+     * Absent when the response carried no `Content-Type` header.
+     */
+    readonly contentType?: string;
     /**
      * Creates an API error while preserving the upstream response body.
      *
      * @param status - The HTTP status returned by AniList.
      * @param data - The response body returned by AniList.
      * @param rawAxiosError - The original Axios error when raw diagnostics are enabled.
-     * @param options - Additional error metadata such as rate-limit headers.
+     * @param options - Additional error metadata such as rate-limit headers and the response content type.
      */
     constructor(status: number, data: unknown, rawAxiosError?: unknown, options?: {
         rateLimit?: RateLimitInfo;
+        contentType?: string;
+        requestId?: string;
     });
 }
 /**
@@ -159,8 +182,13 @@ declare class AniLinkGraphQLError extends AniLinkApiError {
      * @param errors - The upstream GraphQL errors; each entry should carry a `message`.
      * @param data - The partial `data` object returned alongside the errors, when any. Exposed as {@link AniLinkGraphQLError.partialData}.
      * @param rawAxiosError - The original Axios error when raw diagnostics are enabled.
+     * @param options - Additional error metadata such as rate-limit headers and the response content type. AniList returns rate-limit headers even on HTTP 200 envelopes carrying GraphQL errors (for example a GraphQL-level `429`), so threading them here keeps {@link AniLinkGraphQLError.rateLimit} consistent with the HTTP-failure path.
      */
-    constructor(errors: ReadonlyArray<GraphQLUpstreamError>, data?: unknown, rawAxiosError?: unknown);
+    constructor(errors: ReadonlyArray<GraphQLUpstreamError>, data?: unknown, rawAxiosError?: unknown, options?: {
+        rateLimit?: RateLimitInfo;
+        contentType?: string;
+        requestId?: string;
+    });
 }
 /**
  * Failure caused by a missing authentication token on a protected operation.
@@ -208,10 +236,12 @@ declare class AniLinkRestError extends AniLinkApiError {
      * @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.
+     * @param options - Additional error metadata such as rate-limit headers, the response content type, and the request correlation ID.
      */
     constructor(status: number, data: unknown, rawAxiosError?: unknown, options?: {
         rateLimit?: RateLimitInfo;
+        contentType?: string;
+        requestId?: string;
     });
 }
 /**
@@ -222,6 +252,14 @@ declare class AniLinkRestError extends AniLinkApiError {
 interface AniLinkNetworkErrorOptions {
     /** The effective per-attempt timeout in milliseconds, when a timeout was configured and enforced. */
     timeoutMs?: number;
+    /**
+     * `true` when the abort happened during the post-success rate-limit
+     * pacing wait rather than while the request was in flight. The upstream
+     * request itself succeeded in that case, so consumers can distinguish
+     * "data was received but the caller's wait was cancelled" from a cancelled
+     * request. Absent for every other abort.
+     */
+    abortedDuringPacing?: boolean;
 }
 /**
  * Network, timeout, cancellation, or circuit-breaker failure.
@@ -237,15 +275,152 @@ declare class AniLinkNetworkError extends AniLinkError {
      * timeout is disabled (`0`) or the failure is not a timeout.
      */
     readonly timeoutMs?: number;
+    /**
+     * `true` when this abort happened during the post-success rate-limit
+     * pacing wait (see {@link AniLinkNetworkErrorOptions.abortedDuringPacing}).
+     * The upstream attempt already succeeded when this is set.
+     */
+    readonly abortedDuringPacing?: boolean;
     /**
      * Creates a sanitized transport error.
      *
      * @param code - The stable code for the transport failure.
      * @param message - A safe message intended for application logs.
      * @param rawAxiosError - The original Axios error when raw diagnostics are enabled.
-     * @param options - Additional transport metadata such as the effective timeout duration.
+     * @param options - Additional transport metadata such as the effective timeout duration and the request correlation ID.
      */
-    constructor(code: typeof AniLinkErrorCodes.NETWORK | typeof AniLinkErrorCodes.TIMEOUT | typeof AniLinkErrorCodes.ABORTED | typeof AniLinkErrorCodes.CIRCUIT, message: string, rawAxiosError?: unknown, options?: AniLinkNetworkErrorOptions);
+    constructor(code: typeof AniLinkErrorCodes.NETWORK | typeof AniLinkErrorCodes.TIMEOUT | typeof AniLinkErrorCodes.ABORTED | typeof AniLinkErrorCodes.CIRCUIT, message: string, rawAxiosError?: unknown, options?: AniLinkNetworkErrorOptions & {
+        requestId?: string;
+    });
+}
+
+/**
+ * Opt-in in-memory TTL response cache for read-heavy traversals.
+ *
+ * The cache is keyed by `(method, url, serialized body)` and capped by
+ * `maxEntries`. It is opt-in (off by default) and never caches mutations
+ * (`POST`/`PUT`/`DELETE`). Cache hits are observable through the existing
+ * `onResponse` hook via a `cacheHit` flag so consumers can distinguish a
+ * cached response from a network round-trip.
+ */
+/**
+ * Configuration for the opt-in response cache.
+ */
+interface ResponseCacheOptions {
+    /** The time-to-live for cached entries, in milliseconds. Defaults to 60_000 (1 minute). */
+    ttlMs?: number;
+    /** The maximum number of entries to retain. Defaults to 128. Entries are evicted LRU when the cap is reached. */
+    maxEntries?: number;
+}
+/**
+ * An in-memory TTL response cache with an LRU eviction cap.
+ *
+ * The cache is per-instance (one per `AniLink` client when enabled) so cache
+ * state never leaks across clients. Entries expire after `ttlMs` and the
+ * cache is capped at `maxEntries` with least-recently-used eviction.
+ *
+ * **Aliasing:** values returned from {@link ResponseCache.get} are deep
+ * clones of the cached entry, so a caller that mutates the returned object
+ * cannot corrupt the cached copy or affect subsequent reads.
+ *
+ * **Invalidation:** the cache is TTL-only. Mutations (`POST`/`PUT`/`DELETE`)
+ * sent through the same client do not invalidate cached `GET` responses, so
+ * a read-after-write sequence can return stale data for up to `ttlMs`. Use
+ * {@link ResponseCache.delete} for targeted invalidation, or
+ * {@link ResponseCache.clear} to drop everything. Keep `ttlMs` short for
+ * read-after-write-sensitive workloads.
+ *
+ * **Privacy:** the cache stores the full response body of every `GET`
+ * request when enabled, including authenticated user-scoped responses
+ * (for example `/Viewer`-style queries that return the user's profile or
+ * email). Cached bodies are retained in plaintext in the JS heap for up to
+ * `ttlMs` and are accessible to any code holding a reference to the
+ * `ResponseCache` instance. Entries are scoped by a SHA-256 hash of the
+ * bearer token so cached responses never cross identities, but within one
+ * identity sensitive payloads are retained verbatim. Do not enable the
+ * cache for clients that fetch private user data unless `ttlMs` is short
+ * and the cache instance is not shared across trust boundaries.
+ */
+declare class ResponseCache {
+    private readonly entries;
+    private readonly ttlMs;
+    private readonly maxEntries;
+    /**
+     * Creates a response cache.
+     *
+     * @param options - Cache configuration; `ttlMs` defaults to 60_000, `maxEntries` to 128.
+     */
+    constructor(options?: ResponseCacheOptions);
+    /**
+     * Builds the cache key for a request.
+     *
+     * The serialized body is SHA-256 hashed (truncated to 16 hex chars)
+     * before it enters the key, so a credential-bearing GET body is never
+     * duplicated into the key string in plaintext — the key map retains
+     * entries for up to the TTL, outliving the error paths the rest of the
+     * library scrubs. The hash is deterministic, so equal bodies still share
+     * one entry and different bodies still get different entries.
+     *
+     * @param method - The HTTP method.
+     * @param url - The request URL.
+     * @param data - The request body, when present.
+     * @param authKey - An authentication-safe credential identity, so cached
+     * responses never cross bearer-token identities.
+     * @returns The cache key.
+     */
+    private static buildKey;
+    /**
+     * Reads a cached response for the given request, or `undefined` when the
+     * entry is absent or expired. Expired entries are evicted on read. The
+     * returned value is a deep clone of the cached entry, so a caller that
+     * mutates it cannot corrupt the cached copy or affect subsequent reads.
+     *
+     * @param method - The HTTP method.
+     * @param url - The request URL.
+     * @param data - The request body, when present.
+     * @param authKey - An authentication-safe credential identity, so cached
+     * responses never cross bearer-token identities.
+     * @returns A deep clone of the cached response body, or `undefined`.
+     */
+    get<T>(method: string, url: string, data?: object | string, authKey?: string): T | undefined;
+    /**
+     * Stores a response in the cache, evicting the LRU entry when the cap is
+     * reached. Only `GET` responses are cached; other methods are no-ops.
+     * The value is deep-copied on write; the cache never aliases the
+     * caller's object.
+     *
+     * @param method - The HTTP method.
+     * @param url - The request URL.
+     * @param data - The request body, when present.
+     * @param authKey - An authentication-safe credential identity, so cached
+     * responses never cross bearer-token identities.
+     * @param response - The response body to cache.
+     */
+    set<T>(method: string, url: string, data: object | string | undefined, authKey: string | undefined, response: T): void;
+    /**
+     * Removes the cached entry for the given request, if present. Use this
+     * for targeted invalidation after a mutation that changes the resource
+     * (for example a `POST` that updates the entity a cached `GET` returned).
+     * Only `GET` entries are tracked, so non-`GET` methods are a no-op and
+     * return `false`.
+     *
+     * @param method - The HTTP method.
+     * @param url - The request URL.
+     * @param data - The request body, when present.
+     * @param authKey - An authentication-safe credential identity, so cached
+     * responses never cross bearer-token identities.
+     * @returns `true` when an entry was removed, `false` when it was absent
+     *          or the method is not cached.
+     */
+    delete(method: string, url: string, data?: object | string, authKey?: string): boolean;
+    /**
+     * Evicts the least-recently-used entry.
+     */
+    private evictLru;
+    /**
+     * Clears all cached entries.
+     */
+    clear(): void;
 }
 
 /**
@@ -294,12 +469,12 @@ interface RetryPolicy {
  * HTTP methods the shared transport accepts.
  *
  * GraphQL providers use `POST` only; REST providers additionally use `GET`,
- * `PUT`, and `DELETE`. The union is shared so hooks and error contexts stay
- * provider-agnostic.
+ * `PUT`, `PATCH`, and `DELETE`. The union is shared so hooks and error
+ * contexts stay provider-agnostic.
  *
  * @see {@link sendRequest}
  */
-type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 /**
  * Authentication material a provider can apply to an HTTP request.
  *
@@ -323,6 +498,13 @@ type RequestAuthInput = string | RequestAuth;
  * @see {@link OnErrorHandler}
  */
 interface RequestErrorContext {
+    /**
+     * Library-generated correlation ID identifying one logical request across
+     * all of its attempts. Use it to join `onRequestStart`, `onResponse`,
+     * `onError`, and `onRetry` events for the same request in a metrics or
+     * logging backend.
+     */
+    requestId: string;
     /** The URL the request was sent to. */
     url: string;
     /** The HTTP method of the request. */
@@ -335,6 +517,11 @@ interface RequestErrorContext {
     status?: number;
     /** The delay before the next retry, when the failure will be retried. */
     nextDelayMs?: number;
+    /**
+     * Rate-limit accounting parsed from the failure response's
+     * `x-ratelimit-*` headers, when the upstream included them.
+     */
+    rateLimit?: RateLimitInfo;
 }
 /**
  * Callback invoked when an attempt fails, before each retry wait and once more when retries are exhausted.
@@ -349,6 +536,11 @@ type OnErrorHandler = (error: AniLinkError, context: RequestErrorContext) => voi
  * @see {@link OnRequestStartHandler}
  */
 interface RequestContext {
+    /**
+     * Library-generated correlation ID identifying one logical request across
+     * all of its attempts; see {@link RequestErrorContext.requestId}.
+     */
+    requestId: string;
     /** The URL the request is being sent to. */
     url: string;
     /** The HTTP method of the request. */
@@ -364,14 +556,64 @@ interface RequestContext {
  */
 type OnRequestStartHandler = (context: RequestContext) => void;
 /**
- * A callback invoked after each attempt completes, whether it succeeded or
- * failed. The elapsed wall-clock time of the attempt is reported as
- * `durationMs`, making this the natural point for latency metrics.
+ * A callback invoked after each attempt completes with the elapsed
+ * `durationMs` and parsed `rateLimit` headers when present. When the response
+ * was served from the opt-in response cache, `cacheHit` is `true` and
+ * `durationMs` is `0`.
  *
  * @see {@link RequestOptions.onResponse}
  */
 type OnResponseHandler = (context: RequestContext & {
     durationMs: number;
+    rateLimit?: RateLimitInfo;
+    cacheHit?: boolean;
+}) => void;
+/**
+ * A callback invoked when proactive rate-limit pacing delays the next request
+ * after a successful attempt, with the pacing wait in `delayMs`.
+ *
+ * @see {@link RequestOptions.onPace}
+ */
+type OnPaceHandler = (context: RequestContext & {
+    delayMs: number;
+}) => void;
+/**
+ * A callback invoked when a user-supplied lifecycle hook throws. Throwing
+ * hooks never affect the request pipeline; this callback only observes the
+ * failure so it can be routed to a logger or metrics backend. When unset,
+ * hook failures fall back to a `console.warn`.
+ *
+ * @see {@link RequestOptions.onHookError}
+ */
+type OnHookErrorHandler = (hookName: string, error: unknown) => void;
+/**
+ * Context passed to the `onCircuitOpen` hook when the circuit breaker trips.
+ *
+ * @see {@link OnCircuitOpenHandler}
+ */
+interface CircuitOpenContext extends RequestContext {
+    /** The upstream host scope the breaker tripped for. */
+    host: string;
+    /** The consecutive-failure count that reached the threshold. */
+    failures: number;
+}
+/**
+ * A callback invoked when the circuit breaker opens (trips) after the
+ * consecutive-failure threshold is reached, so dashboards can plot trip
+ * frequency and time-to-half-open without scraping `CIRCUIT_OPEN_ERROR` codes.
+ *
+ * @see {@link RequestOptions.onCircuitOpen}
+ */
+type OnCircuitOpenHandler = (context: CircuitOpenContext) => void;
+/**
+ * A callback invoked when the circuit breaker closes (returns to healthy)
+ * after a successful post-cooldown probe, so dashboards can plot open
+ * duration and recovery without inferring it from error-code absence.
+ *
+ * @see {@link RequestOptions.onCircuitClose}
+ */
+type OnCircuitCloseHandler = (context: RequestContext & {
+    host: string;
 }) => void;
 /**
  * Transport settings shared by the AniLink request operations.
@@ -455,10 +697,86 @@ interface RequestOptions {
     onRetry?: OnErrorHandler;
     /** Invoked just before each attempt is sent. */
     onRequestStart?: OnRequestStartHandler;
-    /** Invoked after each attempt completes with the elapsed `durationMs`. */
+    /** Invoked after each attempt completes with the elapsed `durationMs` and the parsed `rateLimit` headers when present. */
     onResponse?: OnResponseHandler;
+    /**
+     * Invoked when proactive rate-limit pacing ({@link RequestOptions.paceWithRateLimit})
+     * delays the next request after a successful attempt, with the pacing
+     * wait in `delayMs`.
+     */
+    onPace?: OnPaceHandler;
+    /**
+     * Invoked when a user-supplied lifecycle hook throws. Throwing hooks are
+     * always isolated from the request pipeline; this callback observes the
+     * failure so it can be routed to a logger or metrics backend. When unset,
+     * hook failures are reported via `console.warn`.
+     */
+    onHookError?: OnHookErrorHandler;
+    /**
+     * Invoked when the circuit breaker opens (trips) after the
+     * consecutive-failure threshold is reached. Carries the host scope and
+     * the failure count so consumers can plot trip frequency and alert on
+     * sustained outages without parsing `CIRCUIT_OPEN_ERROR` codes.
+     *
+     * @see {@link OnCircuitOpenHandler}
+     */
+    onCircuitOpen?: OnCircuitOpenHandler;
+    /**
+     * Invoked when the circuit breaker closes (returns to healthy) after a
+     * successful post-cooldown probe, so consumers can plot open duration and
+     * recovery without inferring it from error-code absence.
+     *
+     * @see {@link OnCircuitCloseHandler}
+     */
+    onCircuitClose?: OnCircuitCloseHandler;
+    /**
+     * Bypass the shared rate-limit pacing deadline recorded by a prior
+     * successful response to the same host, so an urgent single request
+     * (for example a user-facing lookup during a rate-limited window) is not
+     * held hostage by a deadline recorded from an earlier bulk request on
+     * the same client. Defaults to `false`; the per-request `signal` is still
+     * honored.
+     *
+     * @see {@link RequestOptions.paceWithRateLimit}
+     */
+    ignorePaceDeadline?: boolean;
+    /**
+     * Opt-in in-memory TTL response cache for read-heavy traversals. When
+     * set, `GET` responses are cached by `(method, url, serialized body)`
+     * for the cache's TTL window so repeated identical reads skip the network
+     * round-trip entirely. Mutations (`POST`/`PUT`/`DELETE`) are never cached.
+     * Off by default; pass a `ResponseCache` instance to enable.
+     *
+     * **Privacy:** the cache retains the full response body of every cached
+     * `GET` in plaintext for the TTL window, including authenticated
+     * user-scoped responses. Entries are scoped by a hash of the bearer
+     * token so they never cross identities, but within one identity
+     * sensitive payloads are retained. Do not enable for clients that fetch
+     * private user data unless the TTL is short and the cache instance is
+     * not shared across trust boundaries.
+     *
+     * @see {@link ResponseCache}
+     */
+    responseCache?: ResponseCache;
 }
 
+/**
+ * Destroys every cached custom agent pair — plus every pair evicted while
+ * requests may still have been in flight — and clears the cache. Intended
+ * for tests and explicit teardown so long-lived processes can release the
+ * keep-alive sockets held by customized agents on demand.
+ *
+ * **Must not be called while requests using these agents are in-flight.**
+ * The agents are shared across every request with identical
+ * `maxSockets`/`maxFreeSockets` bounds, so destroying them closes the
+ * underlying sockets and can fail concurrent requests that are still
+ * draining over those sockets. Call this only after all in-flight requests
+ * have settled (for example in a shutdown hook that has awaited the final
+ * request, or in test teardown after the test's assertions). Calling it
+ * twice is safe (the second call iterates an empty cache).
+ */
+declare const destroyCachedAgents: () => void;
+
 /**
  * The `custom` member group of the `AniListApi` type.
  *
@@ -8841,7 +9159,7 @@ type AniListQueries = {
         /**
          * `GenreCollectionQuery` returns the list of all genres recognized by AniList. No variables are required.
          * @param options - Optional per-request transport settings ({@link RequestOptions}) merged over the instance-level ones for this call only.
-         * @returns {Promise<string>} A promise that resolves to the genre collection data.
+         * @returns {Promise<string[]>} A promise that resolves to the genre collection data (a list of genre strings).
          *
          * @example
          * ```typescript
@@ -8849,7 +9167,7 @@ type AniListQueries = {
          * ```
          * @see https://docs.anilist.co/reference/query
          */
-        genreCollection: (options?: RequestOptions) => Promise<string>;
+        genreCollection: (options?: RequestOptions) => Promise<string[]>;
         /**
          * `MediaTagCollectionQuery` returns all media tags recognized by AniList, optionally filtered by `variables`. Returns a {@link MediaTagCollectionResponse}.
          * @param {MediaTagCollectionVariables} variables - Optional {@link MediaTagCollectionVariables} filters for the query.
@@ -8876,7 +9194,7 @@ type AniListQueries = {
          * Must be authenticated.
          * @see https://docs.anilist.co/reference/object/user
          */
-        viewer: (variables: UserVariables, options?: RequestOptions) => Promise<UserResponse>;
+        viewer: (variables?: UserVariables, options?: RequestOptions) => Promise<UserResponse>;
         /**
          * `NotificationQuery` fetches a single notification by `id`. Returns a {@link NotificationResponse}. Must be authenticated.
          * @param {NotificationVariables} variables - The {@link NotificationVariables} for the query.
@@ -11414,17 +11732,49 @@ interface PaginateOptions {
     perPage?: number;
     /** 1-based page number to start from. Defaults to 1. */
     startPage?: number;
-    /** Hard cap on pages fetched, guarding against unbounded loops. Defaults to 100. */
+    /**
+     * Hard cap on pages fetched, guarding against unbounded loops. Defaults
+     * to 100, which means up to 100 round-trips (up to 5,000 items at the
+     * default `perPage`); set an explicit value for cost-sensitive workloads.
+     */
     maxPages?: number;
     /**
      * Maximum number of page requests kept in flight at once while collecting
      * results. Pages are always returned in order regardless of completion
      * order, scheduling stops as soon as a fetched page reports
      * `hasNextPage: false`, and every existing guard (`maxPages`, `perPage`
-     * clamping) still applies. Defaults to `1` (strictly sequential fetches,
-     * matching previous behavior). Values above 8 are clamped down to 8.
+     * clamping) still applies. Defaults to `3`
+     * (a small look-ahead window); pass `1` for strictly sequential fetches.
+     * Values above 8 are clamped down to 8.
      */
     concurrency?: number;
+    /**
+     * Optional `AbortSignal` to cancel the traversal. When aborted, all
+     * in-flight look-ahead page requests are cancelled immediately so they
+     * stop consuming rate-limit budget and bandwidth for payloads that will
+     * be discarded. The signal is also forwarded to `fetchPage` calls so the
+     * transport layer can abort the underlying HTTP request.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional per-page callback invoked once per page **after all responses
+     * have been collected**, as the results are gathered into the returned
+     * `PaginateResult`. This is a post-collection notification, not a
+     * streaming hook: because the eager helpers collect every response before
+     * returning, this callback does **not** reduce peak memory or release
+     * collected items incrementally. For true streaming, early-exit, or
+     * memory-bounded workflows, use {@link paginatePages} instead — it yields
+     * each page as it arrives and lets the consumer `break` or `return` to
+     * stop the traversal. The callback receives the page's `pageInfo` and
+     * items array; the full `PaginateResult` is still returned for callers
+     * that need the collected items. Errors thrown by the callback are
+     * caught, reported via `console.warn`, and swallowed, so a failing
+     * observer cannot fail {@link paginate} or stop the traversal.
+     */
+    onPage?: (page: {
+        pageInfo: PageInfo;
+        items: unknown[];
+    }) => void;
 }
 /** Options controlling a {@link paginateChunks} traversal over `hasNextChunk`-based chunks. */
 interface ChunkPaginateOptions {
@@ -11435,17 +11785,49 @@ interface ChunkPaginateOptions {
     perChunk?: number;
     /** 1-based chunk number to start from. Defaults to 1. */
     startChunk?: number;
-    /** Hard cap on chunks fetched, guarding against unbounded loops. Defaults to 100. */
+    /**
+     * Hard cap on chunks fetched, guarding against unbounded loops. Defaults
+     * to 100, which means up to 100 round-trips and up to 50,000 items at the
+     * default `perChunk`; set an explicit value for cost-sensitive workloads.
+     */
     maxChunks?: number;
     /**
      * Maximum number of chunk requests kept in flight at once while collecting
      * results. Chunks are always returned in order regardless of completion
      * order, scheduling stops as soon as a fetched chunk reports
      * `hasNextChunk: false`, and every existing guard (`maxChunks`, `perChunk`
-     * clamping) still applies. Defaults to `1` (strictly sequential fetches,
-     * matching previous behavior). Values above 8 are clamped down to 8.
+     * clamping) still applies. Defaults to `3`
+     * (a small look-ahead window); pass `1` for strictly sequential fetches.
+     * Values above 8 are clamped down to 8.
      */
     concurrency?: number;
+    /**
+     * Optional `AbortSignal` to cancel the traversal. When aborted, all
+     * in-flight look-ahead chunk requests are cancelled immediately so they
+     * stop consuming rate-limit budget and bandwidth for payloads that will
+     * be discarded.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional per-chunk callback invoked once per chunk **after all responses
+     * have been collected**, as the results are gathered into the returned
+     * `ChunkPaginateResult`. This is a post-collection notification, not a
+     * streaming hook: because the eager helpers collect every response before
+     * returning, this callback does **not** reduce peak memory or release
+     * collected items incrementally. For true streaming, early-exit, or
+     * memory-bounded workflows, use {@link paginatePages} instead — it yields
+     * each page as it arrives and lets the consumer `break` or `return` to
+     * stop the traversal. The callback receives the chunk's `hasNextChunk`
+     * flag and items array; the full `ChunkPaginateResult` is still returned
+     * for callers that need the collected items. Errors thrown by the
+     * callback are caught, reported via `console.warn`, and swallowed, so a
+     * failing observer cannot fail {@link paginateChunks} or stop the
+     * traversal.
+     */
+    onChunk?: (chunk: {
+        hasNextChunk: boolean;
+        items: unknown[];
+    }) => void;
 }
 /** The outcome of a {@link paginate} traversal. */
 interface PaginateResult<TItem> {
@@ -11482,19 +11864,21 @@ interface ChunkPaginateResult<TItem> {
  * array at `itemsKey`, and stops when AniList reports no further pages or when the
  * `maxPages` guard fires. The guard prevents accidental unbounded fetch loops.
  * Pass `concurrency` to keep multiple page requests in flight at once; results
- * are still collected strictly in page order.
+ * are still collected strictly in page order. The default `maxPages` of 100
+ * means an unconstrained traversal can issue up to 100 round-trips; set an
+ * explicit `maxPages` for cost-sensitive workloads.
  *
  * @typeParam TPage - The page response shape (must include `pageInfo`).
  * @typeParam K - The key of the items array on `TPage`.
- * @param fetchPage - Callback that fetches a single page given its 1-based number and `perPage`.
+ * @param fetchPage - Callback that fetches a single page given its 1-based number, `perPage`, and an optional `AbortSignal` forwarded from the traversal.
  * @param itemsKey - The key of the items array on the page response (e.g. `"media"`, `"users"`).
- * @param options - Optional `perPage`, `startPage`, `maxPages`, and `concurrency` controls.
+ * @param options - Optional `perPage`, `startPage`, `maxPages`, `concurrency`, `signal`, and `onPage` controls.
  * @returns The collected items, per-page snapshots, page count, and whether the guard truncated the run.
  * @see https://docs.anilist.co/reference/object/pageinfo
  * @example
  * ```typescript
  * const result = await paginate(
- *   (page, perPage) => aniLink.anilist.query.page.medias({ page, perPage, type: "ANIME" }),
+ *   (page, perPage, signal) => aniLink.anilist.query.page.medias({ page, perPage, type: "ANIME" }, { signal }),
  *   "media",
  *   { perPage: 50, maxPages: 10, concurrency: 4 }
  * );
@@ -11503,23 +11887,32 @@ interface ChunkPaginateResult<TItem> {
  */
 declare function paginate<TPage extends {
     pageInfo: PageInfo;
-}, K extends ArrayKeys<TPage> & keyof TPage>(fetchPage: (page: number, perPage: number) => Promise<TPage>, itemsKey: K, options?: PaginateOptions): Promise<PaginateResult<ArrayElement<TPage, K>>>;
+}, K extends ArrayKeys<TPage> & keyof TPage>(fetchPage: (page: number, perPage: number, signal?: AbortSignal) => Promise<TPage>, itemsKey: K, options?: PaginateOptions): Promise<PaginateResult<ArrayElement<TPage, K>>>;
 /**
  * Async generator that yields each {@link PageInfo}-based page response until
  * `hasNextPage` is false or `maxPages` is reached.
  *
  * Use this for streaming or early-exit workflows where collecting every item
- * into memory is unnecessary. The `maxPages` guard still prevents unbounded loops.
+ * into memory is unnecessary. The `maxPages` guard still prevents unbounded
+ * loops. Unlike the sequential implementations it replaces, this generator
+ * keeps a small look-ahead window of `concurrency` in-flight page requests so
+ * round-trip latency overlaps while pages are still yielded strictly in page
+ * order; on early exit (`break`/`return` by the consumer), a terminal page,
+ * or the `maxPages` guard, already-launched stragglers are drained and their
+ * payloads discarded.
+ *
+ * The default `maxPages` of 100 means an unconstrained traversal can issue up
+ * to 100 round-trips; set an explicit `maxPages` for cost-sensitive workloads.
  *
  * @typeParam TPage - The page response shape (must include `pageInfo`).
- * @param fetchPage - Callback that fetches a single page given its 1-based number and `perPage`.
- * @param options - Optional `perPage`, `startPage`, and `maxPages` controls.
- * @yields Each raw page response in turn.
+ * @param fetchPage - Callback that fetches a single page given its 1-based number, `perPage`, and an optional `AbortSignal` forwarded from the traversal.
+ * @param options - Optional `perPage`, `startPage`, `maxPages`, `concurrency`, and `signal` controls. `concurrency` defaults to a small look-ahead window; pass `1` for strictly sequential fetches.
+ * @yields Each raw page response in turn, in page order.
  * @see https://docs.anilist.co/reference/object/pageinfo
  * @example
  * ```typescript
  * for await (const page of paginatePages(
- *   (page, perPage) => aniLink.anilist.query.page.medias({ page, perPage, type: "ANIME" })
+ *   (page, perPage, signal) => aniLink.anilist.query.page.medias({ page, perPage, type: "ANIME" }, { signal })
  * )) {
  *   console.log(page.pageInfo.currentPage, page.media.length);
  *   if (page.media.length > 0 && page.media[0].id === 1) break;
@@ -11528,7 +11921,7 @@ declare function paginate<TPage extends {
  */
 declare function paginatePages<TPage extends {
     pageInfo: PageInfo;
-}>(fetchPage: (page: number, perPage: number) => Promise<TPage>, options?: PaginateOptions): AsyncGenerator<TPage>;
+}>(fetchPage: (page: number, perPage: number, signal?: AbortSignal) => Promise<TPage>, options?: PaginateOptions): AsyncGenerator<TPage>;
 /**
  * Iterate `MediaListCollection` chunks until `hasNextChunk` is false or `maxChunks` is reached.
  *
@@ -11537,20 +11930,23 @@ declare function paginatePages<TPage extends {
  * extracts the items array at `itemsKey` (typically `"lists"`), and stops when AniList
  * reports no further chunks or when the `maxChunks` guard fires. Pass
  * `concurrency` to keep multiple chunk requests in flight at once; results are
- * still collected strictly in chunk order.
+ * still collected strictly in chunk order. The default `maxChunks` of 100
+ * means an unconstrained traversal can issue up to 100 round-trips (up to
+ * 50,000 items at the default `perChunk`); set an explicit `maxChunks` for
+ * cost-sensitive workloads.
  *
  * @typeParam TChunk - The chunk response shape (must include `hasNextChunk`).
  * @typeParam K - The key of the items array on `TChunk`.
- * @param fetchChunk - Callback that fetches a single chunk given its 1-based number and `perChunk`.
+ * @param fetchChunk - Callback that fetches a single chunk given its 1-based number, `perChunk`, and an optional `AbortSignal` forwarded from the traversal.
  * @param itemsKey - The key of the items array on the chunk response (e.g. `"lists"`).
- * @param options - Optional `perChunk`, `startChunk`, `maxChunks`, and `concurrency` controls.
+ * @param options - Optional `perChunk`, `startChunk`, `maxChunks`, `concurrency`, `signal`, and `onChunk` controls.
  * @returns The collected items, per-chunk snapshots, chunk count, and whether the guard truncated the run.
  * @see https://docs.anilist.co/reference/object/medialistcollection
  * @example
  * ```typescript
  * const result = await paginateChunks(
- *   (chunk, perChunk) => aniLink.anilist.query.mediaListCollection(
- *     { userId: 542244, type: "ANIME", chunk, perChunk }
+ *   (chunk, perChunk, signal) => aniLink.anilist.query.mediaListCollection(
+ *     { userId: 542244, type: "ANIME", chunk, perChunk }, { signal }
  *   ),
  *   "lists",
  *   { perChunk: 500, maxChunks: 20, concurrency: 3 }
@@ -11560,7 +11956,7 @@ declare function paginatePages<TPage extends {
  */
 declare function paginateChunks<TChunk extends {
     hasNextChunk: boolean;
-}, K extends ArrayKeys<TChunk> & keyof TChunk>(fetchChunk: (chunk: number, perChunk: number) => Promise<TChunk>, itemsKey: K, options?: ChunkPaginateOptions): Promise<ChunkPaginateResult<ArrayElement<TChunk, K>>>;
+}, K extends ArrayKeys<TChunk> & keyof TChunk>(fetchChunk: (chunk: number, perChunk: number, signal?: AbortSignal) => Promise<TChunk>, itemsKey: K, options?: ChunkPaginateOptions): Promise<ChunkPaginateResult<ArrayElement<TChunk, K>>>;
 
 /**
  * The pagination and pure-helper members of the `AniListApi` type.
@@ -11675,10 +12071,13 @@ type AniListHelpers = {
 /**
  * AniList provider facade.
  *
- * Adding an operation touches four sites: the operation class under `query/`
- * or `mutation/`, its declaration on one of the group types under `facade/`
- * (composed into {@link AniListApi} below), and its instance wiring in
- * `wiring.ts`.
+ * Adding an operation touches three sites: the operation class under `query/`
+ * or `mutation/`, its entry in the declarative registry in `registry.ts`, and
+ * its declaration on one of the group types under `facade/` (composed into
+ * {@link AniListApi} below). Instance wiring in `wiring.ts` is automatic from
+ * the registry, and the group modules carry a compile-time
+ * `Record<RegistryXxxKeys, true>` parity constant so the registry
+ * and the typed surface cannot drift without failing `tsc`.
  */
 
 /**
@@ -11714,11 +12113,12 @@ type AniLinkOptions = RequestOptions;
 type AniListApi = AniListCustom & AniListQueries & AniListMutations & AniListHelpers;
 
 /**
- * {@link MalPicture} is the image variants returned by MyAnimeList for an anime entity.
+ * {@link MalPicture} is the image variants returned by MyAnimeList for an anime or manga entity.
  *
- * It is the `main_picture` shape inside {@link MalAnime} and is selected via {@link MalRequestOptions.fields} through `MalAnimeOperation.get` and `MyAnimeListAnimeApi.get`.
+ * It is the `main_picture` shape inside {@link MalAnime} and {@link MalManga} and is selected via {@link MalRequestOptions.fields} through `MalAnimeOperation.get`, `MalMangaOperation.get`, `MyAnimeListAnimeApi.get`, and `MyAnimeListMangaApi.get`.
  *
  * @see https://myanimelist.net/apiconfig/references/api/v2#tag/anime/operation/anime_anime_id_get
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/manga/operation/manga_manga_id_get
  */
 interface MalPicture {
     /** The large image URL, when MyAnimeList provides one. */
@@ -11761,6 +12161,39 @@ interface MalAnime {
     /** Any additional fields requested by a caller remain available without narrowing. */
     [field: string]: unknown;
 }
+/**
+ * {@link MalManga} is the typed portion of a MyAnimeList manga response returned by `MalMangaOperation.get` and `MyAnimeListMangaApi.get`.
+ *
+ * It always carries `id` and `title`; additional fields appear when requested via {@link MalRequestOptions.fields} and are exposed through the index signature without narrowing. Manga-specific fields such as `num_chapters` and `num_volumes` mirror the MyAnimeList manga endpoint shape.
+ *
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/manga/operation/manga_manga_id_get
+ */
+interface MalManga {
+    /** The MyAnimeList numeric identifier. */
+    id: number;
+    /** The canonical MyAnimeList title. */
+    title: string;
+    /** Optional image variants requested through the `fields` query parameter. */
+    main_picture?: MalPicture;
+    /** The synopsis, when requested via the `fields` query parameter. */
+    synopsis?: string;
+    /** The publication status, when requested (one of MAL's status values such as `finished`). */
+    status?: string;
+    /** The average score out of 10, when requested via the `fields` query parameter. */
+    mean?: number;
+    /** The total number of chapters, when requested via the `fields` query parameter. */
+    num_chapters?: number;
+    /** The total number of volumes, when requested via the `fields` query parameter. */
+    num_volumes?: number;
+    /** The media type, when requested (for example `manga`, `novel`, or `oneshot`). */
+    media_type?: string;
+    /** The first publication date in ISO 8601 format, when requested via the `fields` query parameter. */
+    start_date?: string;
+    /** The end publication date in ISO 8601 format, when requested via the `fields` query parameter. */
+    end_date?: string;
+    /** Any additional fields requested by a caller remain available without narrowing. */
+    [field: string]: unknown;
+}
 /**
  * {@link MalUser} is the typed portion of the authenticated MyAnimeList user response returned by `MalUserOperation.me` and `MyAnimeListUserApi.me`.
  *
@@ -11789,22 +12222,179 @@ interface MalUser {
 /**
  * {@link MalRequestOptions} is the public request options shared by MAL endpoint methods.
  *
- * It extends {@link RequestOptions} with the MyAnimeList `fields` selector consumed by `MalAnimeOperation.get` and `MalUserOperation.me` through `MyAnimeListApi`. Transport settings are merged over the instance defaults from `MalCredentials` via `buildMyAnimeListApi`.
+ * It extends {@link RequestOptions} with the MyAnimeList `fields` selector consumed by `MalAnimeOperation.get`, `MalMangaOperation.get`, and `MalUserOperation.me` through `MyAnimeListApi`. Transport settings are merged over the instance defaults from `MalCredentials` via `buildMyAnimeListApi`.
  *
  * @see https://myanimelist.net/apiconfig/references/api/v2#tag/anime/operation/anime_anime_id_get
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/manga/operation/manga_manga_id_get
  * @see https://myanimelist.net/apiconfig/references/api/v2#tag/users/operation/users_user_id_get
  */
 interface MalRequestOptions extends RequestOptions {
     /** A comma-separated field selector, or the same selector as an array. */
     fields?: string | readonly string[];
 }
+/**
+ * The watch status of an anime on a user's MyAnimeList list.
+ *
+ * These are the five fixed values MyAnimeList accepts for the `status` field
+ * of {@link MalAnimeListStatusUpdate} and returns on {@link MalAnimeListStatus}.
+ *
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-animelist/operation/anime_anime_id_my_list_status_put
+ */
+type MalAnimeListStatusValue = "watching" | "completed" | "on_hold" | "dropped" | "plan_to_watch";
+/**
+ * {@link MalAnimeListStatusUpdate} is the form-urlencoded PATCH request body for updating a user's anime list status.
+ *
+ * Every field is optional: callers send only the fields they want to change. It is consumed by `MalAnimeOperation.updateMyListStatus` and `MyAnimeListAnimeApi.updateMyListStatus` against `PATCH /anime/{anime_id}/my_list_status`, which encodes it as `application/x-www-form-urlencoded` (MAL rejects JSON on this endpoint).
+ *
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-animelist/operation/anime_anime_id_my_list_status_put
+ */
+interface MalAnimeListStatusUpdate {
+    /** The watch status to set; one of {@link MalAnimeListStatusValue}. */
+    status?: MalAnimeListStatusValue;
+    /** The number of episodes the user has watched. */
+    num_watched_episodes?: number;
+    /** The user's score out of 10. */
+    score?: number;
+    /** The date the user started watching, in ISO 8601 form; MAL also accepts partial dates (`YYYY-MM` or `YYYY`). */
+    start_date?: string;
+    /** The date the user finished watching, in ISO 8601 form; MAL also accepts partial dates (`YYYY-MM` or `YYYY`). */
+    finish_date?: string;
+    /** Free-form notes the user attached to the entry. */
+    comments?: string;
+    /** Whether the user is currently rewatching the anime. */
+    is_rewatching?: boolean;
+    /** The number of times the user has rewatched the anime. */
+    num_times_rewatched?: number;
+    /** The rewatch value rating (0-5). */
+    rewatch_value?: number;
+    /** The priority rating (0-2). */
+    priority?: number;
+    /** User-defined tags attached to the entry; sent as a comma-separated string. */
+    tags?: readonly string[];
+}
+/**
+ * {@link MalAnimeListStatus} is the response returned by MyAnimeList for a user's anime list status.
+ *
+ * It is the shape returned by `MalAnimeOperation.updateMyListStatus` and `MyAnimeListAnimeApi.updateMyListStatus` from `PATCH /anime/{anime_id}/my_list_status`. MyAnimeList returns `tags` as a single comma-separated string and reports the episode count as `num_episodes_watched` (the request field is `num_watched_episodes` — a documented MAL asymmetry); the server-managed `updated_at` timestamp is included when set.
+ *
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-animelist/operation/anime_anime_id_my_list_status_put
+ */
+interface MalAnimeListStatus {
+    /** The current watch status; one of {@link MalAnimeListStatusValue}. */
+    status: MalAnimeListStatusValue;
+    /** The number of episodes the user has watched; MAL reports this as `num_episodes_watched`. */
+    num_episodes_watched: number;
+    /** The user's score out of 10. */
+    score: number;
+    /** The date the user started watching, in ISO 8601 form; may be a partial date (`YYYY-MM` or `YYYY`). */
+    start_date?: string;
+    /** The date the user finished watching, in ISO 8601 form; may be a partial date (`YYYY-MM` or `YYYY`). */
+    finish_date?: string;
+    /** Free-form notes the user attached to the entry. */
+    comments?: string;
+    /** Whether the user is currently rewatching the anime. */
+    is_rewatching: boolean;
+    /** The number of times the user has rewatched the anime. */
+    num_times_rewatched: number;
+    /** The rewatch value rating (0-5). */
+    rewatch_value: number;
+    /** The priority rating (0-2). */
+    priority: number;
+    /** User-defined tags attached to the entry, as a single comma-separated string. */
+    tags: string;
+    /** The server-managed timestamp of the last update, in ISO 8601 form. */
+    updated_at?: string;
+    /** Any additional fields returned by MyAnimeList remain available without narrowing. */
+    [field: string]: unknown;
+}
+/**
+ * The reading status of a manga on a user's MyAnimeList list.
+ *
+ * These are the five fixed values MyAnimeList accepts for the `status` field
+ * of {@link MalMangaListStatusUpdate} and returns on {@link MalMangaListStatus}.
+ *
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-mangalist/operation/manga_manga_id_my_list_status_put
+ */
+type MalMangaListStatusValue = "reading" | "completed" | "on_hold" | "dropped" | "plan_to_read";
+/**
+ * {@link MalMangaListStatusUpdate} is the form-urlencoded PATCH request body for updating a user's manga list status.
+ *
+ * Every field is optional: callers send only the fields they want to change. It is consumed by `MalMangaOperation.updateMyListStatus` and `MyAnimeListMangaApi.updateMyListStatus` against `PATCH /manga/{manga_id}/my_list_status`, which encodes it as `application/x-www-form-urlencoded` (MAL rejects JSON on this endpoint).
+ *
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-mangalist/operation/manga_manga_id_my_list_status_put
+ */
+interface MalMangaListStatusUpdate {
+    /** The reading status to set; one of {@link MalMangaListStatusValue}. */
+    status?: MalMangaListStatusValue;
+    /** The number of chapters the user has read. */
+    num_chapters_read?: number;
+    /** The number of volumes the user has read. */
+    num_volumes_read?: number;
+    /** The user's score out of 10. */
+    score?: number;
+    /** The date the user started reading, in ISO 8601 form; MAL also accepts partial dates (`YYYY-MM` or `YYYY`). */
+    start_date?: string;
+    /** The date the user finished reading, in ISO 8601 form; MAL also accepts partial dates (`YYYY-MM` or `YYYY`). */
+    finish_date?: string;
+    /** Free-form notes the user attached to the entry. */
+    comments?: string;
+    /** Whether the user is currently rereading the manga. */
+    is_rereading?: boolean;
+    /** The number of times the user has reread the manga. */
+    num_times_reread?: number;
+    /** The reread value rating (0-5). */
+    reread_value?: number;
+    /** The priority rating (0-2). */
+    priority?: number;
+    /** User-defined tags attached to the entry; sent as a comma-separated string. */
+    tags?: readonly string[];
+}
+/**
+ * {@link MalMangaListStatus} is the response returned by MyAnimeList for a user's manga list status.
+ *
+ * It is the shape returned by `MalMangaOperation.updateMyListStatus` and `MyAnimeListMangaApi.updateMyListStatus` from `PATCH /manga/{manga_id}/my_list_status`. MyAnimeList returns `tags` as a single comma-separated string and reports the chapter count as `num_chapters_read`; the server-managed `updated_at` timestamp is included when set.
+ *
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-mangalist/operation/manga_manga_id_my_list_status_put
+ */
+interface MalMangaListStatus {
+    /** The current reading status; one of {@link MalMangaListStatusValue}. */
+    status: MalMangaListStatusValue;
+    /** The number of chapters the user has read. */
+    num_chapters_read: number;
+    /** The number of volumes the user has read. */
+    num_volumes_read: number;
+    /** The user's score out of 10. */
+    score: number;
+    /** The date the user started reading, in ISO 8601 form; may be a partial date (`YYYY-MM` or `YYYY`). */
+    start_date?: string;
+    /** The date the user finished reading, in ISO 8601 form; may be a partial date (`YYYY-MM` or `YYYY`). */
+    finish_date?: string;
+    /** Free-form notes the user attached to the entry. */
+    comments?: string;
+    /** Whether the user is currently rereading the manga. */
+    is_rereading: boolean;
+    /** The number of times the user has reread the manga. */
+    num_times_reread: number;
+    /** The reread value rating (0-5). */
+    reread_value: number;
+    /** The priority rating (0-2). */
+    priority: number;
+    /** User-defined tags attached to the entry, as a single comma-separated string. */
+    tags: string;
+    /** The server-managed timestamp of the last update, in ISO 8601 form. */
+    updated_at?: string;
+    /** Any additional fields returned by MyAnimeList remain available without narrowing. */
+    [field: string]: unknown;
+}
 
 /**
  * {@link MyAnimeListAnimeApi} is the anime group exposed by {@link MyAnimeListApi} under `aniLink.mal.anime`.
  *
- * It is the facade boundary for MyAnimeList anime reads; the single `MalAnimeOperation.get | get` method delegates to `MalAnimeOperation` and returns a {@link MalAnime} shaped by {@link MalRequestOptions.fields}.
+ * It is the facade boundary for MyAnimeList anime reads and list-status writes; the `MalAnimeOperation.get | get` method delegates to `MalAnimeOperation` and returns a {@link MalAnime} shaped by {@link MalRequestOptions.fields}, while `updateMyListStatus` and `deleteFromList` cover the authenticated `PATCH` and `DELETE /anime/{id}/my_list_status` endpoints.
  *
  * @see https://myanimelist.net/apiconfig/references/api/v2#tag/anime/operation/anime_anime_id_get
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-animelist/operation/anime_anime_id_my_list_status_put
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-animelist/operation/anime_anime_id_my_list_status_delete
  */
 interface MyAnimeListAnimeApi {
     /**
@@ -11825,6 +12415,121 @@ interface MyAnimeListAnimeApi {
      * @see https://myanimelist.net/apiconfig/references/api/v2#tag/anime/operation/anime_anime_id_get
      */
     get: (id: number, options?: MalRequestOptions) => Promise<MalAnime>;
+    /**
+     * {@link MyAnimeListAnimeApi.updateMyListStatus} updates the authenticated user's anime list status through `MalAnimeOperation.updateMyListStatus`.
+     *
+     * It is the public facade for `PATCH /anime/{id}/my_list_status` and requires a MAL access token from `MalCredentials.accessToken` via `buildMyAnimeListApi`; send only the {@link MalAnimeListStatusUpdate} fields you want to change, form-encoded as MAL requires.
+     *
+     * @param id - The MyAnimeList anime ID.
+     * @param payload - The list-status fields to update; a {@link MalAnimeListStatusUpdate} of only the fields to change.
+     * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
+     * @returns The updated {@link MalAnimeListStatus}.
+     * @throws `AniLinkAuthError` when no MAL access token is configured.
+     * @throws `AniLinkRestError` for a non-success MyAnimeList response.
+     * @throws `AniLinkNetworkError` for timeout, cancellation, or other transport failures.
+     * @example
+     * ```typescript
+     * const api = new AniLink({ mal: { accessToken: "mal-token" } }).mal;
+     * const status = await api.anime.updateMyListStatus(21, {
+     *   status: "watching",
+     *   num_watched_episodes: 10,
+     *   score: 9,
+     * });
+     * ```
+     * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-animelist/operation/anime_anime_id_my_list_status_put
+     */
+    updateMyListStatus: (id: number, payload: MalAnimeListStatusUpdate, options?: MalRequestOptions) => Promise<MalAnimeListStatus>;
+    /**
+     * {@link MyAnimeListAnimeApi.deleteFromList} removes an anime from the authenticated user's list through `MalAnimeOperation.deleteFromList`.
+     *
+     * It is the public facade for `DELETE /anime/{id}/my_list_status` and requires a MAL access token from `MalCredentials.accessToken` via `buildMyAnimeListApi`.
+     *
+     * @param id - The MyAnimeList anime ID.
+     * @param options - Optional transport settings; a {@link MalRequestOptions} merged over the instance defaults.
+     * @returns Resolves once the entry is deleted; the response carries no body.
+     * @throws `AniLinkAuthError` when no MAL access token is configured.
+     * @throws `AniLinkRestError` for a non-success MyAnimeList response.
+     * @throws `AniLinkNetworkError` for timeout, cancellation, or other transport failures.
+     * @example
+     * ```typescript
+     * const api = new AniLink({ mal: { accessToken: "mal-token" } }).mal;
+     * await api.anime.deleteFromList(21);
+     * ```
+     * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-animelist/operation/anime_anime_id_my_list_status_delete
+     */
+    deleteFromList: (id: number, options?: MalRequestOptions) => Promise<void>;
+}
+/**
+ * {@link MyAnimeListMangaApi} is the manga group exposed by {@link MyAnimeListApi} under `aniLink.mal.manga`.
+ *
+ * It is the facade boundary for MyAnimeList manga reads and list-status writes; the {@link MalMangaOperation.get | get} method delegates to `MalMangaOperation` and returns a {@link MalManga} shaped by {@link MalRequestOptions.fields}, while `updateMyListStatus` and `deleteFromList` cover the authenticated `PATCH` and `DELETE /manga/{id}/my_list_status` endpoints.
+ *
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/manga/operation/manga_manga_id_get
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-mangalist/operation/manga_manga_id_my_list_status_put
+ * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-mangalist/operation/manga_manga_id_my_list_status_delete
+ */
+interface MyAnimeListMangaApi {
+    /**
+     * {@link MyAnimeListMangaApi.get} gets one manga by its MyAnimeList ID through `MalMangaOperation.get`.
+     *
+     * It is the public facade for the `GET /manga/{id}` endpoint; use {@link MalRequestOptions.fields} to select the response shape and {@link MalRequestOptions} transport settings to override per call.
+     *
+     * @param id - The MyAnimeList manga ID.
+     * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
+     * @returns The requested {@link MalManga}.
+     * @throws `AniLinkRestError` for a non-success MyAnimeList response.
+     * @throws `AniLinkNetworkError` for timeout, cancellation, or other transport failures.
+     * @example
+     * ```typescript
+     * const api = new AniLink({ mal: { accessToken: "mal-token" } }).mal;
+     * const manga = await api.manga.get(1, { fields: ["id", "title", "main_picture"] });
+     * ```
+     * @see https://myanimelist.net/apiconfig/references/api/v2#tag/manga/operation/manga_manga_id_get
+     */
+    get: (id: number, options?: MalRequestOptions) => Promise<MalManga>;
+    /**
+     * {@link MyAnimeListMangaApi.updateMyListStatus} updates the authenticated user's manga list status through `MalMangaOperation.updateMyListStatus`.
+     *
+     * It is the public facade for `PATCH /manga/{id}/my_list_status` and requires a MAL access token from `MalCredentials.accessToken` via `buildMyAnimeListApi`; send only the {@link MalMangaListStatusUpdate} fields you want to change, form-encoded as MAL requires.
+     *
+     * @param id - The MyAnimeList manga ID.
+     * @param payload - The list-status fields to update; a {@link MalMangaListStatusUpdate} of only the fields to change.
+     * @param options - Optional field selection and transport settings; a {@link MalRequestOptions} merged over the instance defaults.
+     * @returns The updated {@link MalMangaListStatus}.
+     * @throws `AniLinkAuthError` when no MAL access token is configured.
+     * @throws `AniLinkRestError` for a non-success MyAnimeList response.
+     * @throws `AniLinkNetworkError` for timeout, cancellation, or other transport failures.
+     * @example
+     * ```typescript
+     * const api = new AniLink({ mal: { accessToken: "mal-token" } }).mal;
+     * const status = await api.manga.updateMyListStatus(1, {
+     *   status: "reading",
+     *   num_chapters_read: 10,
+     *   score: 9,
+     * });
+     * ```
+     * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-mangalist/operation/manga_manga_id_my_list_status_put
+     */
+    updateMyListStatus: (id: number, payload: MalMangaListStatusUpdate, options?: MalRequestOptions) => Promise<MalMangaListStatus>;
+    /**
+     * {@link MyAnimeListMangaApi.deleteFromList} removes a manga from the authenticated user's list through `MalMangaOperation.deleteFromList`.
+     *
+     * It is the public facade for `DELETE /manga/{id}/my_list_status` and requires a MAL access token from `MalCredentials.accessToken` via `buildMyAnimeListApi`.
+     *
+     * @param id - The MyAnimeList manga ID.
+     * @param options - Optional transport settings; a {@link MalRequestOptions} merged over the instance defaults.
+     * @returns Resolves once the entry is deleted; the response carries no body.
+     * @throws `AniLinkAuthError` when no MAL access token is configured.
+     * @throws `AniLinkRestError` for a non-success MyAnimeList response.
+     * @throws `AniLinkNetworkError` for timeout, cancellation, or other transport failures.
+     * @example
+     * ```typescript
+     * const api = new AniLink({ mal: { accessToken: "mal-token" } }).mal;
+     * await api.manga.deleteFromList(1);
+     * ```
+     * @see https://myanimelist.net/apiconfig/references/api/v2#tag/user-mangalist/operation/manga_manga_id_my_list_status_delete
+     */
+    deleteFromList: (id: number, options?: MalRequestOptions) => Promise<void>;
 }
 /**
  * {@link MyAnimeListUserApi} is the user group exposed by {@link MyAnimeListApi} under `aniLink.mal.user`.
@@ -11856,26 +12561,19 @@ interface MyAnimeListUserApi {
 /**
  * {@link MyAnimeListApi} is the typed MyAnimeList REST surface exposed by `aniLink.mal`.
  *
- * It composes {@link MyAnimeListAnimeApi} and {@link MyAnimeListUserApi} from `MalAnimeOperation` and `MalUserOperation` via `buildMyAnimeListApi`. Every method accepts {@link MalRequestOptions} and returns {@link MalAnime} or {@link MalUser}; OAuth helpers `buildMalAuthorizationUrl`, `getMalAccessToken`, and `refreshMalAccessToken` supply the token for `MalCredentials`.
+ * It composes {@link MyAnimeListAnimeApi}, {@link MyAnimeListMangaApi}, and {@link MyAnimeListUserApi} from `MalAnimeOperation`, `MalMangaOperation`, and `MalUserOperation` via `buildMyAnimeListApi`. Read methods accept {@link MalRequestOptions} and return {@link MalAnime}, {@link MalManga}, or {@link MalUser}; the anime and manga groups additionally expose `updateMyListStatus` and `deleteFromList` for the authenticated list-status write/delete endpoints. OAuth helpers `buildMalAuthorizationUrl`, `getMalAccessToken`, and `refreshMalAccessToken` supply the token for `MalCredentials`.
  *
  * @see https://myanimelist.net/apiconfig/references/api/v2
  */
 interface MyAnimeListApi {
     /** Anime operations via {@link MyAnimeListAnimeApi} and `MalAnimeOperation`. */
     anime: MyAnimeListAnimeApi;
+    /** Manga operations via {@link MyAnimeListMangaApi} and `MalMangaOperation`. */
+    manga: MyAnimeListMangaApi;
     /** User operations via {@link MyAnimeListUserApi} and `MalUserOperation`. */
     user: MyAnimeListUserApi;
 }
 
-/**
- * Per-provider credential shapes accepted by the {@link AniLink} constructor.
- *
- * Every provider owns its own credentials: AniList authenticates with a
- * bearer token, while REST providers such as MyAnimeList carry their own
- * access-token and PKCE fields. All shapes extend {@link ProviderCredentials}
- * so transport settings stay uniform across providers.
- */
-
 /**
  * Transport settings shared by every provider's slot in an
  * {@link AniLinkCredentials} object. Provider-specific credential types
@@ -11923,7 +12621,10 @@ interface MalCredentials extends ProviderCredentials {
  *
  * Each key targets exactly one provider namespace (`aniLink.anilist`,
  * `aniLink.mal`, …); credentials given under one key are never applied to
- * another provider's requests.
+ * another provider's requests. The optional top-level `onHookError` is a
+ * client-level default applied to every provider slot that does not define
+ * its own, so a single hook-error logger can be wired once instead of
+ * repeated per slot.
  *
  * @see {@link ProviderCredentials}
  */
@@ -11932,6 +12633,14 @@ interface AniLinkCredentials {
     anilist?: AniListCredentials;
     /** Credentials for the MyAnimeList provider surface. */
     mal?: MalCredentials;
+    /**
+     * Client-level default for the `onHookError` lifecycle hook, applied to
+     * every provider slot that does not define its own `onHookError`. Lets
+     * consumers route hook failures to a real logger once per client instead
+     * of repeating the wiring on every call or accepting uncorrelated
+     * `console.warn` noise.
+     */
+    onHookError?: OnHookErrorHandler;
 }
 /**
  * Normalized authentication and transport settings for one provider slot.
@@ -12262,7 +12971,7 @@ declare const getMalTokenExpiry: (response: MalTokenResponse, now?: number) => D
 /**
  * {@link buildMyAnimeListApi} is the wiring helper that builds the {@link MyAnimeListApi} from provider-owned {@link MalCredentials}.
  *
- * It resolves credentials through {@link resolveMalCredentials} and composes {@link MalAnimeOperation} and {@link MalUserOperation} into the {@link MyAnimeListApi} facade exposed as `aniLink.mal`. Transport settings from {@link MalCredentials} flow to `MalRequestOptions` without leaking between providers.
+ * It resolves credentials through {@link resolveMalCredentials} and composes {@link MalAnimeOperation}, {@link MalMangaOperation}, and {@link MalUserOperation} into the {@link MyAnimeListApi} facade exposed as `aniLink.mal`. Transport settings from {@link MalCredentials} flow to `MalRequestOptions` without leaking between providers.
  *
  * @param credentials - MAL access and OAuth credentials plus transport settings; a {@link MalCredentials} slot.
  * @returns The composed {@link MyAnimeListApi} surface.
@@ -12325,5 +13034,5 @@ declare class AniLink {
     constructor(authToken?: string | AniLinkCredentials, options?: AniLinkOptions);
 }
 
-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 };
-export type { AniLinkCredentials, AniLinkErrorCode, AniLinkOptions, AniListApi, AniListCredentials, AniListTokenResponse, ChunkPaginateOptions, ChunkPaginateResult, MalAnime as M, MalAuthorizationCodeRequest, MalCredentials, MalRefreshTokenRequest, MalTokenResponse, MyAnimeListApi, PaginateOptions, PaginateResult, ProviderClients, ProviderCredentials, ProviderFactory, ProviderId, RequestOptions as R, RateLimitInfo, RequestAuth, RequestAuthInput, ResolvedProviderCredentials, MalPicture as a, MalRequestOptions as b, MalUser as c, MyAnimeListAnimeApi as d, MyAnimeListUserApi as e };
+export { ANILIST_AUTHORIZE_URL, ANILIST_TOKEN_URL, AniLink, AniLinkApiError, AniLinkAuthError, AniLinkError, AniLinkErrorCodes, AniLinkGraphQLError, AniLinkNetworkError, AniLinkRestError, AniLinkValidationError, MAL_API_BASE_URL, MAL_API_REFERENCE, MAL_AUTHORIZE_URL, MAL_TOKEN_URL, ResponseCache, buildAuthorizationUrl, buildMalAuthorizationUrl, buildMyAnimeListApi, buildProviderClients, destroyCachedAgents, getAccessToken, getMalAccessToken, getMalTokenExpiry, getTokenExpiry, paginate, paginateChunks, paginatePages, refreshAccessToken, refreshMalAccessToken };
+export type { AniLinkCredentials, AniLinkErrorCode, AniLinkOptions, AniListApi, AniListCredentials, AniListTokenResponse, ChunkPaginateOptions, ChunkPaginateResult, CircuitOpenContext, MalAnime as M, MalAuthorizationCodeRequest, MalCredentials, MalRefreshTokenRequest, MalTokenResponse, MyAnimeListApi, OnCircuitCloseHandler, OnCircuitOpenHandler, OnHookErrorHandler, OnPaceHandler, OnResponseHandler, PaginateOptions, PaginateResult, ProviderClients, ProviderCredentials, ProviderFactory, ProviderId, RateLimitInfo, RequestAuth, RequestAuthInput, RequestContext, RequestErrorContext, RequestOptions, ResolvedProviderCredentials, ResponseCacheOptions, MalAnimeListStatus as a, MalAnimeListStatusUpdate as b, MalAnimeListStatusValue as c, MalManga as d, MalMangaListStatus as e, MalMangaListStatusUpdate as f, MalMangaListStatusValue as g, MalPicture as h, MalRequestOptions as i, MalUser as j, MyAnimeListAnimeApi as k, MyAnimeListMangaApi as l, MyAnimeListUserApi as m };