@lorenzopant/tmdb 1.17.2 → 1.17.4

package/README.md

@@ -28,23 +28,23 @@ yard add @lorenzopant/tmdb
 ## Usage
 
 ```typescript
-import { TMDB } from '@lorenzopant/tmdb';
+import { TMDB } from "@lorenzopant/tmdb";
 
-const tmdb = new TMDB('your_access_token');
+const tmdb = new TMDB("your_access_token");
 
 async function searchMovies() {
-  try {
-    const movies = await tmdb.search.movies({ query: 'Fight Club' });
-    console.log(movies);
-  } catch (error) {
-    if (error instanceof TMDBError) {
-      console.error('TMDB Error:', error.message);
-      console.error('HTTP Status:', error.http_status_code);
-      console.error('TMDB Status Code:', error.tmdb_status_code);
-    } else {
-      console.error('Unknown error:', error);
-    }
-  }
+	try {
+		const movies = await tmdb.search.movies({ query: "Fight Club" });
+		console.log(movies);
+	} catch (error) {
+		if (error instanceof TMDBError) {
+			console.error("TMDB Error:", error.message);
+			console.error("HTTP Status:", error.http_status_code);
+			console.error("TMDB Status Code:", error.tmdb_status_code);
+		} else {
+			console.error("Unknown error:", error);
+		}
+	}
 }
 
 searchMovies();
@@ -77,11 +77,11 @@ Custom logger:
 
 ```typescript
 const tmdb = new TMDB("your_access_token", {
-  logger: (entry) => {
-    if (entry.type === "response") {
-      console.log("TMDB:", entry.endpoint, entry.status, entry.durationMs);
-    }
-  },
+	logger: (entry) => {
+		if (entry.type === "response") {
+			console.log("TMDB:", entry.endpoint, entry.status, entry.durationMs);
+		}
+	},
 });
 ```
 

package/dist/index.d.ts

@@ -25,9 +25,9 @@ type ChangeItem = {
     /** Timestamp of when the change occurred (ISO 8601 format) */
     time: string;
     /** ISO 639-1 language code associated with the change */
-    iso_639_1?: string | null;
+    iso_639_1?: string;
     /** ISO 3166-1 country code associated with the change */
-    iso_3166_1?: string | null;
+    iso_3166_1?: string;
     /** The changed data object (structure varies by change type) */
     value: object | string;
     /** The original data object (structure varies by change type) */
@@ -132,7 +132,7 @@ type GenresResponse = {
  */
 type ProductionCompany = {
     id: number;
-    logo_path: string | null;
+    logo_path?: string;
     name: string;
     origin_country: string;
 };
@@ -157,21 +157,21 @@ type SpokenLanguage = {
 type MovieCollection = {
     id: number;
     name: string;
-    poster_path?: string | null;
-    backdrop_path?: string | null;
+    poster_path?: string;
+    backdrop_path?: string;
 };
 /**
  * Represents common class for cast and crew types
  */
 type Credit = {
     adult: boolean;
-    gender: number | null;
+    gender?: number;
     id: number;
     known_for_department: string;
     name: string;
     original_name: string;
     popularity: number;
-    profile_path?: string | null;
+    profile_path?: string;
     credit_id: string;
 };
 /**
@@ -272,11 +272,11 @@ type WatchMonetizationType = "flatrate" | "free" | "ads" | "rent" | "buy";
  */
 type BaseKnownForItem = {
     adult: boolean;
-    backdrop_path: string | null;
+    backdrop_path?: string;
     id: number;
     original_language: string;
     overview: string;
-    poster_path: string | null;
+    poster_path?: string;
     genre_ids: number[];
     popularity: number;
     vote_average: number;
@@ -446,7 +446,7 @@ type ImageItem = {
     /** Image height in pixels */
     height: number;
     /** ISO 639-1 language code if image contains text, null otherwise */
-    iso_639_1?: string | null;
+    iso_639_1?: string;
     /** Relative path to the image file (append to base URL) */
     file_path: string;
     /** Average user rating for this image */
@@ -580,6 +580,40 @@ type ImagesConfig = {
     default_image_sizes?: Partial<DefaultImageSizesConfig>;
 };
 
+/**
+ * Represents a generic error or an error specific to the TMDB (The Movie Database) API.
+ * This error class extends the built-in `Error` class and includes additional
+ * properties to provide more context about the error.
+ */
+declare class TMDBError extends Error {
+    /**
+     * The status code returned by the TMDB API.
+     * If the value is `-1`, it indicates a library-specific error rather than a TMDB API error.
+     * @reference https://developer.themoviedb.org/docs/errors - code
+     */
+    tmdb_status_code: number;
+    /**
+     * A descriptive message providing details about the error.
+     * If the error is specific to the TMDB API, this message will be derived from the API response
+     * @reference https://developer.themoviedb.org/docs/errors - message
+     */
+    message: string;
+    /**
+     * The HTTP status code associated with the error.
+     * If the error is specific to the TMDB API, this code will be derived from the API response.
+     * @reference https://developer.themoviedb.org/docs/errors - HTTP Status
+     */
+    http_status_code: number;
+    /**
+     * Creates an instance of `TMDBError`.
+     *
+     * @param message - A descriptive message providing details about the error.
+     * @param http_status - The HTTP status code associated with the error.
+     * @param tmdb_status_code - (Optional) The status code returned by the TMDB API. Defaults to `-1` for library-specific errors.
+     */
+    constructor(message: string, http_status: number, tmdb_status_code?: number);
+}
+
 type TMDBLoggerEntry = {
     type: "request" | "response" | "error";
     method: "GET";
@@ -1350,6 +1384,81 @@ declare const TIMEZONE_DATA: readonly [{
     readonly zones: readonly ["Africa/Maputo"];
 }];
 
+/**
+ * Context object passed to every request interceptor before a TMDB API call is made.
+ * Interceptors may return a modified copy of this object to override the endpoint or params,
+ * or return `void` / `undefined` to leave the request unchanged.
+ */
+type RequestInterceptorContext = {
+    /** The API path being requested, e.g. `"/movie/550"`. */
+    endpoint: string;
+    /** Query parameters that will be appended to the URL. Mutating this object has no effect — return a new context instead. */
+    params: Record<string, unknown>;
+    /** The HTTP method. Currently always `"GET"`. */
+    method: "GET";
+};
+/**
+ * A function that runs before each TMDB API request.
+ *
+ * - Return `void` / `undefined` to leave the request unchanged.
+ * - Return a (partial) {@link RequestInterceptorContext} to override `endpoint` and/or `params`.
+ * - Async interceptors are awaited in order.
+ *
+ * @example
+ * ```ts
+ * const tmdb = new TMDB(token, {
+ *   interceptors: {
+ *     request: (ctx) => {
+ *       console.log(`[TMDB] ${ctx.method} ${ctx.endpoint}`, ctx.params);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+type RequestInterceptor = (context: RequestInterceptorContext) => RequestInterceptorContext | void | Promise<RequestInterceptorContext | void>;
+/**
+ * Called after every successful TMDB API response, before data is returned to the caller.
+ *
+ * - Receives the parsed response as `unknown` (the interceptor is not aware of the specific type).
+ * - Return the data (same shape) to pass it through — or return `void` to fall back to the original.
+ * - Designed for side effects: logging, caching, image URL enrichment.
+ * - Must **not** change the shape of the returned data.
+ *
+ * @example
+ * ```ts
+ * const tmdb = new TMDB(token, {
+ *   interceptors: {
+ *     response: {
+ *       onSuccess: (data) => {
+ *         myCache.set(data);
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+type ResponseSuccessInterceptor = (data: unknown) => unknown | void | Promise<unknown | void>;
+/**
+ * Called after a TMDB API error has been normalised into a {@link TMDBError}.
+ *
+ * - Receives a typed `TMDBError` — never raw `unknown`.
+ * - Return `void` — this hook is for side effects only (logging, toast notifications, Sentry).
+ * - The `TMDBError` is **always re-thrown** after the interceptor runs; you cannot suppress it.
+ *
+ * @example
+ * ```ts
+ * const tmdb = new TMDB(token, {
+ *   interceptors: {
+ *     response: {
+ *       onError: (error) => {
+ *         Sentry.captureException(error);
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ */
+type ResponseErrorInterceptor = (error: TMDBError) => void | Promise<void>;
 type TMDBOptions = {
     /**
      * The language to use for requests (ISO 639-1 code)
@@ -1390,6 +1499,38 @@ type TMDBOptions = {
      * @default true
      */
     deduplication?: boolean;
+    /**
+     * Interceptors that run at specific points in the request lifecycle.
+     *
+     * `request` interceptors are called **before** every API request, in the order
+     * they are provided. Each interceptor receives a {@link RequestInterceptorContext}
+     * and may optionally return a modified context to change the endpoint or params.
+     *
+     * @example
+     * ```ts
+     * const tmdb = new TMDB(token, {
+     *   interceptors: {
+     *     request: [
+     *       (ctx) => console.log(`→ ${ctx.endpoint}`),
+     *       (ctx) => ({ ...ctx, params: { ...ctx.params, include_adult: false } }),
+     *     ],
+     *   },
+     * });
+     * ```
+     */
+    interceptors?: {
+        request?: RequestInterceptor | RequestInterceptor[];
+        /**
+         * Response lifecycle hooks.
+         *
+         * - `onSuccess` — runs after every successful response, before data is returned.
+         * - `onError` — runs after a {@link TMDBError} is created; always re-throws after.
+         */
+        response?: {
+            onSuccess?: ResponseSuccessInterceptor;
+            onError?: ResponseErrorInterceptor;
+        };
+    };
 };
 
 /**
@@ -1459,7 +1600,7 @@ declare enum DiscoverTVType {
  * A TV result item as returned by discover endpoints.
  */
 type DiscoverTVResultItem = {
-    backdrop_path: string | null;
+    backdrop_path?: string;
     first_air_date: string;
     genre_ids: number[];
     id: number;
@@ -1469,7 +1610,7 @@ type DiscoverTVResultItem = {
     original_name: string;
     overview: string;
     popularity: number;
-    poster_path: string | null;
+    poster_path?: string;
     vote_average: number;
     vote_count: number;
 };
@@ -1565,7 +1706,7 @@ type CollectionResultItem = {
     /** Collection overview/description */
     overview: string;
     /** Path to poster image */
-    poster_path?: string | null;
+    poster_path?: string;
 };
 /**
  * Company information in search results
@@ -1574,7 +1715,7 @@ type CompanyResultItem = {
     /** Unique company identifier */
     id: number;
     /** Path to company logo image */
-    logo_path?: string | null;
+    logo_path?: string;
     /** Company name */
     name: string;
     /** ISO 3166-1 country code of company's origin */
@@ -1603,7 +1744,7 @@ type PersonResultItem = {
     /** TMDB popularity score based on views, votes, and activity */
     popularity: number;
     /** Path to person's profile image */
-    profile_path?: string | null;
+    profile_path?: string;
     /** List of notable movies or TV shows the person is known for */
     known_for: KnownForItem[];
 };
@@ -1616,7 +1757,7 @@ type PersonResultItem = {
  */
 type TVSeriesResultItem = {
     /** Relative path to the backdrop image for the series (nullable on some responses). */
-    backdrop_path?: string | null;
+    backdrop_path?: string;
     /** First air date of the series (YYYY-MM-DD). */
     first_air_date: string;
     /** Array of genre ids associated with the series. */
@@ -1634,7 +1775,7 @@ type TVSeriesResultItem = {
     /** Popularity score as returned by TMDB. */
     popularity: number;
     /** Relative path to the poster image for the series (nullable on some responses). */
-    poster_path?: string | null;
+    poster_path?: string;
     /** Average vote score for the series. */
     vote_average: number;
     /** Total number of votes the series has received. */
@@ -1647,7 +1788,7 @@ type TVSeriesResultItem = {
  */
 type MovieResultItem = {
     /** Path to backdrop image */
-    backdrop_path?: string | null;
+    backdrop_path?: string;
     /** Unique movie identifier */
     id: number;
     /** Movie title (localized) */
@@ -1657,7 +1798,7 @@ type MovieResultItem = {
     /** Plot synopsis/overview */
     overview: string;
     /** Path to poster image */
-    poster_path?: string | null;
+    poster_path?: string;
     /** Whether the movie is marked as adult content */
     adult: boolean;
     /** Original language of the movie (ISO 639-1 code) */
@@ -1804,19 +1945,19 @@ type MovieDetails = {
     /** Whether the movie is marked as adult content */
     adult: boolean;
     /** Path to backdrop image, null if not available */
-    backdrop_path: string | null;
+    backdrop_path?: string;
     /** Collection the movie belongs to (e.g., "The Lord of the Rings Collection"), null if standalone */
-    belongs_to_collection: MovieCollection | null;
+    belongs_to_collection?: MovieCollection;
     /** Production budget in US dollars */
     budget: number;
     /** Array of genres associated with the movie */
     genres: Genre[];
     /** Official homepage URL, null if not available */
-    homepage: string | null;
+    homepage?: string;
     /** Unique movie identifier in TMDB */
     id: number;
     /** IMDb identifier (e.g., "tt0133093"), null if not linked */
-    imdb_id: string | null;
+    imdb_id?: string;
     /** Array of origin country codes (ISO 3166-1) */
     origin_country: string[];
     /** Original language of the movie (ISO 639-1 code) */
@@ -1824,11 +1965,11 @@ type MovieDetails = {
     /** Original title in the original language */
     original_title: string;
     /** Plot synopsis/overview, null if not available */
-    overview: string | null;
+    overview?: string;
     /** Popularity score calculated by TMDB */
     popularity: number;
     /** Path to poster image, null if not available */
-    poster_path: string | null;
+    poster_path?: string;
     /** Array of companies that produced the movie */
     production_companies: ProductionCompany[];
     /** Array of countries where the movie was produced */
@@ -1838,13 +1979,13 @@ type MovieDetails = {
     /** Box office revenue in US dollars */
     revenue: number;
     /** Runtime in minutes, null if not set */
-    runtime: number | null;
+    runtime?: number;
     /** Array of languages spoken in the movie */
     spoken_languages: SpokenLanguage[];
     /** Release status (e.g., "Released", "Post Production", "In Production") */
     status: string;
     /** Movie tagline/slogan, null if not available */
-    tagline: string | null;
+    tagline?: string;
     /** Movie title (localized if language parameter was provided) */
     title: string;
     /** Whether a video is available on TMDB */
@@ -1917,13 +2058,13 @@ type MovieExternalIDs = {
     /** Movie identifier in TMDB */
     id: number;
     /** IMDb identifier (e.g., "tt0133093"), null if not available */
-    imdb_id?: string | null;
+    imdb_id?: string;
     /** Facebook page identifier, null if not available */
-    facebook_id?: string | null;
+    facebook_id?: string;
     /** Twitter/X handle, null if not available */
-    twitter_id?: string | null;
+    twitter_id?: string;
     /** Instagram handle, null if not available */
-    instagram_id?: string | null;
+    instagram_id?: string;
 };
 /**
  * Collection of movie images (backdrops, logos, posters)
@@ -2126,9 +2267,9 @@ type NetworkImages = ImagesResult<OrganizationImage, "logos">;
  */
 type Network = NetworkItem & {
     /** The city or location of the network's headquarters, if available. */
-    headquarters?: string | null;
+    headquarters?: string;
     /** The URL of the network's official homepage, if available. */
-    homepage?: string | null;
+    homepage?: string;
 };
 /**
  * Base parameters required by all network endpoints.
@@ -2145,7 +2286,7 @@ type NetworkBaseParams = {
  */
 type TVSeriesDetails = {
     /** The path to the backdrop image, or null if not available */
-    backdrop_path: string | null;
+    backdrop_path?: string;
     /** Array of creators who developed the TV show */
     created_by: Pick<Credit, "id" | "credit_id" | "gender" | "name" | "profile_path">[];
     /** Array of typical episode runtimes in minutes */
@@ -2155,7 +2296,7 @@ type TVSeriesDetails = {
     /** Array of genres associated with the TV show */
     genres: Genre[];
     /** The official homepage URL for the TV show, or null if not available */
-    homepage: string | null;
+    homepage?: string;
     /** The unique identifier for the TV show */
     id: number;
     /** Indicates whether the TV show is currently in production */
@@ -2165,7 +2306,7 @@ type TVSeriesDetails = {
     /** The date the most recent episode aired */
     last_air_date: string;
     /** Details of the last episode that aired, if available */
-    last_episode_to_air?: TVEpisodeItem | null;
+    last_episode_to_air?: TVEpisodeItem;
     /** The title of the TV show */
     name: string;
     /** Details of the next episode to air, if available */
@@ -2183,11 +2324,11 @@ type TVSeriesDetails = {
     /** The original title of the TV show */
     original_name: string;
     /** A brief description or summary of the TV show, or null if not available */
-    overview: string | null;
+    overview?: string;
     /** The popularity score of the TV show */
     popularity: number;
     /** The path to the poster image, or null if not available */
-    poster_path: string | null;
+    poster_path?: string;
     /** Array of companies that produced the TV show */
     production_companies?: ProductionCompany[];
     /** Array of countries where the TV show was produced */
@@ -2217,19 +2358,19 @@ type TVEpisodeItem = {
     /** The total number of votes received for the episode */
     vote_count: number;
     /** The date the episode first aired */
-    air_date?: string | null;
+    air_date?: string;
     /** The episode number within its season */
     episode_number: number;
     /** The production code used internally during filming */
-    production_code?: string | null;
+    production_code?: string;
     /** The runtime of the episode in minutes */
-    runtime?: number | null;
+    runtime?: number;
     /** The season number this episode belongs to */
     season_number: number;
     /** The unique identifier of the TV show this episode belongs to */
     show_id: number;
     /** The path to the episode's still image (screenshot) */
-    still_path?: string | null;
+    still_path?: string;
 };
 type TVSeasonItem = {
     /** The date the season first aired, or null if not available */
@@ -2388,23 +2529,23 @@ type TVExternalIDs = {
     /** TV series identifier in TMDB */
     id: number;
     /** IMDb identifier (e.g., "tt0944947"), null if not available */
-    imdb_id?: string | null;
+    imdb_id?: string;
     /** Freebase MID identifier (deprecated), null if not available */
-    freebase_mid?: string | null;
+    freebase_mid?: string;
     /** Freebase ID (deprecated), null if not available */
-    freebase_id?: string | null;
+    freebase_id?: string;
     /** TheTVDB identifier, null if not available */
-    tvdb_id?: number | null;
+    tvdb_id?: number;
     /** TVRage identifier (service discontinued), null if not available */
-    tvrage_id?: number | null;
+    tvrage_id?: number;
     /** Wikidata identifier (e.g., "Q23572"), null if not available */
-    wikidata_id?: string | null;
+    wikidata_id?: string;
     /** Facebook page identifier, null if not available */
-    facebook_id?: string | null;
+    facebook_id?: string;
     /** Instagram handle, null if not available */
-    instagram_id?: string | null;
+    instagram_id?: string;
     /** Twitter/X handle, null if not available */
-    twitter_id?: string | null;
+    twitter_id?: string;
 };
 /**
  * Images related to a TV show.
@@ -2614,7 +2755,7 @@ type TVSeasonEpisode = TVEpisodeItem & {
  */
 type TVSeason = {
     /** ISO 8601 date when the season first aired */
-    air_date?: string | null;
+    air_date?: string;
     /** Array of episodes in this season */
     episodes: TVSeasonEpisode[];
     /** Unique TMDB identifier for the season */
@@ -2626,7 +2767,7 @@ type TVSeason = {
     /** Season overview/description */
     overview: string;
     /** Relative path to the season poster */
-    poster_path?: string | null;
+    poster_path?: string;
     /** Season number within the TV show */
     season_number: number;
     /** Average user rating (0–10) */
@@ -2678,8 +2819,8 @@ type TVSeasonExternalIDs = Pick<TVExternalIDs, "id" | "freebase_mid" | "freebase
 type TVSeasonImages = ImagesResult<ImageItem, "posters">;
 /** Translation data for a TV season. */
 type TVSeasonTranslationData = {
-    name?: string | null;
-    overview?: string | null;
+    name?: string;
+    overview?: string;
 };
 /** Collection of all available translations for a TV season. */
 type TVSeasonTranslations = TranslationResults<TVSeasonTranslationData>;
@@ -2727,13 +2868,13 @@ type TVEpisode = {
     /** Unique TMDB identifier for this episode */
     id: number;
     /** Production code assigned by the production company, if available */
-    production_code?: string | null;
+    production_code?: string;
     /** Runtime of the episode in minutes */
     runtime: number;
     /** Season number this episode belongs to (1-based) */
     season_number: number;
     /** Relative path to the episode still/image (e.g. `"/abc123.jpg"`), or null if none */
-    still_path?: string | null;
+    still_path?: string;
     /** Average user rating of the episode (0-10 scale) */
     vote_average: number;
     /** Total number of user votes for the episode */
@@ -2771,8 +2912,8 @@ type TVEpisodeExternalIDs = Omit<TVExternalIDs, "facebook_id" | "instagram_id" |
 type TVEpisodeImages = ImagesResult<ImageItem, "stills">;
 type TVEpisodeTranslations = TranslationResults<TVEpisodeTranslationData>;
 type TVEpisodeTranslationData = {
-    name?: string | null;
-    overview?: string | null;
+    name?: string;
+    overview?: string;
 };
 type TVEpisodeVideos = VideoResults;
 /**
@@ -2817,7 +2958,7 @@ type Collection = {
     /** Short description or synopsis of the collection */
     overview: string;
     /** Relative path to the collection's poster image on TMDB, if available (sanitized nulls become undefined) */
-    poster_path?: string | null;
+    poster_path?: string;
     /** Relative path to the collection's backdrop image on TMDB, if available (sanitized nulls become undefined) */
     backdrop_path?: string | null;
     /** Ordered list of media items that make up the collection */
@@ -2877,7 +3018,7 @@ type CompanySummary = {
     /** Unique company identifier */
     id: number;
     /** Relative path to the company logo */
-    logo_path?: string | null;
+    logo_path?: string;
     /** Company display name */
     name: string;
 };
@@ -2892,9 +3033,9 @@ type Company = CompanySummary & {
     /** Company headquarters location */
     headquarters: string;
     /** Official company homepage */
-    homepage: string | null;
+    homepage?: string;
     /** Parent company, if TMDB links one */
-    parent_company?: CompanySummary | null;
+    parent_company?: CompanySummary;
 };
 /**
  * A single alternative company name entry.
@@ -2961,9 +3102,9 @@ type TVEpisodeGroupDetailsItem = {
  */
 type TVEpisodeGroupEpisode = Omit<TVEpisode, "guest_stars" | "runtime"> & {
     /** Production code for the episode, if available */
-    production_code?: string | null;
+    production_code?: string;
     /** Path to the episode still image, if available */
-    still_path?: string | null;
+    still_path?: string;
 };
 /**
  * Supported episode group type identifiers.
@@ -2998,11 +3139,11 @@ type FindByIDParams = {
 };
 type FindMediaResultBase = {
     adult: boolean;
-    backdrop_path: string | null;
+    backdrop_path?: string;
     id: number;
     original_language: string;
     overview: string;
-    poster_path: string | null;
+    poster_path?: string;
     popularity: number;
     vote_average: number;
     vote_count: number;
@@ -3022,14 +3163,14 @@ type FindMovieResultItem = FindMediaResultBase & {
  */
 type FindPersonResultItem = {
     adult: boolean;
-    gender: number | null;
+    gender?: number;
     id: number;
     known_for_department: string;
     media_type: "person";
     name: string;
     original_name: string;
     popularity: number;
-    profile_path: string | null;
+    profile_path?: string;
 };
 /**
  * TV series item returned inside `tv_results`.
@@ -3054,7 +3195,7 @@ type FindTVEpisodeResultItem = {
     production_code: string;
     season_number: number;
     show_id: number;
-    still_path: string | null;
+    still_path?: string;
     vote_average: number;
     vote_count: number;
 };
@@ -3068,7 +3209,7 @@ type FindTVSeasonResultItem = {
     media_type: "tv_season";
     name: string;
     overview: string;
-    poster_path: string | null;
+    poster_path?: string;
     season_number: number;
 };
 /**
@@ -3148,7 +3289,7 @@ type CreditDetailsMediaBase = {
     /** Indicates whether the title is marked for adult content. */
     adult: boolean;
     /** Relative path to the backdrop image, if available. */
-    backdrop_path?: string | null;
+    backdrop_path?: string;
     /** Character name when the credit belongs to cast. */
     character?: string;
     /** Genre identifiers attached to the media item. */
@@ -3160,7 +3301,7 @@ type CreditDetailsMediaBase = {
     /** Plot summary. */
     overview: string;
     /** Relative path to the poster image, if available. */
-    poster_path?: string | null;
+    poster_path?: string;
     /** Popularity score. */
     popularity: number;
     /** Average vote score. */
@@ -3190,7 +3331,7 @@ type CreditDetailsTVEpisode = {
     /** Indicates whether the episode is marked for adult content. */
     adult: boolean;
     /** Episode air date in ISO 8601 format, if available. */
-    air_date?: string | null;
+    air_date?: string;
     /** Episode number within the season. */
     episode_number: number;
     /** Episode type reported by TMDB. */
@@ -3204,11 +3345,11 @@ type CreditDetailsTVEpisode = {
     /** Production code if available. */
     production_code: string;
     /** Runtime in minutes, if available. */
-    runtime?: number | null;
+    runtime?: number;
     /** Season number for the episode. */
     season_number: number;
     /** Episode still image path, if available. */
-    still_path?: string | null;
+    still_path?: string;
     /** Average vote score. */
     vote_average: number;
     /** Total vote count. */
@@ -3219,7 +3360,7 @@ type CreditDetailsTVEpisode = {
  */
 type CreditDetailsTVSeason = {
     /** Season air date in ISO 8601 format, if available. */
-    air_date?: string | null;
+    air_date?: string;
     /** Total number of episodes in the season. */
     episode_count: number;
     /** Unique season identifier. */
@@ -3229,7 +3370,7 @@ type CreditDetailsTVSeason = {
     /** Plot summary. */
     overview: string;
     /** Relative path to the season poster, if available. */
-    poster_path?: string | null;
+    poster_path?: string;
     /** Season number within the series. */
     season_number: number;
     /** Average vote score. */
@@ -3529,9 +3670,19 @@ declare class ApiClient {
      */
     private inflightRequests;
     private deduplication;
+    private requestInterceptors;
+    private onSuccessInterceptor?;
+    private onErrorInterceptor?;
     constructor(accessToken: string, options?: {
         logger?: boolean | TMDBLoggerFn;
         deduplication?: boolean;
+        interceptors?: {
+            request?: RequestInterceptor | RequestInterceptor[];
+            response?: {
+                onSuccess?: ResponseSuccessInterceptor;
+                onError?: ResponseErrorInterceptor;
+            };
+        };
     });
     /**
      * Builds a stable, order-independent cache key for a request.
@@ -3541,6 +3692,11 @@ declare class ApiClient {
      * `{ language, page }` and `{ page, language }` produce the same key.
      */
     private buildRequestKey;
+    /**
+     * Serializes request params once so URL construction and deduplication keys stay aligned.
+     * `undefined` values are intentionally skipped because they are not sent to TMDB.
+     */
+    private serializeParams;
     /**
      * Makes an authenticated GET request to the TMDB API, returning the parsed and
      * null-sanitised response.
@@ -3553,6 +3709,11 @@ declare class ApiClient {
      * `TMDBOptions.deduplication = false`.
      */
     request<T>(endpoint: string, params?: Record<string, unknown | undefined>): Promise<T>;
+    /**
+     * 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.
+     */
+    private runRequestInterceptors;
     /**
      * The actual fetch + response-parsing pipeline. Called by `request()` only when no
      * matching in-flight promise exists. Handles URL construction, auth headers, logging,
@@ -5048,40 +5209,27 @@ declare class TMDB {
     constructor(accessToken: string, options?: TMDBOptions);
 }
 
-/**
- * Represents a generic error or an error specific to the TMDB (The Movie Database) API.
- * This error class extends the built-in `Error` class and includes additional
- * properties to provide more context about the error.
- */
-declare class TMDBError extends Error {
-    /**
-     * The status code returned by the TMDB API.
-     * If the value is `-1`, it indicates a library-specific error rather than a TMDB API error.
-     * @reference https://developer.themoviedb.org/docs/errors - code
-     */
-    tmdb_status_code: number;
-    /**
-     * A descriptive message providing details about the error.
-     * If the error is specific to the TMDB API, this message will be derived from the API response
-     * @reference https://developer.themoviedb.org/docs/errors - message
-     */
-    message: string;
-    /**
-     * The HTTP status code associated with the error.
-     * If the error is specific to the TMDB API, this code will be derived from the API response.
-     * @reference https://developer.themoviedb.org/docs/errors - HTTP Status
-     */
-    http_status_code: number;
-    /**
-     * Creates an instance of `TMDBError`.
-     *
-     * @param message - A descriptive message providing details about the error.
-     * @param http_status - The HTTP status code associated with the error.
-     * @param tmdb_status_code - (Optional) The status code returned by the TMDB API. Defaults to `-1` for library-specific errors.
-     */
-    constructor(message: string, http_status: number, tmdb_status_code?: number);
-}
-
 declare function isJwt(token: string): boolean;
 
-export { type AlternativeName, type AlternativeNamesResult, type AlternativeTitle, BACKDROP_SIZES, type BackdropSize, type Cast, type CertificationItem, type Certifications, type Change, type ChangeItem, type ChangeResultItem, type Changes, type Collection, type CollectionBaseParam, type CollectionDetailsParams, type CollectionImages, type CollectionImagesParams, type CollectionItem, type CollectionResultItem, type CollectionTranslationData, type CollectionTranslations, type Company, type CompanyAlternativeName, type CompanyAlternativeNames, type CompanyAlternativeNamesParams, type CompanyBaseParam, type CompanyDetailsParams, type CompanyImages, type CompanyImagesParams, type CompanyResultItem, type CompanySummary, type ConfigurationCountriesParams, type ConfigurationCountry, type ConfigurationJob, type ConfigurationLanguage, type ConfigurationResponse, type ConfigurationTimezone, type ContentRating, type CountryISO3166_1, type Credit, type CreditBaseParam, type CreditDetails, type CreditDetailsMedia, type CreditDetailsMovieMedia, type CreditDetailsParams, type CreditDetailsPerson, type CreditDetailsTVEpisode, type CreditDetailsTVMedia, type CreditDetailsTVSeason, type Crew, type DateRange, type DefaultImageSizesConfig, type DiscoverFilterExpression, type DiscoverMovieParams, type DiscoverMovieSortBy, type DiscoverTVParams, type DiscoverTVResultItem, type DiscoverTVSortBy, DiscoverTVStatus, DiscoverTVType, type FileType, type FindByIDParams, type FindExternalSource, type FindMovieResultItem, type FindPersonResultItem, type FindResults, type FindTVEpisodeResultItem, type FindTVResultItem, type FindTVSeasonResultItem, type Genre, type GenresResponse, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, type ImageCollectionKey, type ImageConfiguration, type ImageItem, type ImageSize, type ImageSizeTypes, type ImagesConfig, type ImagesResult, type Keyword, type KeywordBaseParam, type KeywordDetailsParams, type KeywordMoviesParams, type KeywordResultItem, type KnownForItem, type KnownForMovie, type KnownForTV, LOGO_SIZES, type Language, type LanguageISO6391, type LiteralUnion, type LogoSize, type MediaType, type MediaWatchProviders, type MovieAlternativeTitles, type MovieAlternativeTitlesParams, type MovieAppendToResponseNamespace, type MovieAppendableMap, type MovieChanges, type MovieChangesParams, type MovieCollection, type MovieCredits, type MovieCreditsParams, type MovieDetails, type MovieDetailsParams, type MovieDetailsWithAppends, type MovieExternalIDs, type MovieExternalIDsParams, type MovieImages, type MovieImagesParams, type MovieKeywords, type MovieKeywordsParams, type MovieListParams, type MovieRecommendations, type MovieRecommendationsParams, type MovieReleaseDate, type MovieReleaseDateResult, type MovieReleaseDates, type MovieReleaseDatesParams, type MovieResultItem, type MovieReviews, type MovieReviewsParams, type MovieSimilar, type MovieSimilarParams, type MovieTranslationData, type MovieTranslations, type MovieTranslationsParams, type MovieVideos, type MovieVideosParams, type MovieWatchProvidersParams, type MultiSearchResultItem, type Network, type NetworkBaseParams, type NetworkImages, type NetworkItem, type OrganizationImage, POSTER_SIZES, PROFILE_SIZES, type PaginatedResponse, type PeopleListParams, type PersonAppendToResponseNamespace, type PersonAppendableMap, type PersonBaseParam, type PersonChanges, type PersonChangesParams, type PersonCombinedCastCredit, type PersonCombinedCredits, type PersonCombinedCrewCredit, type PersonCreditsParams, type PersonDetails, type PersonDetailsParams, type PersonDetailsWithAppends, type PersonExternalIDs, type PersonExternalIDsParams, type PersonImages, type PersonImagesParams, type PersonMovieCastCredit, type PersonMovieCredits, type PersonMovieCrewCredit, type PersonResultItem, type PersonTVCastCredit, type PersonTVCredits, type PersonTVCrewCredit, type PersonTaggedImage, type PersonTaggedImageMedia, type PersonTaggedImages, type PersonTaggedImagesParams, type PersonTranslationData, type PersonTranslations, type PersonTranslationsParams, type PosterSize, type Prettify, type PrimaryTranslations, type ProductionCompany, type ProductionCountry, type ProfileSize, type Review, type ReviewAuthorDetails, type ReviewDetails, type ReviewDetailsParams, STILL_SIZES, type SearchCollectionsParams, type SearchCompanyParams, type SearchKeywordsParams, type SearchMoviesParams, type SearchMultiParams, type SearchPersonParams, type SearchTVSeriesParams, type SpokenLanguage, type StillSize, TMDB, TMDBCountries, TMDBError, TMDBLogger, type TMDBLoggerEntry, type TMDBLoggerFn, type TMDBOptions, type TMDBQueryParams, type TVAggregateCredits, type TVAggregateCreditsCastItem, type TVAggregateCreditsCrewItem, type TVAggregateCreditsParams, type TVAlternativeTitles, type TVAppendToResponseNamespace, type TVAppendableMap, type TVBaseParam, type TVChangeParams, type TVContentRatings, type TVCreditJob, type TVCreditRole, type TVCredits, type TVCreditsParams, type TVDetailsParams, type TVDetailsWithAppends, type TVEpisode, type TVEpisodeAppendToResponseNamespace, type TVEpisodeAppendableMap, type TVEpisodeBaseParams, type TVEpisodeCredits, type TVEpisodeCreditsParams, type TVEpisodeDetailsParams, type TVEpisodeDetailsWithAppends, type TVEpisodeExternalIDs, type TVEpisodeGroupDetails, type TVEpisodeGroupDetailsItem, type TVEpisodeGroupEpisode, type TVEpisodeGroupItem, type TVEpisodeGroupParams, TVEpisodeGroupType, type TVEpisodeGroups, type TVEpisodeId, type TVEpisodeImages, type TVEpisodeImagesParams, type TVEpisodeItem, type TVEpisodeTranslationData, type TVEpisodeTranslations, type TVEpisodeVideos, type TVExternalIDs, type TVImageItem, type TVImages, type TVImagesParams, type TVKeywords, type TVRecommendations, type TVRecommendationsParams, type TVReviews, type TVReviewsParams, type TVScreenedTheatrically, type TVScreeningItem, type TVSeason, type TVSeasonAggregateCredits, type TVSeasonAggregateCreditsParams, type TVSeasonAppendToResponseNamespace, type TVSeasonAppendableMap, type TVSeasonBaseParams, type TVSeasonChanges, type TVSeasonChangesParams, type TVSeasonCredits, type TVSeasonCreditsParams, type TVSeasonDetailsParams, type TVSeasonDetailsWithAppends, type TVSeasonEpisode, type TVSeasonExternalIDs, type TVSeasonId, type TVSeasonImages, type TVSeasonImagesParams, type TVSeasonItem, type TVSeasonTranslationData, type TVSeasonTranslations, type TVSeasonVideos, type TVSeasonVideosParams, type TVSeasonWatchProvidersParams, type TVSeriesChanges, type TVSeriesDetails, type TVSeriesListItem, type TVSeriesListParams, type TVSeriesLists, type TVSeriesListsParams, type TVSeriesResultItem, type TVSimilar, type TVSimilarParams, type TVTranslationData, type TVTranslations, type TVVideos, type Timezone, type Translation, type TranslationResults, type TrendingAllResult, type TrendingMovieResult, type TrendingParams, type TrendingPersonResult, type TrendingTVResult, type TrendingTimeWindow, type VideoItem, type VideoResults, type WatchMonetizationType, type WatchProvider, type WatchProviderDisplayPriorities, type WatchProviderItem, type WatchProviderListItem, type WatchProviderListParams, type WatchProviderListResponse, type WatchProviderRegionsParams, type WatchProviderRegionsResponse, type WithLanguage, type WithLanguagePage, type WithPage, type WithPageAndDateRange, type WithParams, type WithRegion, isJwt, isKnownForMovie, isKnownForTV };
+/** Utility type guard to check if an object has a poster_path property */
+declare function hasPosterPath(data: unknown): data is {
+    poster_path: string;
+};
+/** Utility type guard to check if an object has a backdrop_path property */
+declare function hasBackdropPath(data: unknown): data is {
+    backdrop_path: string;
+};
+/** Utility type guard to check if an object has a profile_path property */
+declare function hasProfilePath(data: unknown): data is {
+    profile_path: string;
+};
+/** Utility type guard to check if an object has a still_path property */
+declare function hasStillPath(data: unknown): data is {
+    still_path: string;
+};
+/** Utility type guard to check if an object has a logo_path property */
+declare function hasLogoPath(data: unknown): data is {
+    logo_path: string;
+};
+
+export { type AlternativeName, type AlternativeNamesResult, type AlternativeTitle, BACKDROP_SIZES, type BackdropSize, type Cast, type CertificationItem, type Certifications, type Change, type ChangeItem, type ChangeResultItem, type Changes, type Collection, type CollectionBaseParam, type CollectionDetailsParams, type CollectionImages, type CollectionImagesParams, type CollectionItem, type CollectionResultItem, type CollectionTranslationData, type CollectionTranslations, type Company, type CompanyAlternativeName, type CompanyAlternativeNames, type CompanyAlternativeNamesParams, type CompanyBaseParam, type CompanyDetailsParams, type CompanyImages, type CompanyImagesParams, type CompanyResultItem, type CompanySummary, type ConfigurationCountriesParams, type ConfigurationCountry, type ConfigurationJob, type ConfigurationLanguage, type ConfigurationResponse, type ConfigurationTimezone, type ContentRating, type CountryISO3166_1, type Credit, type CreditBaseParam, type CreditDetails, type CreditDetailsMedia, type CreditDetailsMovieMedia, type CreditDetailsParams, type CreditDetailsPerson, type CreditDetailsTVEpisode, type CreditDetailsTVMedia, type CreditDetailsTVSeason, type Crew, type DateRange, type DefaultImageSizesConfig, type DiscoverFilterExpression, type DiscoverMovieParams, type DiscoverMovieSortBy, type DiscoverTVParams, type DiscoverTVResultItem, type DiscoverTVSortBy, DiscoverTVStatus, DiscoverTVType, type FileType, type FindByIDParams, type FindExternalSource, type FindMovieResultItem, type FindPersonResultItem, type FindResults, type FindTVEpisodeResultItem, type FindTVResultItem, type FindTVSeasonResultItem, type Genre, type GenresResponse, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, type ImageCollectionKey, type ImageConfiguration, type ImageItem, type ImageSize, type ImageSizeTypes, type ImagesConfig, type ImagesResult, type Keyword, type KeywordBaseParam, type KeywordDetailsParams, type KeywordMoviesParams, type KeywordResultItem, type KnownForItem, type KnownForMovie, type KnownForTV, LOGO_SIZES, type Language, type LanguageISO6391, type LiteralUnion, type LogoSize, type MediaType, type MediaWatchProviders, type MovieAlternativeTitles, type MovieAlternativeTitlesParams, type MovieAppendToResponseNamespace, type MovieAppendableMap, type MovieChanges, type MovieChangesParams, type MovieCollection, type MovieCredits, type MovieCreditsParams, type MovieDetails, type MovieDetailsParams, type MovieDetailsWithAppends, type MovieExternalIDs, type MovieExternalIDsParams, type MovieImages, type MovieImagesParams, type MovieKeywords, type MovieKeywordsParams, type MovieListParams, type MovieRecommendations, type MovieRecommendationsParams, type MovieReleaseDate, type MovieReleaseDateResult, type MovieReleaseDates, type MovieReleaseDatesParams, type MovieResultItem, type MovieReviews, type MovieReviewsParams, type MovieSimilar, type MovieSimilarParams, type MovieTranslationData, type MovieTranslations, type MovieTranslationsParams, type MovieVideos, type MovieVideosParams, type MovieWatchProvidersParams, type MultiSearchResultItem, type Network, type NetworkBaseParams, type NetworkImages, type NetworkItem, type OrganizationImage, POSTER_SIZES, PROFILE_SIZES, type PaginatedResponse, type PeopleListParams, type PersonAppendToResponseNamespace, type PersonAppendableMap, type PersonBaseParam, type PersonChanges, type PersonChangesParams, type PersonCombinedCastCredit, type PersonCombinedCredits, type PersonCombinedCrewCredit, type PersonCreditsParams, type PersonDetails, type PersonDetailsParams, type PersonDetailsWithAppends, type PersonExternalIDs, type PersonExternalIDsParams, type PersonImages, type PersonImagesParams, type PersonMovieCastCredit, type PersonMovieCredits, type PersonMovieCrewCredit, type PersonResultItem, type PersonTVCastCredit, type PersonTVCredits, type PersonTVCrewCredit, type PersonTaggedImage, type PersonTaggedImageMedia, type PersonTaggedImages, type PersonTaggedImagesParams, type PersonTranslationData, type PersonTranslations, type PersonTranslationsParams, type PosterSize, type Prettify, type PrimaryTranslations, type ProductionCompany, type ProductionCountry, type ProfileSize, type RequestInterceptor, type RequestInterceptorContext, type ResponseErrorInterceptor, type ResponseSuccessInterceptor, type Review, type ReviewAuthorDetails, type ReviewDetails, type ReviewDetailsParams, STILL_SIZES, type SearchCollectionsParams, type SearchCompanyParams, type SearchKeywordsParams, type SearchMoviesParams, type SearchMultiParams, type SearchPersonParams, type SearchTVSeriesParams, type SpokenLanguage, type StillSize, TMDB, TMDBCountries, TMDBError, TMDBLogger, type TMDBLoggerEntry, type TMDBLoggerFn, type TMDBOptions, type TMDBQueryParams, type TVAggregateCredits, type TVAggregateCreditsCastItem, type TVAggregateCreditsCrewItem, type TVAggregateCreditsParams, type TVAlternativeTitles, type TVAppendToResponseNamespace, type TVAppendableMap, type TVBaseParam, type TVChangeParams, type TVContentRatings, type TVCreditJob, type TVCreditRole, type TVCredits, type TVCreditsParams, type TVDetailsParams, type TVDetailsWithAppends, type TVEpisode, type TVEpisodeAppendToResponseNamespace, type TVEpisodeAppendableMap, type TVEpisodeBaseParams, type TVEpisodeCredits, type TVEpisodeCreditsParams, type TVEpisodeDetailsParams, type TVEpisodeDetailsWithAppends, type TVEpisodeExternalIDs, type TVEpisodeGroupDetails, type TVEpisodeGroupDetailsItem, type TVEpisodeGroupEpisode, type TVEpisodeGroupItem, type TVEpisodeGroupParams, TVEpisodeGroupType, type TVEpisodeGroups, type TVEpisodeId, type TVEpisodeImages, type TVEpisodeImagesParams, type TVEpisodeItem, type TVEpisodeTranslationData, type TVEpisodeTranslations, type TVEpisodeVideos, type TVExternalIDs, type TVImageItem, type TVImages, type TVImagesParams, type TVKeywords, type TVRecommendations, type TVRecommendationsParams, type TVReviews, type TVReviewsParams, type TVScreenedTheatrically, type TVScreeningItem, type TVSeason, type TVSeasonAggregateCredits, type TVSeasonAggregateCreditsParams, type TVSeasonAppendToResponseNamespace, type TVSeasonAppendableMap, type TVSeasonBaseParams, type TVSeasonChanges, type TVSeasonChangesParams, type TVSeasonCredits, type TVSeasonCreditsParams, type TVSeasonDetailsParams, type TVSeasonDetailsWithAppends, type TVSeasonEpisode, type TVSeasonExternalIDs, type TVSeasonId, type TVSeasonImages, type TVSeasonImagesParams, type TVSeasonItem, type TVSeasonTranslationData, type TVSeasonTranslations, type TVSeasonVideos, type TVSeasonVideosParams, type TVSeasonWatchProvidersParams, type TVSeriesChanges, type TVSeriesDetails, type TVSeriesListItem, type TVSeriesListParams, type TVSeriesLists, type TVSeriesListsParams, type TVSeriesResultItem, type TVSimilar, type TVSimilarParams, type TVTranslationData, type TVTranslations, type TVVideos, type Timezone, type Translation, type TranslationResults, type TrendingAllResult, type TrendingMovieResult, type TrendingParams, type TrendingPersonResult, type TrendingTVResult, type TrendingTimeWindow, type VideoItem, type VideoResults, type WatchMonetizationType, type WatchProvider, type WatchProviderDisplayPriorities, type WatchProviderItem, type WatchProviderListItem, type WatchProviderListParams, type WatchProviderListResponse, type WatchProviderRegionsParams, type WatchProviderRegionsResponse, type WithLanguage, type WithLanguagePage, type WithPage, type WithPageAndDateRange, type WithParams, type WithRegion, hasBackdropPath, hasLogoPath, hasPosterPath, hasProfilePath, hasStillPath, isJwt, isKnownForMovie, isKnownForTV };

package/dist/index.js

@@ -126,6 +126,23 @@ function isJwt(token) {
   return true;
 }
 
+// src/utils/index.ts
+function hasPosterPath(data) {
+  return typeof data === "object" && data !== null && "poster_path" in data && typeof data.poster_path === "string";
+}
+function hasBackdropPath(data) {
+  return typeof data === "object" && data !== null && "backdrop_path" in data && typeof data.backdrop_path === "string";
+}
+function hasProfilePath(data) {
+  return typeof data === "object" && data !== null && "profile_path" in data && typeof data.profile_path === "string";
+}
+function hasStillPath(data) {
+  return typeof data === "object" && data !== null && "still_path" in data && typeof data.still_path === "string";
+}
+function hasLogoPath(data) {
+  return typeof data === "object" && data !== null && "logo_path" in data && typeof data.logo_path === "string";
+}
+
 // src/client.ts
 var ApiClient = class {
   accessToken;
@@ -139,10 +156,17 @@ var ApiClient = class {
    */
   inflightRequests = /* @__PURE__ */ new Map();
   deduplication;
+  requestInterceptors;
+  onSuccessInterceptor;
+  onErrorInterceptor;
   constructor(accessToken, options = {}) {
     this.accessToken = accessToken;
     this.logger = TMDBLogger.from(options.logger);
     this.deduplication = options.deduplication !== false;
+    const raw = options.interceptors?.request;
+    this.requestInterceptors = raw == null ? [] : Array.isArray(raw) ? raw : [raw];
+    this.onSuccessInterceptor = options.interceptors?.response?.onSuccess;
+    this.onErrorInterceptor = options.interceptors?.response?.onError;
   }
   /**
    * Builds a stable, order-independent cache key for a request.
@@ -152,9 +176,19 @@ var ApiClient = class {
    * `{ language, page }` and `{ page, language }` produce the same key.
    */
   buildRequestKey(endpoint, params) {
-    const definedEntries = Object.entries(params).filter(([, v]) => v !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}=${String(v)}`);
+    const definedEntries = this.serializeParams(params).sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => `${key}=${value}`);
     return definedEntries.length > 0 ? `${endpoint}?${definedEntries.join("&")}` : endpoint;
   }
+  /**
+   * Serializes request params once so URL construction and deduplication keys stay aligned.
+   * `undefined` values are intentionally skipped because they are not sent to TMDB.
+   */
+  serializeParams(params) {
+    return Object.entries(params).flatMap(([key, value]) => {
+      if (value === void 0) return [];
+      return [[key, String(value)]];
+    });
+  }
   /**
    * Makes an authenticated GET request to the TMDB API, returning the parsed and
    * null-sanitised response.
@@ -177,17 +211,31 @@ var ApiClient = class {
     this.inflightRequests.set(key, promise);
     return promise;
   }
+  /**
+   * 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.
+   */
+  async runRequestInterceptors(context) {
+    let current = context;
+    for (const interceptor of this.requestInterceptors) {
+      const result = await interceptor(current);
+      if (result != null) current = result;
+    }
+    return current;
+  }
   /**
    * The actual fetch + response-parsing pipeline. Called by `request()` only when no
    * matching in-flight promise exists. Handles URL construction, auth headers, logging,
    * error mapping, and null sanitisation.
    */
   async doRequest(endpoint, params) {
+    const ctx = await this.runRequestInterceptors({ endpoint, params, method: "GET" });
+    endpoint = ctx.endpoint;
+    params = ctx.params;
     const url = new URL(`${this.baseUrl}${endpoint}`);
     const jwt = isJwt(this.accessToken);
-    for (const [key, value] of Object.entries(params)) {
-      if (value === void 0) continue;
-      url.searchParams.append(key, String(value));
+    for (const [key, value] of this.serializeParams(params)) {
+      url.searchParams.append(key, value);
     }
     if (!jwt) {
       url.searchParams.append("api_key", this.accessToken);
@@ -218,7 +266,12 @@ var ApiClient = class {
       });
       throw error;
     }
-    if (!res.ok) await this.handleError(res, endpoint);
+    if (!res.ok) {
+      await this.handleError(res, endpoint).catch(async (err) => {
+        if (this.onErrorInterceptor) await this.onErrorInterceptor(err);
+        throw err;
+      });
+    }
     this.logger?.log({
       type: "response",
       method: "GET",
@@ -228,7 +281,12 @@ var ApiClient = class {
       durationMs: Date.now() - startedAt
     });
     const data = await res.json();
-    return this.sanitizeNulls(data);
+    const sanitized = this.sanitizeNulls(data);
+    if (this.onSuccessInterceptor) {
+      const result = await this.onSuccessInterceptor(sanitized);
+      return result !== void 0 ? result : sanitized;
+    }
+    return sanitized;
   }
   /**
    * Recursively converts null values to undefined in API responses.
@@ -554,7 +612,7 @@ var CompaniesAPI = class extends TMDBAPIBase {
    */
   async details(params) {
     const endpoint = this.companyPath(params.company_id);
-    return this.client.request(endpoint, params);
+    return this.client.request(endpoint);
   }
   /**
    * Alternative names
@@ -567,7 +625,7 @@ var CompaniesAPI = class extends TMDBAPIBase {
    */
   async alternative_names(params) {
     const endpoint = `${this.companyPath(params.company_id)}${ENDPOINTS.COMPANIES.ALTERNATIVE_NAMES}`;
-    return this.client.request(endpoint, params);
+    return this.client.request(endpoint);
   }
   /**
    * Images
@@ -581,9 +639,9 @@ var CompaniesAPI = class extends TMDBAPIBase {
    * @reference https://developer.themoviedb.org/reference/company-images
    */
   async images(params) {
-    const endpoint = `${this.companyPath(params.company_id)}${ENDPOINTS.COMPANIES.IMAGES}`;
-    const requestParams = this.withLanguage(params) ?? params;
-    return this.client.request(endpoint, requestParams);
+    const { company_id, ...rest } = params;
+    const endpoint = `${this.companyPath(company_id)}${ENDPOINTS.COMPANIES.IMAGES}`;
+    return this.client.request(endpoint, this.withLanguage(rest));
   }
 };
 
@@ -603,9 +661,9 @@ var CreditsAPI = class extends TMDBAPIBase {
    * @reference https://developer.themoviedb.org/reference/credit-details
    */
   async details(params) {
-    const endpoint = this.creditPath(params.credit_id);
-    const requestParams = this.withLanguage(params) ?? params;
-    return this.client.request(endpoint, requestParams);
+    const { credit_id, ...rest } = params;
+    const endpoint = this.creditPath(credit_id);
+    return this.client.request(endpoint, this.withLanguage(rest));
   }
 };
 
@@ -625,9 +683,9 @@ var CollectionsAPI = class extends TMDBAPIBase {
    * @reference https://developer.themoviedb.org/reference/collection-details
    */
   async details(params) {
-    const { language = this.defaultOptions.language, ...rest } = params;
-    const endpoint = this.collectionPath(params.collection_id);
-    return this.client.request(endpoint, { language, ...rest });
+    const { language = this.defaultOptions.language, collection_id } = params;
+    const endpoint = this.collectionPath(collection_id);
+    return this.client.request(endpoint, { language });
   }
   /**
    * Images
@@ -642,9 +700,9 @@ var CollectionsAPI = class extends TMDBAPIBase {
    * @reference https://developer.themoviedb.org/reference/collection-images
    */
   async images(params) {
-    const endpoint = `${this.collectionPath(params.collection_id)}${ENDPOINTS.COLLECTIONS.IMAGES}`;
-    const requestParams = this.withLanguage(params) ?? params;
-    return this.client.request(endpoint, requestParams);
+    const { collection_id, ...rest } = params;
+    const endpoint = `${this.collectionPath(collection_id)}${ENDPOINTS.COLLECTIONS.IMAGES}`;
+    return this.client.request(endpoint, this.withLanguage(rest));
   }
   /**
    * Translations
@@ -657,7 +715,7 @@ var CollectionsAPI = class extends TMDBAPIBase {
    */
   async translations(params) {
     const endpoint = `${this.collectionPath(params.collection_id)}${ENDPOINTS.COLLECTIONS.TRANSLATIONS}`;
-    return this.client.request(endpoint, params);
+    return this.client.request(endpoint);
   }
 };
 
@@ -869,7 +927,7 @@ var KeywordsAPI = class extends TMDBAPIBase {
    */
   async details(params) {
     const endpoint = this.keywordPath(params.keyword_id);
-    return this.client.request(endpoint, params);
+    return this.client.request(endpoint);
   }
   /**
    * Movies
@@ -885,8 +943,9 @@ var KeywordsAPI = class extends TMDBAPIBase {
    * @reference https://developer.themoviedb.org/reference/keyword-movies
    */
   async movies(params) {
-    const endpoint = `${this.keywordPath(params.keyword_id)}${ENDPOINTS.KEYWORDS.MOVIES}`;
-    const requestParams = this.withLanguage(params);
+    const { keyword_id, ...rest } = params;
+    const endpoint = `${this.keywordPath(keyword_id)}${ENDPOINTS.KEYWORDS.MOVIES}`;
+    const requestParams = this.withLanguage(rest);
     return this.client.request(endpoint, requestParams);
   }
 };
@@ -976,9 +1035,9 @@ var MoviesAPI = class extends TMDBAPIBase {
    * @reference https://developer.themoviedb.org/reference/movie-details
    */
   async details(params) {
-    const { language = this.defaultOptions.language, ...rest } = params;
-    const endpoint = this.moviePath(params.movie_id);
-    return this.client.request(endpoint, { language, ...rest });
+    const { language = this.defaultOptions.language, movie_id, append_to_response } = params;
+    const endpoint = this.moviePath(movie_id);
+    return this.client.request(endpoint, { language, append_to_response });
   }
   /**
    * Alternative Titles
@@ -991,8 +1050,9 @@ var MoviesAPI = class extends TMDBAPIBase {
    * @reference https://developer.themoviedb.org/reference/movie-alternative-titles
    */
   async alternative_titles(params) {
-    const endpoint = this.movieSubPath(params.movie_id, ENDPOINTS.MOVIES.ALTERNATIVE_TITLES);
-    return this.client.request(endpoint, params);
+    const { movie_id, ...rest } = params;
+    const endpoint = this.movieSubPath(movie_id, ENDPOINTS.MOVIES.ALTERNATIVE_TITLES);
+    return this.client.request(endpoint, rest);
   }
   /**
    * Credits
@@ -1053,8 +1113,9 @@ var MoviesAPI = class extends TMDBAPIBase {
    * @reference https://developer.themoviedb.org/reference/movie-changes
    */
   async changes(params) {
-    const endpoint = this.movieSubPath(params.movie_id, ENDPOINTS.MOVIES.CHANGES);
-    return this.client.request(endpoint, params);
+    const { movie_id, ...rest } = params;
+    const endpoint = this.movieSubPath(movie_id, ENDPOINTS.MOVIES.CHANGES);
+    return this.client.request(endpoint, rest);
   }
   /**
    * Images
@@ -1793,7 +1854,7 @@ var NetworksAPI = class extends TMDBAPIBase {
    */
   async details(params) {
     const endpoint = this.networkPath(params.network_id);
-    return this.client.request(endpoint, params);
+    return this.client.request(endpoint);
   }
   /**
    * Alternative names
@@ -1806,7 +1867,7 @@ var NetworksAPI = class extends TMDBAPIBase {
    */
   async alternative_names(params) {
     const endpoint = `${this.networkPath(params.network_id)}${ENDPOINTS.NETWORKS.ALTERNATIVE_NAMES}`;
-    return this.client.request(endpoint, params);
+    return this.client.request(endpoint);
   }
   /**
    * Images
@@ -1869,8 +1930,8 @@ var TVEpisodesAPI = class extends TMDBAPIBase {
    * @reference https://developer.themoviedb.org/reference/tv-episode-changes-by-id
    */
   async changes(params) {
-    const endpoint = `${ENDPOINTS.TV_SERIES.DETAILS}/${ENDPOINTS.TV_EPISODES.DETAILS}/${params.episode_id}/${ENDPOINTS.TV_EPISODES.CHANGES}`;
-    return this.client.request(endpoint, { ...params });
+    const endpoint = `${ENDPOINTS.TV_SERIES.DETAILS}${ENDPOINTS.TV_EPISODES.DETAILS}/${params.episode_id}${ENDPOINTS.TV_EPISODES.CHANGES}`;
+    return this.client.request(endpoint);
   }
   /**
    * Credits
@@ -2215,10 +2276,7 @@ var PeopleListsAPI = class extends TMDBAPIBase {
    * @reference https://developer.themoviedb.org/reference/person-popular-list
    */
   async popular(params = {}) {
-    return this.client.request(
-      ENDPOINTS.PEOPLE_LISTS.POPULAR,
-      this.withLanguage(params) ?? params
-    );
+    return this.client.request(ENDPOINTS.PEOPLE_LISTS.POPULAR, this.withLanguage(params));
   }
 };
 
@@ -2389,7 +2447,11 @@ var TMDB = class {
   constructor(accessToken, options = {}) {
     if (!accessToken) throw new Error(Errors.NO_ACCESS_TOKEN);
     this.options = options;
-    this.client = new ApiClient(accessToken, { logger: options.logger, deduplication: options.deduplication });
+    this.client = new ApiClient(accessToken, {
+      logger: options.logger,
+      deduplication: options.deduplication,
+      interceptors: options.interceptors
+    });
     this.movies = new MoviesAPI(this.client, this.options);
     this.movie_lists = new MovieListsAPI(this.client, this.options);
     this.search = new SearchAPI(this.client, this.options);
@@ -3718,4 +3780,4 @@ var TVEpisodeGroupType = /* @__PURE__ */ ((TVEpisodeGroupType2) => {
   return TVEpisodeGroupType2;
 })(TVEpisodeGroupType || {});
 
-export { BACKDROP_SIZES, DiscoverTVStatus, DiscoverTVType, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, LOGO_SIZES, POSTER_SIZES, PROFILE_SIZES, STILL_SIZES, TMDB, TMDBCountries, TMDBError, TMDBLogger, TVEpisodeGroupType, isJwt, isKnownForMovie, isKnownForTV };
+export { BACKDROP_SIZES, DiscoverTVStatus, DiscoverTVType, IMAGE_BASE_URL, IMAGE_SECURE_BASE_URL, LOGO_SIZES, POSTER_SIZES, PROFILE_SIZES, STILL_SIZES, TMDB, TMDBCountries, TMDBError, TMDBLogger, TVEpisodeGroupType, hasBackdropPath, hasLogoPath, hasPosterPath, hasProfilePath, hasStillPath, isJwt, isKnownForMovie, isKnownForTV };

package/package.json

@@ -1,25 +1,44 @@
 {
 	"name": "@lorenzopant/tmdb",
-	"version": "1.17.2",
+	"version": "1.17.4",
 	"type": "module",
 	"description": "A completely type-safe The Movie Database (TMDB) API wrapper for typescript applications.",
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
-	"files": [
-		"dist",
-		"README.md"
+	"keywords": [
+		"api",
+		"movies",
+		"tmdb",
+		"typescript"
 	],
+	"homepage": "https://lorenzopant-tmdb-docs.vercel.app",
+	"bugs": {
+		"url": "https://github.com/lorenzopant/tmdb/issues"
+	},
+	"license": "MIT",
+	"author": "Lorenzo Pantano",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/lorenzopant/tmdb"
 	},
-	"homepage": "https://lorenzopant-tmdb-docs.vercel.app",
-	"bugs": {
-		"url": "https://github.com/lorenzopant/tmdb/issues"
+	"files": [
+		"dist",
+		"README.md"
+	],
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		},
+		"./types": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
 	},
 	"scripts": {
 		"build": "tsup",
 		"dev": "tsup --watch",
+		"format": "oxfmt .",
 		"typecheck": "tsc --noEmit",
 		"test": "vitest",
 		"test:unit": "vitest run --exclude '**/*.integration.test.ts'",
@@ -27,34 +46,18 @@
 		"test:ui": "vitest --ui",
 		"test:coverage": "vitest --coverage",
 		"prepare": "husky",
-		"lint": "eslint .",
+		"lint": "oxlint .",
+		"lint:check": "oxlint --type-aware --type-check .",
 		"release": "pnpm release:patch",
 		"release:patch": "pnpm version patch --git-tag-version && git push --follow-tags",
 		"release:minor": "pnpm version minor --git-tag-version && git push --follow-tags",
 		"release:major": "pnpm version major --git-tag-version && git push --follow-tags"
 	},
-	"author": "Lorenzo Pantano",
-	"license": "MIT",
-	"keywords": [
-		"tmdb",
-		"typescript",
-		"api",
-		"movies"
-	],
-	"packageManager": "pnpm@8.8.0",
 	"devDependencies": {
-		"@eslint/compat": "^2.0.0",
-		"@eslint/eslintrc": "^3.3.1",
-		"@eslint/js": "^9.30.0",
 		"@types/node": "^22.19.11",
-		"@typescript-eslint/eslint-plugin": "^8.35.0",
-		"@typescript-eslint/parser": "^8.35.0",
 		"@vitest/coverage-v8": "^4.0.9",
 		"@vitest/ui": "^4.0.10",
 		"dotenv": "^16.5.0",
-		"eslint": "^9.30.0",
-		"eslint-config-prettier": "^10.1.5",
-		"eslint-plugin-import": "^2.32.0",
 		"husky": "^9.1.7",
 		"release-it": "^19.0.3",
 		"release-it-pnpm": "^4.6.6",
@@ -62,23 +65,13 @@
 		"tsup": "^8.5.1",
 		"tsx": "^4.21.0",
 		"typescript": "^5.8.3",
-		"typescript-eslint": "^8.35.0",
 		"vite": "^7.0.0",
 		"vitest": "^4.0.9"
 	},
+	"packageManager": "pnpm@8.8.0",
 	"pnpm": {
 		"overrides": {
 			"basic-ftp": "5.2.0"
 		}
-	},
-	"exports": {
-		".": {
-			"import": "./dist/index.js",
-			"types": "./dist/index.d.ts"
-		},
-		"./types": {
-			"import": "./dist/index.js",
-			"types": "./dist/index.d.ts"
-		}
 	}
 }