@lorenzopant/tmdb 1.19.0 → 1.20.0

package/dist/index.d.mts

@@ -542,6 +542,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 +1453,27 @@ 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;
 };
 //#endregion
 //#region src/types/common/certifications.d.ts
@@ -3400,6 +3435,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,6 +3679,7 @@ declare class ApiClient {
    */
   private inflightRequests;
   private deduplication;
+  private rateLimiter?;
   private requestInterceptors;
   private onSuccessInterceptor?;
   private onErrorInterceptor?;
@@ -3422,6 +3689,7 @@ declare class ApiClient {
     logger?: boolean | TMDBLoggerFn;
     deduplication?: boolean;
     images?: ImagesConfig;
+    rate_limit?: boolean | RateLimitOptions;
     interceptors?: {
       request?: RequestInterceptor | RequestInterceptor[];
       response?: {
@@ -3468,15 +3736,19 @@ 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.
@@ -5151,6 +5423,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 +5569,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
 /**
@@ -5262,6 +5737,8 @@ 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.
@@ -5312,4 +5789,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 };

package/dist/index.mjs

@@ -296,6 +296,60 @@ var ImageAPI = class {
 	}
 };
 //#endregion
+//#region src/utils/rate-limiter.ts
+/**
+* A sliding-window rate limiter that queues callers when the request budget is exhausted.
+*
+* Callers `await acquire()` before dispatching a fetch. If the number of requests made
+* within the last `per_ms` milliseconds is below `max_requests`, the caller is released
+* immediately. Otherwise it waits until enough time has passed for older timestamps to
+* leave the window, then proceeds.
+*
+* The internal queue is processed serially by a single `process()` loop so there are no
+* race conditions between concurrent callers.
+*/
+var RateLimiter = class {
+	maxRequests;
+	windowMs;
+	timestamps = [];
+	queue = [];
+	processing = false;
+	constructor(options = {}) {
+		const maxRequests = options.max_requests ?? 40;
+		const perMs = options.per_ms ?? 1e3;
+		if (!Number.isFinite(maxRequests) || !Number.isInteger(maxRequests) || maxRequests < 1) throw new RangeError(`rate_limit.max_requests must be a finite integer >= 1 (got ${maxRequests})`);
+		if (!Number.isFinite(perMs) || !Number.isInteger(perMs) || perMs < 1) throw new RangeError(`rate_limit.per_ms must be a finite integer >= 1 (got ${perMs})`);
+		this.maxRequests = maxRequests;
+		this.windowMs = perMs;
+	}
+	/**
+	* Resolves when a request slot is available within the current window.
+	* Requests that cannot be dispatched immediately are queued in FIFO order.
+	*/
+	acquire() {
+		return new Promise((resolve) => {
+			this.queue.push(resolve);
+			if (!this.processing) this.process();
+		});
+	}
+	async process() {
+		this.processing = true;
+		while (this.queue.length > 0) {
+			const now = Date.now();
+			this.timestamps = this.timestamps.filter((t) => now - t < this.windowMs);
+			if (this.timestamps.length < this.maxRequests) {
+				this.timestamps.push(Date.now());
+				this.queue.shift()();
+			} else {
+				const oldest = this.timestamps[0];
+				const waitMs = this.windowMs - (Date.now() - oldest) + 1;
+				await new Promise((r) => setTimeout(r, waitMs));
+			}
+		}
+		this.processing = false;
+	}
+};
+//#endregion
 //#region src/client.ts
 var ApiClient = class {
 	accessToken;
@@ -309,6 +363,7 @@ var ApiClient = class {
 	*/
 	inflightRequests = /* @__PURE__ */ new Map();
 	deduplication;
+	rateLimiter;
 	requestInterceptors;
 	onSuccessInterceptor;
 	onErrorInterceptor;
@@ -318,6 +373,7 @@ var ApiClient = class {
 		this.baseUrl = `https://api.themoviedb.org/${options.version ?? 3}`;
 		this.logger = TMDBLogger.from(options.logger);
 		this.deduplication = options.deduplication !== false;
+		if (options.rate_limit) this.rateLimiter = new RateLimiter(options.rate_limit === true ? {} : options.rate_limit);
 		const raw = options.interceptors?.request;
 		this.requestInterceptors = raw == null ? [] : Array.isArray(raw) ? raw : [raw];
 		this.onSuccessInterceptor = options.interceptors?.response?.onSuccess;
@@ -419,12 +475,16 @@ var ApiClient = class {
 		throw error;
 	}
 	/**
-	* 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)
 	*/
 	async mutate(method, endpoint, body, params = {}) {
@@ -435,6 +495,7 @@ var ApiClient = class {
 	* Handles URL construction, auth, logging, error mapping, and null sanitisation.
 	*/
 	async execute(method, endpoint, params, body) {
+		const bodyJson = body !== void 0 ? JSON.stringify(body) : void 0;
 		const ctx = await this.runRequestInterceptors({
 			endpoint,
 			params,
@@ -452,6 +513,7 @@ var ApiClient = class {
 			method,
 			endpoint: effectiveEndpoint
 		});
+		if (this.rateLimiter) await this.rateLimiter.acquire();
 		let res;
 		try {
 			res = await fetch(url.toString(), {
@@ -460,7 +522,7 @@ var ApiClient = class {
 					Authorization: `Bearer ${this.accessToken}`,
 					"Content-Type": "application/json;charset=utf-8"
 				} : { "Content-Type": "application/json;charset=utf-8" },
-				...body !== void 0 ? { body: JSON.stringify(body) } : {}
+				...bodyJson !== void 0 ? { body: bodyJson } : {}
 			});
 		} catch (error) {
 			this.logger?.log({
@@ -661,7 +723,20 @@ const ENDPOINTS = {
 		PERSON: "/trending/person"
 	},
 	REVIEWS: { DETAILS: "/review" },
-	PEOPLE_LISTS: { POPULAR: "/person/popular" }
+	PEOPLE_LISTS: { POPULAR: "/person/popular" },
+	LISTS: {
+		DETAILS: "/list",
+		ADD_ITEM: "/add_item",
+		ITEM_STATUS: "/item_status",
+		CLEAR: "/clear",
+		REMOVE_ITEM: "/remove_item"
+	},
+	GUEST_SESSIONS: {
+		DETAILS: "/guest_session",
+		RATED_MOVIES: "/rated/movies",
+		RATED_TV: "/rated/tv",
+		RATED_TV_EPISODES: "/rated/tv/episodes"
+	}
 };
 /**
 * TMDB API v4 endpoint fragments.
@@ -685,7 +760,8 @@ const ENDPOINTS_V4 = {
 	LISTS: {
 		DETAILS: "/list",
 		ITEMS: "/items",
-		ITEM_STATUS: "/item_status"
+		ITEM_STATUS: "/item_status",
+		CLEAR: "/clear"
 	}
 };
 //#endregion
@@ -710,6 +786,7 @@ var TMDBAPIBase = class {
 			this.client = new ApiClient(accessTokenOrClient, {
 				logger: defaultOptions.logger,
 				deduplication: defaultOptions.deduplication,
+				rate_limit: defaultOptions.rate_limit,
 				interceptors: defaultOptions.interceptors
 			});
 		} else if (accessTokenOrClient instanceof ApiClient) this.client = accessTokenOrClient;
@@ -2909,6 +2986,163 @@ var AuthenticationAPI = class extends TMDBAPIBase {
 	}
 };
 //#endregion
+//#region src/endpoints/guest_sessions.ts
+var GuestSessionsAPI = class extends TMDBAPIBase {
+	guestSessionPath(guest_session_id) {
+		return `${ENDPOINTS.GUEST_SESSIONS.DETAILS}/${guest_session_id}`;
+	}
+	guestSessionSubPath(guest_session_id, route) {
+		return `${this.guestSessionPath(guest_session_id)}${route}`;
+	}
+	/**
+	* 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
+	*/
+	async rated_movies(params) {
+		const { guest_session_id, language = this.defaultOptions.language, ...rest } = params;
+		return this.client.request(this.guestSessionSubPath(guest_session_id, ENDPOINTS.GUEST_SESSIONS.RATED_MOVIES), {
+			language,
+			...rest
+		});
+	}
+	/**
+	* 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
+	*/
+	async rated_tv(params) {
+		const { guest_session_id, language = this.defaultOptions.language, ...rest } = params;
+		return this.client.request(this.guestSessionSubPath(guest_session_id, ENDPOINTS.GUEST_SESSIONS.RATED_TV), {
+			language,
+			...rest
+		});
+	}
+	/**
+	* 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
+	*/
+	async rated_tv_episodes(params) {
+		const { guest_session_id, language = this.defaultOptions.language, ...rest } = params;
+		return this.client.request(this.guestSessionSubPath(guest_session_id, ENDPOINTS.GUEST_SESSIONS.RATED_TV_EPISODES), {
+			language,
+			...rest
+		});
+	}
+};
+//#endregion
+//#region src/endpoints/lists.ts
+var ListsAPI = class extends TMDBAPIBase {
+	listPath(list_id) {
+		return `${ENDPOINTS.LISTS.DETAILS}/${list_id}`;
+	}
+	listSubPath(list_id, route) {
+		return `${this.listPath(list_id)}${route}`;
+	}
+	/**
+	* 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
+	*/
+	async details(params) {
+		const { list_id, language = this.defaultOptions.language, ...rest } = params;
+		return this.client.request(this.listPath(list_id), {
+			language,
+			...rest
+		});
+	}
+	/**
+	* 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
+	*/
+	async create(params, body) {
+		return this.client.mutate("POST", ENDPOINTS.LISTS.DETAILS, body, params);
+	}
+	/**
+	* 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
+	*/
+	async delete(params) {
+		const { list_id, ...queryParams } = params;
+		return this.client.mutate("DELETE", this.listPath(list_id), void 0, queryParams);
+	}
+	/**
+	* 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
+	*/
+	async add_movie(params, body) {
+		const { list_id, ...queryParams } = params;
+		return this.client.mutate("POST", this.listSubPath(list_id, ENDPOINTS.LISTS.ADD_ITEM), body, queryParams);
+	}
+	/**
+	* 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
+	*/
+	async remove_movie(params, body) {
+		const { list_id, ...queryParams } = params;
+		return this.client.mutate("POST", this.listSubPath(list_id, ENDPOINTS.LISTS.REMOVE_ITEM), body, queryParams);
+	}
+	/**
+	* 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
+	*/
+	async check_item_status(params) {
+		const { list_id, language = this.defaultOptions.language, ...rest } = params;
+		return this.client.request(this.listSubPath(list_id, ENDPOINTS.LISTS.ITEM_STATUS), {
+			language,
+			...rest
+		});
+	}
+	/**
+	* 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
+	*/
+	async clear(params) {
+		const { list_id, ...queryParams } = params;
+		return this.client.mutate("POST", this.listSubPath(list_id, ENDPOINTS.LISTS.CLEAR), void 0, queryParams);
+	}
+};
+//#endregion
 //#region src/endpoints/v4/auth.ts
 var V4AuthAPI = class extends TMDBAPIBase {
 	/**
@@ -2956,7 +3190,114 @@ var V4AuthAPI = class extends TMDBAPIBase {
 var V4AccountAPI = class extends TMDBAPIBase {};
 //#endregion
 //#region src/endpoints/v4/lists.ts
-var V4ListsAPI = class extends TMDBAPIBase {};
+var V4ListsAPI = class extends TMDBAPIBase {
+	listPath(list_id) {
+		return `${ENDPOINTS_V4.LISTS.DETAILS}/${list_id}`;
+	}
+	/**
+	* 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
+	*/
+	async create(body) {
+		return this.client.mutate("POST", ENDPOINTS_V4.LISTS.DETAILS, body);
+	}
+	/**
+	* 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
+	*/
+	async details({ list_id, ...params }) {
+		return this.client.request(this.listPath(list_id), this.withLanguage(params));
+	}
+	/**
+	* 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
+	*/
+	async update({ list_id, ...body }) {
+		return this.client.mutate("PUT", this.listPath(list_id), body);
+	}
+	/**
+	* 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
+	*/
+	async delete({ list_id }) {
+		return this.client.mutate("DELETE", this.listPath(list_id), {});
+	}
+	/**
+	* 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
+	*/
+	async add_items(list_id, body) {
+		return this.client.mutate("POST", `${this.listPath(list_id)}${ENDPOINTS_V4.LISTS.ITEMS}`, body);
+	}
+	/**
+	* 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
+	*/
+	async update_items(list_id, body) {
+		return this.client.mutate("PUT", `${this.listPath(list_id)}${ENDPOINTS_V4.LISTS.ITEMS}`, body);
+	}
+	/**
+	* 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
+	*/
+	async remove_items(list_id, body) {
+		return this.client.mutate("DELETE", `${this.listPath(list_id)}${ENDPOINTS_V4.LISTS.ITEMS}`, body);
+	}
+	/**
+	* 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
+	*/
+	async item_status({ list_id, ...params }) {
+		return this.client.request(`${this.listPath(list_id)}${ENDPOINTS_V4.LISTS.ITEM_STATUS}`, params);
+	}
+	/**
+	* 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
+	*/
+	async clear(list_id) {
+		return this.client.mutate("GET", `${this.listPath(list_id)}${ENDPOINTS_V4.LISTS.CLEAR}`);
+	}
+};
 //#endregion
 //#region src/tmdb.v4.ts
 /**
@@ -2998,6 +3339,7 @@ var TMDBv4 = class {
 			logger: options.logger,
 			deduplication: options.deduplication,
 			images: options.images,
+			rate_limit: options.rate_limit,
 			interceptors: options.interceptors
 		});
 		this.auth = new V4AuthAPI(this.client, options);
@@ -3038,6 +3380,8 @@ var TMDB = class {
 	people;
 	account;
 	authentication;
+	guest_sessions;
+	lists;
 	/**
 	* 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.
@@ -3061,6 +3405,7 @@ var TMDB = class {
 			logger: options.logger,
 			deduplication: options.deduplication,
 			images: options.images,
+			rate_limit: options.rate_limit,
 			interceptors: options.interceptors
 		});
 		this.movies = new MoviesAPI(this.client, this.options);
@@ -3090,6 +3435,8 @@ var TMDB = class {
 		this.people = new PeopleAPI(this.client, this.options);
 		this.account = new AccountAPI(this.client, this.options);
 		this.authentication = new AuthenticationAPI(this.client, this.options);
+		this.guest_sessions = new GuestSessionsAPI(this.client, this.options);
+		this.lists = new ListsAPI(this.client, this.options);
 	}
 };
 //#endregion
@@ -4408,4 +4755,4 @@ let TVEpisodeGroupType = /* @__PURE__ */ function(TVEpisodeGroupType) {
 	return TVEpisodeGroupType;
 }({});
 //#endregion
-export { AccountAPI, AuthenticationAPI, BACKDROP_SIZES, CertificationsAPI, ChangesAPI, CollectionsAPI, CompaniesAPI, ConfigurationAPI, CreditsAPI, DiscoverAPI, DiscoverTVStatus, DiscoverTVType, FindAPI, GenresAPI, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, KeywordsAPI, LOGO_SIZES, MovieListsAPI, MoviesAPI, NetworksAPI, POSTER_SIZES, PROFILE_SIZES, PeopleAPI, PeopleListsAPI, ReviewsAPI, STILL_SIZES, SearchAPI, TMDB, TMDBCountries, TMDBError, TMDBLogger, TMDBv4, TVEpisodeGroupType, TVEpisodeGroupsAPI, TVEpisodesAPI, TVSeasonsAPI, TVSeriesAPI, TVSeriesListsAPI, TrendingAPI, V4AccountAPI, V4AuthAPI, V4ListsAPI, WatchProvidersAPI, hasBackdropPath, hasLogoPath, hasPosterPath, hasProfilePath, hasStillPath, isJwt, isKnownForMovie, isKnownForTV, isPlainObject, isRecord };
+export { AccountAPI, AuthenticationAPI, BACKDROP_SIZES, CertificationsAPI, ChangesAPI, CollectionsAPI, CompaniesAPI, ConfigurationAPI, CreditsAPI, DiscoverAPI, DiscoverTVStatus, DiscoverTVType, FindAPI, GenresAPI, GuestSessionsAPI, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, KeywordsAPI, LOGO_SIZES, ListsAPI, MovieListsAPI, MoviesAPI, NetworksAPI, POSTER_SIZES, PROFILE_SIZES, PeopleAPI, PeopleListsAPI, ReviewsAPI, STILL_SIZES, SearchAPI, TMDB, TMDBCountries, TMDBError, TMDBLogger, TMDBv4, TVEpisodeGroupType, TVEpisodeGroupsAPI, TVEpisodesAPI, TVSeasonsAPI, TVSeriesAPI, TVSeriesListsAPI, TrendingAPI, V4AccountAPI, V4AuthAPI, V4ListsAPI, WatchProvidersAPI, hasBackdropPath, hasLogoPath, hasPosterPath, hasProfilePath, hasStillPath, isJwt, isKnownForMovie, isKnownForTV, isPlainObject, isRecord };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lorenzopant/tmdb",
-	"version": "1.19.0",
+	"version": "1.20.0",
 	"description": "A completely type-safe The Movie Database (TMDB) API wrapper for typescript applications.",
 	"keywords": [
 		"api",