@lorenzopant/tmdb 1.19.0 → 1.20.1

package/dist/index.d.mts

@@ -522,6 +522,43 @@ declare class TMDBError extends Error {
   constructor(message: string, http_status: number, tmdb_status_code?: number);
 }
 //#endregion
+//#region src/utils/cache.d.ts
+type CacheOptions = {
+  /**
+   * How long (in milliseconds) each cached entry remains valid.
+   * @default 300_000 (5 minutes)
+   */
+  ttl?: number;
+  /**
+   * Maximum number of entries to hold in memory.
+   * When the store is full the oldest entry is evicted before a new one is inserted.
+   * Defaults to unlimited.
+   */
+  max_size?: number;
+  /**
+   * Endpoints that should never be cached.
+   *
+   * Each pattern is matched against the full cache key (`endpoint?param=value&…`).
+   * - A `string` is matched with `key.startsWith(pattern)`.
+   * - A `RegExp` is tested with `pattern.test(key)`.
+   *
+   * `RegExp` patterns with the global (`g`) or sticky (`y`) flag are automatically
+   * normalized by stripping those flags. Stateful `lastIndex` mutations would otherwise
+   * cause flaky cache behaviour across repeated calls.
+   *
+   * @example
+   * ```ts
+   * // Never cache trending or any discover endpoint
+   * const tmdb = new TMDB(token, {
+   *   cache: {
+   *     excluded_endpoints: ["/trending", /\/discover\//],
+   *   },
+   * });
+   * ```
+   */
+  excluded_endpoints?: (string | RegExp)[];
+};
+//#endregion
 //#region src/utils/logger.d.ts
 type TMDBLoggerEntry = {
   type: "request" | "response" | "error";
@@ -542,6 +579,20 @@ declare class TMDBLogger {
   private static defaultLogger;
 }
 //#endregion
+//#region src/utils/rate-limiter.d.ts
+type RateLimitOptions = {
+  /**
+   * Maximum number of requests allowed within the window.
+   * @default 40
+   */
+  max_requests?: number;
+  /**
+   * Window size in milliseconds.
+   * @default 1_000
+   */
+  per_ms?: number;
+};
+//#endregion
 //#region src/types/config/timezones.d.ts
 type Timezone = TimezoneTuple[number];
 type TimezoneTuple = (typeof TIMEZONE_DATA)[number]["zones"];
@@ -1439,6 +1490,49 @@ type TMDBOptions = {
       onError?: ResponseErrorInterceptor;
     };
   };
+  /**
+   * When enabled, outgoing requests are queued to stay within TMDB's API rate limits.
+   *
+   * - `true` — uses the default limits (approximately 40 requests per second).
+   * - Pass a {@link RateLimitOptions} object to customize `max_requests` and/or `per_ms`.
+   *
+   * Requests that exceed the budget are held in a FIFO queue and dispatched as
+   * slots become available. This is especially useful for bulk data-fetching scripts.
+   *
+   * @default false (disabled)
+   *
+   * @example
+   * ```ts
+   * // Enable with defaults (~40 req / s)
+   * const tmdb = new TMDB(token, { rate_limit: true });
+   *
+   * // Custom budget
+   * const tmdb = new TMDB(token, { rate_limit: { max_requests: 30, per_ms: 1_000 } });
+   * ```
+   */
+  rate_limit?: boolean | RateLimitOptions;
+  /**
+   * Enables in-memory TTL-based caching for GET requests.
+   *
+   * - `true` — uses the default TTL of 5 minutes with no size limit.
+   * - Pass a {@link CacheOptions} object to customize `ttl` and/or `max_size`.
+   *
+   * Cached responses are served immediately without hitting the network.
+   * Entries expire lazily on access once the TTL has elapsed.
+   * Only `GET` requests are cached; mutations are never cached.
+   *
+   * @default false (disabled)
+   *
+   * @example
+   * ```ts
+   * // Enable with defaults (5-minute TTL)
+   * const tmdb = new TMDB(token, { cache: true });
+   *
+   * // Custom TTL and bounded size
+   * const tmdb = new TMDB(token, { cache: { ttl: 60_000, max_size: 500 } });
+   * ```
+   */
+  cache?: boolean | CacheOptions;
 };
 //#endregion
 //#region src/types/common/certifications.d.ts
@@ -3400,6 +3494,237 @@ type V4AuthDeleteAccessTokenResponse = {
   status_message: string;
 };
 //#endregion
+//#region src/types/v4/lists.d.ts
+/** A media type used in v4 list items. */
+type V4ListMediaType = "movie" | "tv";
+/**
+ * A single item reference used when adding, updating, or removing items from a v4 list.
+ */
+type V4ListItemInput = {
+  /** The TMDB media type. */media_type: V4ListMediaType; /** The TMDB media ID. */
+  media_id: number; /** Optional per-item comment. */
+  comment?: string;
+};
+/** Standard status/success response returned by mutating v4 list endpoints. */
+type V4ListStatusResponse = {
+  /** Always `true` on success. */success: boolean; /** TMDB internal status code. */
+  status_code: number; /** Human-readable status message. */
+  status_message: string;
+};
+/** Request body for POST /4/list. */
+type V4CreateListBody = {
+  /** The name of the list. */name: string; /** ISO 639-1 language code (e.g. `"en"`). */
+  iso_639_1: string; /** Optional description for the list. */
+  description?: string; /** Whether the list is public. Defaults to `true`. */
+  public?: boolean;
+};
+/**
+ * Response from POST /4/list.
+ * Returns the new list's ID alongside a standard status payload.
+ */
+type V4CreateListResponse = V4ListStatusResponse & {
+  /** The TMDB ID of the newly created list. */id: number;
+};
+/** Parameters for GET /4/list/{list_id}. */
+type V4ListDetailsParams = {
+  /** The TMDB list ID. */list_id: number; /** Language for localized fields. Defaults to `en-US`. */
+  language?: Language; /** Page number. Defaults to `1`. */
+  page?: number;
+};
+/**
+ * A single media item returned inside a v4 list's results array.
+ * Fields vary slightly between movie and TV show entries; common fields are listed here.
+ */
+type V4ListResult = {
+  /** Whether the item is adult-only content. */adult: boolean; /** Backdrop image path, or `null` if unavailable. */
+  backdrop_path?: string; /** TMDB ID. */
+  id: number; /** The media type. */
+  media_type: V4ListMediaType; /** Original language. */
+  original_language: string; /** Poster image path, or `null` if unavailable. */
+  poster_path?: string; /** Popularity score. */
+  popularity: number; /** Vote average. */
+  vote_average: number; /** Total vote count. */
+  vote_count: number; /** Movie: original title. */
+  original_title?: string; /** Movie: release date (YYYY-MM-DD). */
+  release_date?: string; /** Movie: title. */
+  title?: string; /** Movie: whether the movie has a video. */
+  video?: boolean; /** TV: original name. */
+  original_name?: string; /** TV: first air date (YYYY-MM-DD). */
+  first_air_date?: string; /** TV: name. */
+  name?: string; /** TV: origin countries. */
+  origin_country?: string[];
+};
+/**
+ * Full list detail response from GET /4/list/{list_id}.
+ * Includes paginated results.
+ */
+type V4ListDetails = {
+  /** The TMDB list ID. */id: number; /** Display name. */
+  name: string; /** Description text. */
+  description: string; /** Username of the list creator. */
+  created_by: string; /** Backdrop image path, or `null`. */
+  backdrop_path?: string; /** Cover poster image path, or `null`. */
+  poster_path?: string; /** Whether the list is publicly visible. */
+  public: boolean; /** ISO 639-1 language code. */
+  iso_639_1: string; /** ISO 3166-1 country code. */
+  iso_3166_1: string; /** Total number of items in the list. */
+  item_count: number; /** Average rating across all rated items. */
+  average_rating: number; /** Total combined runtime of all items (minutes). */
+  runtime: number; /** Active sort_by mode. */
+  sort_by: string; /** Total revenue of items in the list. */
+  revenue: number; /** Per-item comments keyed by `"movie:{id}"` or `"tv:{id}"`. */
+  comments: Record<string, string | null>; /** Internal TMDB object IDs. */
+  object_ids: Record<string, string>; /** Current page of results. */
+  page: number; /** Total number of pages. */
+  total_pages: number; /** Total number of items. */
+  total_results: number; /** Paginated media items. */
+  results: V4ListResult[];
+};
+/** Request body for PUT /4/list/{list_id}. */
+type V4UpdateListBody = {
+  /** The TMDB list ID. */list_id: number; /** New display name. */
+  name?: string; /** New description. */
+  description?: string; /** Change visibility. */
+  public?: boolean; /** Sort field (e.g. `"original_order.asc"`, `"vote_average.desc"`). */
+  sort_by?: string;
+};
+/** Parameters for DELETE /4/list/{list_id}. */
+type V4DeleteListParams = {
+  /** The TMDB list ID. */list_id: number;
+};
+/** Request body for POST /4/list/{list_id}/items. */
+type V4AddListItemsBody = {
+  /** Array of items to add. */items: V4ListItemInput[];
+};
+/** Per-item result within an add/update items response. */
+type V4ListItemResult = {
+  /** Whether this individual item was successfully processed. */success: boolean; /** The media type. */
+  media_type: V4ListMediaType; /** The TMDB media ID. */
+  media_id: number;
+};
+/** Response from POST /4/list/{list_id}/items (add) and PUT /4/list/{list_id}/items (update). */
+type V4AddListItemsResponse = V4ListStatusResponse & {
+  /** Per-item success status. */results: V4ListItemResult[];
+};
+/** Request body for PUT /4/list/{list_id}/items (update comments). */
+type V4UpdateListItemsBody = V4AddListItemsBody;
+/** Response from PUT /4/list/{list_id}/items. */
+type V4UpdateListItemsResponse = V4AddListItemsResponse;
+/** Request body for DELETE /4/list/{list_id}/items. */
+type V4RemoveListItemsBody = {
+  /** Array of items to remove. */items: Pick<V4ListItemInput, "media_type" | "media_id">[];
+};
+/** Parameters for GET /4/list/{list_id}/item_status. */
+type V4ListItemStatusParams = {
+  /** The TMDB list ID. */list_id: number; /** The media type to check. */
+  media_type: V4ListMediaType; /** The TMDB media ID to check. */
+  media_id: number;
+};
+/**
+ * Response from GET /4/list/{list_id}/item_status.
+ */
+type V4ListItemStatusResponse = {
+  /** The TMDB list ID. */id: number; /** The media type. */
+  media_type: V4ListMediaType; /** The TMDB media ID. */
+  media_id: number;
+};
+//#endregion
+//#region src/types/guest_sessions.d.ts
+/** Common query params for paginated guest session rated lists. */
+type GuestSessionRatedParams = {
+  /** The guest session ID. */guest_session_id: string; /** Sort direction for the results. */
+  sort_by?: AccountSortBy;
+} & WithLanguage & WithPage;
+/** Paginated response of rated movies for a guest session. */
+type GuestSessionRatedMoviesResponse = PaginatedResponse<AccountRatedMovieItem>;
+/** Paginated response of rated TV shows for a guest session. */
+type GuestSessionRatedTVResponse = PaginatedResponse<AccountRatedTVItem>;
+/** Paginated response of rated TV episodes for a guest session. */
+type GuestSessionRatedEpisodesResponse = PaginatedResponse<AccountRatedEpisodeItem>;
+//#endregion
+//#region src/types/lists.d.ts
+/** Standard mutation response returned by add_movie, remove_movie, clear, and delete. */
+type ListMutationResponse = {
+  /** TMDB internal status code. */status_code: number; /** Human-readable status message. */
+  status_message: string;
+};
+/** Query params for list mutation endpoints that require a session and a list ID. */
+type ListMutationParams = {
+  /** TMDB list ID. */list_id: number; /** v3 session ID (required). */
+  session_id: string;
+};
+/** A single item inside a TMDB v3 list (movie with media_type). */
+type ListItem = {
+  /** Whether the item is adult content. */adult: boolean; /** Path to the backdrop image, if available. */
+  backdrop_path?: string; /** Array of genre IDs. */
+  genre_ids: number[]; /** Unique TMDB ID of the item. */
+  id: number; /** Media type — always `"movie"` for v3 lists. */
+  media_type: string; /** ISO 639-1 original language code. */
+  original_language: string; /** Original title. */
+  original_title: string; /** Plot overview. */
+  overview: string; /** Popularity score. */
+  popularity: number; /** Path to the poster image, if available. */
+  poster_path?: string; /** Release date (YYYY-MM-DD). */
+  release_date: string; /** Localized title. */
+  title: string; /** Whether the item has a video. */
+  video: boolean; /** Average TMDB vote score. */
+  vote_average: number; /** Total number of TMDB votes. */
+  vote_count: number;
+};
+/** Full details of a TMDB v3 list. */
+type ListDetails = {
+  /** Display name of the list creator. */created_by: string; /** Description of the list. */
+  description: string; /** Number of users who have favorited this list. */
+  favorite_count: number; /** Unique TMDB list ID (returned as a string by the API). */
+  id: string; /** Array of items in the list. */
+  items: ListItem[]; /** Total number of items in the list. */
+  item_count: number; /** ISO 639-1 language the list is written in. */
+  iso_639_1: string; /** Display name of the list. */
+  name: string; /** Path to the list's poster image, if set. */
+  poster_path?: string;
+};
+/** Query params for the list details endpoint. */
+type ListDetailsParams = {
+  /** TMDB list ID. */list_id: number;
+} & WithLanguage & WithPage;
+/** Request body for creating a new list. */
+type ListCreateBody = {
+  /** Display name of the list. */name: string; /** Description of the list. */
+  description: string; /** ISO 639-1 language code for the list. */
+  language: string;
+};
+/** Query params for the create list endpoint. */
+type ListCreateParams = {
+  /** v3 session ID (required). */session_id: string;
+};
+/** Response from creating a new list. */
+type ListCreateResponse = {
+  /** Human-readable status message. */status_message: string; /** Whether the list was created successfully. */
+  success: boolean; /** TMDB internal status code. */
+  status_code: number; /** The ID of the newly created list. */
+  list_id: number;
+};
+/** Request body for add_movie and remove_movie. */
+type ListMovieBody = {
+  /** TMDB movie ID to add or remove. */media_id: number;
+};
+/** Query params for clearing all items from a list. */
+type ListClearParams = {
+  /** TMDB list ID. */list_id: number; /** v3 session ID (required). */
+  session_id: string; /** Must be `true` to confirm the operation. */
+  confirm: boolean;
+};
+/** Query params for the check item status endpoint. */
+type ListItemStatusParams = {
+  /** TMDB list ID. */list_id: number; /** TMDB movie ID to check. */
+  movie_id?: number;
+} & WithLanguage;
+/** Response from the check item status endpoint. */
+type ListItemStatusResponse = {
+  /** The TMDB list ID. */id: number; /** Whether the movie is present in the list. */
+  item_present: boolean;
+};
+//#endregion
 //#region src/client.d.ts
 declare class ApiClient {
   private accessToken;
@@ -3413,15 +3738,19 @@ declare class ApiClient {
    */
   private inflightRequests;
   private deduplication;
+  private rateLimiter?;
   private requestInterceptors;
   private onSuccessInterceptor?;
   private onErrorInterceptor?;
   private imageApi?;
+  private responseCache?;
   constructor(accessToken: string, options?: {
     /** @internal API version to target. Used by TMDBv4 — not exposed in TMDBOptions. */version?: 3 | 4;
     logger?: boolean | TMDBLoggerFn;
     deduplication?: boolean;
     images?: ImagesConfig;
+    rate_limit?: boolean | RateLimitOptions;
+    cache?: boolean | CacheOptions;
     interceptors?: {
       request?: RequestInterceptor | RequestInterceptor[];
       response?: {
@@ -3455,6 +3784,20 @@ declare class ApiClient {
    * `TMDBOptions.deduplication = false`.
    */
   request<T>(endpoint: string, params?: Record<string, unknown | undefined>): Promise<T>;
+  /**
+   * Removes a single entry from the response cache.
+   *
+   * The key is built from `endpoint` + `params` using the same deterministic algorithm
+   * as the cache itself, so the arguments must match exactly what was used in the original
+   * request (including parameter values and casing).
+   *
+   * @returns `true` if an entry was found and removed, `false` if it was not cached.
+   */
+  invalidateCache(endpoint: string, params?: Record<string, unknown>): boolean;
+  /** Removes all entries from the response cache. */
+  clearCache(): void;
+  /** Returns the number of entries currently held in the response cache. */
+  get cacheSize(): number;
   /**
    * Runs all registered request interceptors in order, threading the context through each one.
    * If an interceptor returns a new context, it replaces the current context for the next interceptor.
@@ -3468,18 +3811,26 @@ declare class ApiClient {
   private sanitizeNulls;
   private handleError;
   /**
-   * Makes an authenticated mutation request (POST, PUT, or DELETE) to the TMDB API.
-   * Unlike `request()`, mutations are never deduplicated since they change server state.
+   * Makes an authenticated mutation request to the TMDB API.
+   * Unlike `request()`, mutations are **never deduplicated** since they change server state.
+   *
+   * Accepts `"GET"` in addition to the standard mutation verbs for the rare TMDB endpoints
+   * (e.g. `GET /4/list/{id}/clear`) that are specified as GET but carry side effects and
+   * must therefore not be collapsed by the deduplication layer.
    *
    * @param method - HTTP method to use
    * @param endpoint - API path (e.g. "/account/123/favorite")
-   * @param body - JSON body to send (omit for DELETE requests without a body)
+   * @param body - JSON body to send (omit for DELETE/GET requests without a body)
    * @param params - Optional query string parameters (e.g. session_id)
    */
-  mutate<T>(method: "POST" | "PUT" | "DELETE", endpoint: string, body?: Record<string, unknown>, params?: Record<string, unknown | undefined>): Promise<T>;
+  mutate<T>(method: "GET" | "POST" | "PUT" | "DELETE", endpoint: string, body?: Record<string, unknown>, params?: Record<string, unknown | undefined>): Promise<T>;
   /**
    * Shared fetch + response-parsing pipeline used by both `request` and `mutate`.
    * Handles URL construction, auth, logging, error mapping, and null sanitisation.
+   *
+   * When called from `request()`, interceptors have already been applied and
+   * `endpoint`/`params` are the effective (post-interceptor) values — interceptors
+   * are skipped. When called from `mutate()`, interceptors run here as normal.
    */
   private execute;
 }
@@ -5151,6 +5502,111 @@ declare class AuthenticationAPI extends TMDBAPIBase {
   delete_session(body: AuthDeleteSessionBody): Promise<AuthDeleteSessionResponse>;
 }
 //#endregion
+//#region src/endpoints/guest_sessions.d.ts
+declare class GuestSessionsAPI extends TMDBAPIBase {
+  private guestSessionPath;
+  private guestSessionSubPath;
+  /**
+   * Rated Movies
+   * GET - https://api.themoviedb.org/3/guest_session/{guest_session_id}/rated/movies
+   *
+   * Get the rated movies for a guest session.
+   * @param params Guest session ID, optional language, page, and sort_by.
+   * @reference https://developer.themoviedb.org/reference/guest-session-rated-movies
+   */
+  rated_movies(params: GuestSessionRatedParams): Promise<GuestSessionRatedMoviesResponse>;
+  /**
+   * Rated TV
+   * GET - https://api.themoviedb.org/3/guest_session/{guest_session_id}/rated/tv
+   *
+   * Get the rated TV shows for a guest session.
+   * @param params Guest session ID, optional language, page, and sort_by.
+   * @reference https://developer.themoviedb.org/reference/guest-session-rated-tv
+   */
+  rated_tv(params: GuestSessionRatedParams): Promise<GuestSessionRatedTVResponse>;
+  /**
+   * Rated TV Episodes
+   * GET - https://api.themoviedb.org/3/guest_session/{guest_session_id}/rated/tv/episodes
+   *
+   * Get the rated TV episodes for a guest session.
+   * @param params Guest session ID, optional language, page, and sort_by.
+   * @reference https://developer.themoviedb.org/reference/guest-session-rated-tv-episodes
+   */
+  rated_tv_episodes(params: GuestSessionRatedParams): Promise<GuestSessionRatedEpisodesResponse>;
+}
+//#endregion
+//#region src/endpoints/lists.d.ts
+declare class ListsAPI extends TMDBAPIBase {
+  private listPath;
+  private listSubPath;
+  /**
+   * Details
+   * GET - https://api.themoviedb.org/3/list/{list_id}
+   *
+   * Get the details of a list.
+   * @param params List ID and optional language and page.
+   * @reference https://developer.themoviedb.org/reference/list-details
+   */
+  details(params: ListDetailsParams): Promise<ListDetails>;
+  /**
+   * Create
+   * POST - https://api.themoviedb.org/3/list
+   *
+   * Create a new list.
+   * @param params session_id query param (required).
+   * @param body name, description, and language for the new list.
+   * @reference https://developer.themoviedb.org/reference/list-create
+   */
+  create(params: ListCreateParams, body: ListCreateBody): Promise<ListCreateResponse>;
+  /**
+   * Delete
+   * DELETE - https://api.themoviedb.org/3/list/{list_id}
+   *
+   * Delete a list.
+   * @param params List ID and session_id (required).
+   * @reference https://developer.themoviedb.org/reference/list-delete
+   */
+  delete(params: ListMutationParams): Promise<ListMutationResponse>;
+  /**
+   * Add Movie
+   * POST - https://api.themoviedb.org/3/list/{list_id}/add_item
+   *
+   * Add a movie to a list.
+   * @param params List ID and session_id (required).
+   * @param body media_id of the movie to add.
+   * @reference https://developer.themoviedb.org/reference/list-add-movie
+   */
+  add_movie(params: ListMutationParams, body: ListMovieBody): Promise<ListMutationResponse>;
+  /**
+   * Remove Movie
+   * POST - https://api.themoviedb.org/3/list/{list_id}/remove_item
+   *
+   * Remove a movie from a list.
+   * @param params List ID and session_id (required).
+   * @param body media_id of the movie to remove.
+   * @reference https://developer.themoviedb.org/reference/list-remove-movie
+   */
+  remove_movie(params: ListMutationParams, body: ListMovieBody): Promise<ListMutationResponse>;
+  /**
+   * Check Item Status
+   * GET - https://api.themoviedb.org/3/list/{list_id}/item_status
+   *
+   * Check if a movie has already been added to a list.
+   * @param params List ID and optional movie_id and language.
+   * @reference https://developer.themoviedb.org/reference/list-check-item-status
+   */
+  check_item_status(params: ListItemStatusParams): Promise<ListItemStatusResponse>;
+  /**
+   * Clear
+   * POST - https://api.themoviedb.org/3/list/{list_id}/clear
+   *
+   * Clear all items from a list. Pass `confirm: true` to confirm the operation.
+   * @param params List ID, session_id, and confirm flag (required).
+   * @reference https://developer.themoviedb.org/reference/list-clear
+   */
+  clear(params: ListClearParams): Promise<ListMutationResponse>;
+}
+//#endregion
 //#region src/endpoints/v4/auth.d.ts
 declare class V4AuthAPI extends TMDBAPIBase {
   /**
@@ -5192,7 +5648,105 @@ declare class V4AuthAPI extends TMDBAPIBase {
 declare class V4AccountAPI extends TMDBAPIBase {}
 //#endregion
 //#region src/endpoints/v4/lists.d.ts
-declare class V4ListsAPI extends TMDBAPIBase {}
+declare class V4ListsAPI extends TMDBAPIBase {
+  private listPath;
+  /**
+   * Create List
+   * POST - https://api.themoviedb.org/4/list
+   *
+   * Create a new v4 list. The authenticated user becomes the owner.
+   * @param body List name and ISO 639-1 language code are required.
+   * @reference https://developer.themoviedb.org/reference/list-create
+   */
+  create(body: V4CreateListBody): Promise<V4CreateListResponse>;
+  /**
+   * List Details
+   * GET - https://api.themoviedb.org/4/list/{list_id}
+   *
+   * Retrieve the details and paginated items of a specific list.
+   * @param params `list_id` is required. Optionally pass `language` and `page`.
+   * @reference https://developer.themoviedb.org/reference/list-details
+   */
+  details({
+    list_id,
+    ...params
+  }: V4ListDetailsParams): Promise<V4ListDetails>;
+  /**
+   * Update List
+   * PUT - https://api.themoviedb.org/4/list/{list_id}
+   *
+   * Update the metadata (name, description, visibility, sort order) of an existing list.
+   * @param body `list_id` plus any fields to change.
+   * @reference https://developer.themoviedb.org/reference/list-update
+   */
+  update({
+    list_id,
+    ...body
+  }: V4UpdateListBody): Promise<V4ListStatusResponse>;
+  /**
+   * Delete List
+   * DELETE - https://api.themoviedb.org/4/list/{list_id}
+   *
+   * Permanently delete a list. This action cannot be undone.
+   * @param params.list_id The TMDB list ID to delete.
+   * @reference https://developer.themoviedb.org/reference/list-delete
+   */
+  delete({
+    list_id
+  }: V4DeleteListParams): Promise<V4ListStatusResponse>;
+  /**
+   * Add Items
+   * POST - https://api.themoviedb.org/4/list/{list_id}/items
+   *
+   * Add one or more movies or TV shows to a list. For each item the response
+   * includes whether it was added successfully.
+   * @param list_id The TMDB list ID.
+   * @param body Array of `{ media_type, media_id }` objects to add.
+   * @reference https://developer.themoviedb.org/reference/list-add-items
+   */
+  add_items(list_id: number, body: V4AddListItemsBody): Promise<V4AddListItemsResponse>;
+  /**
+   * Update Items
+   * PUT - https://api.themoviedb.org/4/list/{list_id}/items
+   *
+   * Update per-item comments for items already in the list.
+   * @param list_id The TMDB list ID.
+   * @param body Array of `{ media_type, media_id, comment }` objects.
+   * @reference https://developer.themoviedb.org/reference/list-update-items
+   */
+  update_items(list_id: number, body: V4UpdateListItemsBody): Promise<V4UpdateListItemsResponse>;
+  /**
+   * Remove Items
+   * DELETE - https://api.themoviedb.org/4/list/{list_id}/items
+   *
+   * Remove one or more items from the list.
+   * @param list_id The TMDB list ID.
+   * @param body Array of `{ media_type, media_id }` objects to remove.
+   * @reference https://developer.themoviedb.org/reference/list-remove-items
+   */
+  remove_items(list_id: number, body: V4RemoveListItemsBody): Promise<V4ListStatusResponse>;
+  /**
+   * Check Item Status
+   * GET - https://api.themoviedb.org/4/list/{list_id}/item_status
+   *
+   * Check whether a specific movie or TV show is already present in the list.
+   * @param params `list_id`, `media_type`, and `media_id` are all required.
+   * @reference https://developer.themoviedb.org/reference/list-item-status
+   */
+  item_status({
+    list_id,
+    ...params
+  }: V4ListItemStatusParams): Promise<V4ListItemStatusResponse>;
+  /**
+   * Clear List
+   * GET - https://api.themoviedb.org/4/list/{list_id}/clear
+   *
+   * Remove all items from the list without deleting the list itself.
+   * @param list_id The TMDB list ID to clear.
+   * @reference https://developer.themoviedb.org/reference/list-clear
+   */
+  clear(list_id: number): Promise<V4ListStatusResponse>;
+}
 //#endregion
 //#region src/tmdb.v4.d.ts
 /**
@@ -5221,11 +5775,8 @@ declare class V4ListsAPI extends TMDBAPIBase {}
  */
 declare class TMDBv4 {
   private client;
-  /** v4 authentication — request token → access token → logout. */
   auth: V4AuthAPI;
-  /** v4 account — details, lists, favorites, watchlist, rated. */
   account: V4AccountAPI;
-  /** v4 lists — full CRUD for user-created lists. */
   lists: V4ListsAPI;
   constructor(accessToken: string, options?: TMDBOptions);
 }
@@ -5262,12 +5813,35 @@ declare class TMDB {
   people: PeopleAPI;
   account: AccountAPI;
   authentication: AuthenticationAPI;
+  guest_sessions: GuestSessionsAPI;
+  lists: ListsAPI;
   /**
    * TMDB API v4 namespaces. Access via `tmdb.v4.auth`, `tmdb.v4.account`, `tmdb.v4.lists`.
    * Requires a Bearer (JWT) access token — throws if the instance was created with an API key.
    */
   get v4(): TMDBv4;
   private _v4;
+  /**
+   * Response cache controls. Only available when `cache` was set in the constructor options.
+   *
+   * - `clear()` — remove all cached entries (e.g. after a user signs out or state resets).
+   * - `invalidate(endpoint, params?)` — remove a single entry by endpoint + params.
+   * - `size` — number of entries currently held in memory.
+   *
+   * @example
+   * ```ts
+   * // Invalidate now_playing after a mutation
+   * tmdb.cache?.invalidate("/movie/now_playing");
+   *
+   * // Clear everything
+   * tmdb.cache?.clear();
+   * ```
+   */
+  get cache(): {
+    clear(): void;
+    invalidate(endpoint: string, params?: Record<string, unknown>): boolean;
+    readonly size: number;
+  } | undefined;
   /**
    * Creates a new TMDB instance.
    * @param accessToken The TMDB API access token.
@@ -5312,4 +5886,4 @@ declare function hasLogoPath(data: unknown): data is {
   logo_path: string;
 };
 //#endregion
-export { AccountAPI, AccountAddFavoriteBody, AccountAddToWatchlistBody, AccountAvatar, AccountDetails, AccountDetailsParams, AccountListItem, AccountListsParams, AccountListsResponse, AccountMediaListParams, AccountMovieItem, AccountMovieListResponse, AccountMutationParams, AccountMutationResponse, AccountRatedEpisodeItem, AccountRatedEpisodesResponse, AccountRatedMovieItem, AccountRatedMoviesResponse, AccountRatedTVItem, AccountRatedTVResponse, AccountSortBy, AccountTVItem, AccountTVListResponse, AlternativeName, AlternativeNamesResult, AlternativeTitle, AuthCreateSessionBody, AuthCreateSessionResponse, AuthCreateSessionWithLoginBody, AuthDeleteSessionBody, AuthDeleteSessionResponse, AuthGuestSessionResponse, AuthRequestTokenResponse, AuthValidateKeyResponse, AuthenticationAPI, BACKDROP_SIZES, BackdropSize, Cast, CertificationItem, Certifications, CertificationsAPI, Change, ChangeItem, ChangeResultItem, Changes, ChangesAPI, Collection, CollectionBaseParam, CollectionDetailsParams, CollectionImages, CollectionImagesParams, CollectionItem, CollectionResultItem, CollectionTranslationData, CollectionTranslations, CollectionsAPI, CompaniesAPI, Company, CompanyAlternativeName, CompanyAlternativeNames, CompanyAlternativeNamesParams, CompanyBaseParam, CompanyDetailsParams, CompanyImages, CompanyImagesParams, CompanyResultItem, CompanySummary, ConfigurationAPI, ConfigurationCountriesParams, ConfigurationCountry, ConfigurationJob, ConfigurationLanguage, ConfigurationResponse, ConfigurationTimezone, ContentRating, CountryISO3166_1, Credit, CreditBaseParam, CreditDetails, CreditDetailsMedia, CreditDetailsMovieMedia, CreditDetailsParams, CreditDetailsPerson, CreditDetailsTVEpisode, CreditDetailsTVMedia, CreditDetailsTVSeason, CreditsAPI, Crew, DateRange, DefaultImageSizesConfig, DiscoverAPI, DiscoverFilterExpression, DiscoverMovieParams, DiscoverMovieSortBy, DiscoverTVParams, DiscoverTVResultItem, DiscoverTVSortBy, DiscoverTVStatus, DiscoverTVType, FileType, FindAPI, FindByIDParams, FindExternalSource, FindMovieResultItem, FindPersonResultItem, FindResults, FindTVEpisodeResultItem, FindTVResultItem, FindTVSeasonResultItem, Genre, GenresAPI, GenresResponse, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, ImageCollectionKey, ImageConfiguration, ImageItem, ImageSize, ImageSizeTypes, ImagesConfig, ImagesResult, Keyword, KeywordBaseParam, KeywordDetailsParams, KeywordMoviesParams, KeywordResultItem, KeywordsAPI, KnownForItem, KnownForMovie, KnownForTV, LOGO_SIZES, Language, LanguageISO6391, LiteralUnion, LogoSize, MediaType, MediaWatchProviders, MovieAlternativeTitles, MovieAlternativeTitlesParams, MovieAppendToResponseNamespace, MovieAppendableMap, MovieChanges, MovieChangesParams, MovieCollection, MovieCredits, MovieCreditsParams, MovieDetails, MovieDetailsParams, MovieDetailsWithAppends, MovieExternalIDs, MovieExternalIDsParams, MovieImages, MovieImagesParams, MovieKeywords, MovieKeywordsParams, MovieListParams, MovieListsAPI, MovieRecommendations, MovieRecommendationsParams, MovieReleaseDate, MovieReleaseDateResult, MovieReleaseDates, MovieReleaseDatesParams, MovieResultItem, MovieReviews, MovieReviewsParams, MovieSimilar, MovieSimilarParams, MovieTranslationData, MovieTranslations, MovieTranslationsParams, MovieVideos, MovieVideosParams, MovieWatchProvidersParams, MoviesAPI, MultiSearchResultItem, Network, NetworkBaseParams, NetworkImages, NetworkItem, NetworksAPI, OrganizationImage, POSTER_SIZES, PROFILE_SIZES, PaginatedResponse, PeopleAPI, PeopleListParams, PeopleListsAPI, PersonAppendToResponseNamespace, PersonAppendableMap, PersonBaseParam, PersonChanges, PersonChangesParams, PersonCombinedCastCredit, PersonCombinedCredits, PersonCombinedCrewCredit, PersonCreditsParams, PersonDetails, PersonDetailsParams, PersonDetailsWithAppends, PersonExternalIDs, PersonExternalIDsParams, PersonImages, PersonImagesParams, PersonMovieCastCredit, PersonMovieCredits, PersonMovieCrewCredit, PersonResultItem, PersonTVCastCredit, PersonTVCredits, PersonTVCrewCredit, PersonTaggedImage, PersonTaggedImageMedia, PersonTaggedImages, PersonTaggedImagesParams, PersonTranslationData, PersonTranslations, PersonTranslationsParams, PosterSize, Prettify, PrimaryTranslations, ProductionCompany, ProductionCountry, ProfileSize, RequestInterceptor, RequestInterceptorContext, ResponseErrorInterceptor, ResponseSuccessInterceptor, Review, ReviewAuthorDetails, ReviewDetails, ReviewDetailsParams, ReviewsAPI, STILL_SIZES, SearchAPI, SearchCollectionsParams, SearchCompanyParams, SearchKeywordsParams, SearchMoviesParams, SearchMultiParams, SearchPersonParams, SearchTVSeriesParams, SpokenLanguage, StillSize, TMDB, TMDBCountries, TMDBError, TMDBLogger, TMDBLoggerEntry, TMDBLoggerFn, TMDBOptions, TMDBQueryParams, TMDBv4, TVAggregateCredits, TVAggregateCreditsCastItem, TVAggregateCreditsCrewItem, TVAggregateCreditsParams, TVAlternativeTitles, TVAppendToResponseNamespace, TVAppendableMap, TVBaseParam, TVChangeParams, TVContentRatings, TVCreditJob, TVCreditRole, TVCredits, TVCreditsParams, TVDetailsParams, TVDetailsWithAppends, TVEpisode, TVEpisodeAppendToResponseNamespace, TVEpisodeAppendableMap, TVEpisodeBaseParams, TVEpisodeCredits, TVEpisodeCreditsParams, TVEpisodeDetailsParams, TVEpisodeDetailsWithAppends, TVEpisodeExternalIDs, TVEpisodeGroupDetails, TVEpisodeGroupDetailsItem, TVEpisodeGroupEpisode, TVEpisodeGroupItem, TVEpisodeGroupParams, TVEpisodeGroupType, TVEpisodeGroups, TVEpisodeGroupsAPI, TVEpisodeId, TVEpisodeImages, TVEpisodeImagesParams, TVEpisodeItem, TVEpisodeTranslationData, TVEpisodeTranslations, TVEpisodeVideos, TVEpisodesAPI, TVExternalIDs, TVImageItem, TVImages, TVImagesParams, TVKeywords, TVRecommendations, TVRecommendationsParams, TVReviews, TVReviewsParams, TVScreenedTheatrically, TVScreeningItem, TVSeason, TVSeasonAggregateCredits, TVSeasonAggregateCreditsParams, TVSeasonAppendToResponseNamespace, TVSeasonAppendableMap, TVSeasonBaseParams, TVSeasonChanges, TVSeasonChangesParams, TVSeasonCredits, TVSeasonCreditsParams, TVSeasonDetailsParams, TVSeasonDetailsWithAppends, TVSeasonEpisode, TVSeasonExternalIDs, TVSeasonId, TVSeasonImages, TVSeasonImagesParams, TVSeasonItem, TVSeasonTranslationData, TVSeasonTranslations, TVSeasonVideos, TVSeasonVideosParams, TVSeasonWatchProvidersParams, TVSeasonsAPI, TVSeriesAPI, TVSeriesChanges, TVSeriesDetails, TVSeriesListItem, TVSeriesListParams, TVSeriesLists, TVSeriesListsAPI, TVSeriesListsParams, TVSeriesResultItem, TVSimilar, TVSimilarParams, TVTranslationData, TVTranslations, TVVideos, Timezone, Translation, TranslationResults, TrendingAPI, TrendingAllResult, TrendingMovieResult, TrendingParams, TrendingPersonResult, TrendingTVResult, TrendingTimeWindow, V4AccountAPI, V4AuthAPI, V4AuthAccessTokenResponse, V4AuthCreateAccessTokenBody, V4AuthCreateRequestTokenBody, V4AuthDeleteAccessTokenBody, V4AuthDeleteAccessTokenResponse, V4AuthRequestTokenResponse, V4ListsAPI, VideoItem, VideoResults, WatchMonetizationType, WatchProvider, WatchProviderDisplayPriorities, WatchProviderItem, WatchProviderListItem, WatchProviderListParams, WatchProviderListResponse, WatchProviderRegionsParams, WatchProviderRegionsResponse, WatchProvidersAPI, WithLanguage, WithLanguagePage, WithPage, WithPageAndDateRange, WithParams, WithRegion, hasBackdropPath, hasLogoPath, hasPosterPath, hasProfilePath, hasStillPath, isJwt, isKnownForMovie, isKnownForTV, isPlainObject, isRecord };
+export { AccountAPI, AccountAddFavoriteBody, AccountAddToWatchlistBody, AccountAvatar, AccountDetails, AccountDetailsParams, AccountListItem, AccountListsParams, AccountListsResponse, AccountMediaListParams, AccountMovieItem, AccountMovieListResponse, AccountMutationParams, AccountMutationResponse, AccountRatedEpisodeItem, AccountRatedEpisodesResponse, AccountRatedMovieItem, AccountRatedMoviesResponse, AccountRatedTVItem, AccountRatedTVResponse, AccountSortBy, AccountTVItem, AccountTVListResponse, AlternativeName, AlternativeNamesResult, AlternativeTitle, AuthCreateSessionBody, AuthCreateSessionResponse, AuthCreateSessionWithLoginBody, AuthDeleteSessionBody, AuthDeleteSessionResponse, AuthGuestSessionResponse, AuthRequestTokenResponse, AuthValidateKeyResponse, AuthenticationAPI, BACKDROP_SIZES, BackdropSize, Cast, CertificationItem, Certifications, CertificationsAPI, Change, ChangeItem, ChangeResultItem, Changes, ChangesAPI, Collection, CollectionBaseParam, CollectionDetailsParams, CollectionImages, CollectionImagesParams, CollectionItem, CollectionResultItem, CollectionTranslationData, CollectionTranslations, CollectionsAPI, CompaniesAPI, Company, CompanyAlternativeName, CompanyAlternativeNames, CompanyAlternativeNamesParams, CompanyBaseParam, CompanyDetailsParams, CompanyImages, CompanyImagesParams, CompanyResultItem, CompanySummary, ConfigurationAPI, ConfigurationCountriesParams, ConfigurationCountry, ConfigurationJob, ConfigurationLanguage, ConfigurationResponse, ConfigurationTimezone, ContentRating, CountryISO3166_1, Credit, CreditBaseParam, CreditDetails, CreditDetailsMedia, CreditDetailsMovieMedia, CreditDetailsParams, CreditDetailsPerson, CreditDetailsTVEpisode, CreditDetailsTVMedia, CreditDetailsTVSeason, CreditsAPI, Crew, DateRange, DefaultImageSizesConfig, DiscoverAPI, DiscoverFilterExpression, DiscoverMovieParams, DiscoverMovieSortBy, DiscoverTVParams, DiscoverTVResultItem, DiscoverTVSortBy, DiscoverTVStatus, DiscoverTVType, FileType, FindAPI, FindByIDParams, FindExternalSource, FindMovieResultItem, FindPersonResultItem, FindResults, FindTVEpisodeResultItem, FindTVResultItem, FindTVSeasonResultItem, Genre, GenresAPI, GenresResponse, GuestSessionRatedEpisodesResponse, GuestSessionRatedMoviesResponse, GuestSessionRatedParams, GuestSessionRatedTVResponse, GuestSessionsAPI, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, ImageCollectionKey, ImageConfiguration, ImageItem, ImageSize, ImageSizeTypes, ImagesConfig, ImagesResult, Keyword, KeywordBaseParam, KeywordDetailsParams, KeywordMoviesParams, KeywordResultItem, KeywordsAPI, KnownForItem, KnownForMovie, KnownForTV, LOGO_SIZES, Language, LanguageISO6391, ListClearParams, ListCreateBody, ListCreateParams, ListCreateResponse, ListDetails, ListDetailsParams, ListItem, ListItemStatusParams, ListItemStatusResponse, ListMovieBody, ListMutationParams, ListMutationResponse, ListsAPI, LiteralUnion, LogoSize, MediaType, MediaWatchProviders, MovieAlternativeTitles, MovieAlternativeTitlesParams, MovieAppendToResponseNamespace, MovieAppendableMap, MovieChanges, MovieChangesParams, MovieCollection, MovieCredits, MovieCreditsParams, MovieDetails, MovieDetailsParams, MovieDetailsWithAppends, MovieExternalIDs, MovieExternalIDsParams, MovieImages, MovieImagesParams, MovieKeywords, MovieKeywordsParams, MovieListParams, MovieListsAPI, MovieRecommendations, MovieRecommendationsParams, MovieReleaseDate, MovieReleaseDateResult, MovieReleaseDates, MovieReleaseDatesParams, MovieResultItem, MovieReviews, MovieReviewsParams, MovieSimilar, MovieSimilarParams, MovieTranslationData, MovieTranslations, MovieTranslationsParams, MovieVideos, MovieVideosParams, MovieWatchProvidersParams, MoviesAPI, MultiSearchResultItem, Network, NetworkBaseParams, NetworkImages, NetworkItem, NetworksAPI, OrganizationImage, POSTER_SIZES, PROFILE_SIZES, PaginatedResponse, PeopleAPI, PeopleListParams, PeopleListsAPI, PersonAppendToResponseNamespace, PersonAppendableMap, PersonBaseParam, PersonChanges, PersonChangesParams, PersonCombinedCastCredit, PersonCombinedCredits, PersonCombinedCrewCredit, PersonCreditsParams, PersonDetails, PersonDetailsParams, PersonDetailsWithAppends, PersonExternalIDs, PersonExternalIDsParams, PersonImages, PersonImagesParams, PersonMovieCastCredit, PersonMovieCredits, PersonMovieCrewCredit, PersonResultItem, PersonTVCastCredit, PersonTVCredits, PersonTVCrewCredit, PersonTaggedImage, PersonTaggedImageMedia, PersonTaggedImages, PersonTaggedImagesParams, PersonTranslationData, PersonTranslations, PersonTranslationsParams, PosterSize, Prettify, PrimaryTranslations, ProductionCompany, ProductionCountry, ProfileSize, RequestInterceptor, RequestInterceptorContext, ResponseErrorInterceptor, ResponseSuccessInterceptor, Review, ReviewAuthorDetails, ReviewDetails, ReviewDetailsParams, ReviewsAPI, STILL_SIZES, SearchAPI, SearchCollectionsParams, SearchCompanyParams, SearchKeywordsParams, SearchMoviesParams, SearchMultiParams, SearchPersonParams, SearchTVSeriesParams, SpokenLanguage, StillSize, TMDB, TMDBCountries, TMDBError, TMDBLogger, TMDBLoggerEntry, TMDBLoggerFn, TMDBOptions, TMDBQueryParams, TMDBv4, TVAggregateCredits, TVAggregateCreditsCastItem, TVAggregateCreditsCrewItem, TVAggregateCreditsParams, TVAlternativeTitles, TVAppendToResponseNamespace, TVAppendableMap, TVBaseParam, TVChangeParams, TVContentRatings, TVCreditJob, TVCreditRole, TVCredits, TVCreditsParams, TVDetailsParams, TVDetailsWithAppends, TVEpisode, TVEpisodeAppendToResponseNamespace, TVEpisodeAppendableMap, TVEpisodeBaseParams, TVEpisodeCredits, TVEpisodeCreditsParams, TVEpisodeDetailsParams, TVEpisodeDetailsWithAppends, TVEpisodeExternalIDs, TVEpisodeGroupDetails, TVEpisodeGroupDetailsItem, TVEpisodeGroupEpisode, TVEpisodeGroupItem, TVEpisodeGroupParams, TVEpisodeGroupType, TVEpisodeGroups, TVEpisodeGroupsAPI, TVEpisodeId, TVEpisodeImages, TVEpisodeImagesParams, TVEpisodeItem, TVEpisodeTranslationData, TVEpisodeTranslations, TVEpisodeVideos, TVEpisodesAPI, TVExternalIDs, TVImageItem, TVImages, TVImagesParams, TVKeywords, TVRecommendations, TVRecommendationsParams, TVReviews, TVReviewsParams, TVScreenedTheatrically, TVScreeningItem, TVSeason, TVSeasonAggregateCredits, TVSeasonAggregateCreditsParams, TVSeasonAppendToResponseNamespace, TVSeasonAppendableMap, TVSeasonBaseParams, TVSeasonChanges, TVSeasonChangesParams, TVSeasonCredits, TVSeasonCreditsParams, TVSeasonDetailsParams, TVSeasonDetailsWithAppends, TVSeasonEpisode, TVSeasonExternalIDs, TVSeasonId, TVSeasonImages, TVSeasonImagesParams, TVSeasonItem, TVSeasonTranslationData, TVSeasonTranslations, TVSeasonVideos, TVSeasonVideosParams, TVSeasonWatchProvidersParams, TVSeasonsAPI, TVSeriesAPI, TVSeriesChanges, TVSeriesDetails, TVSeriesListItem, TVSeriesListParams, TVSeriesLists, TVSeriesListsAPI, TVSeriesListsParams, TVSeriesResultItem, TVSimilar, TVSimilarParams, TVTranslationData, TVTranslations, TVVideos, Timezone, Translation, TranslationResults, TrendingAPI, TrendingAllResult, TrendingMovieResult, TrendingParams, TrendingPersonResult, TrendingTVResult, TrendingTimeWindow, V4AccountAPI, V4AddListItemsBody, V4AddListItemsResponse, V4AuthAPI, V4AuthAccessTokenResponse, V4AuthCreateAccessTokenBody, V4AuthCreateRequestTokenBody, V4AuthDeleteAccessTokenBody, V4AuthDeleteAccessTokenResponse, V4AuthRequestTokenResponse, V4CreateListBody, V4CreateListResponse, V4DeleteListParams, V4ListDetails, V4ListDetailsParams, V4ListItemInput, V4ListItemResult, V4ListItemStatusParams, V4ListItemStatusResponse, V4ListMediaType, V4ListResult, V4ListStatusResponse, V4ListsAPI, V4RemoveListItemsBody, V4UpdateListBody, V4UpdateListItemsBody, V4UpdateListItemsResponse, VideoItem, VideoResults, WatchMonetizationType, WatchProvider, WatchProviderDisplayPriorities, WatchProviderItem, WatchProviderListItem, WatchProviderListParams, WatchProviderListResponse, WatchProviderRegionsParams, WatchProviderRegionsResponse, WatchProvidersAPI, WithLanguage, WithLanguagePage, WithPage, WithPageAndDateRange, WithParams, WithRegion, hasBackdropPath, hasLogoPath, hasPosterPath, hasProfilePath, hasStillPath, isJwt, isKnownForMovie, isKnownForTV, isPlainObject, isRecord };