@lorenzopant/tmdb 1.15.1 → 1.17.0

package/dist/client.js

@@ -1,5 +1,6 @@
 import { TMDBError } from "./errors/tmdb";
 import { TMDBLogger } from "./utils/logger";
+import { isJwt } from "./utils";
 export class ApiClient {
     accessToken;
     baseUrl = "https://api.themoviedb.org/3";
@@ -10,11 +11,15 @@ export class ApiClient {
     }
     async request(endpoint, params = {}) {
         const url = new URL(`${this.baseUrl}${endpoint}`);
+        const jwt = isJwt(this.accessToken);
         for (const [key, value] of Object.entries(params)) {
             if (value === undefined)
                 continue;
             url.searchParams.append(key, String(value));
         }
+        if (!jwt) {
+            url.searchParams.append("api_key", this.accessToken);
+        }
         const startedAt = Date.now();
         this.logger?.log({
             type: "request",
@@ -24,10 +29,14 @@ export class ApiClient {
         let res;
         try {
             res = await fetch(url.toString(), {
-                headers: {
-                    Authorization: `Bearer ${this.accessToken}`,
-                    "Content-Type": "application/json;charset=utf-8",
-                },
+                headers: jwt
+                    ? {
+                        Authorization: `Bearer ${this.accessToken}`,
+                        "Content-Type": "application/json;charset=utf-8",
+                    }
+                    : {
+                        "Content-Type": "application/json;charset=utf-8",
+                    },
             });
         }
         catch (error) {

package/dist/endpoints/base.d.ts

@@ -14,6 +14,7 @@ export declare abstract class TMDBAPIBase {
     /**
      * Ensures params contains a language: prefer explicit param, fallback to defaultOptions.language.
      * If neither is present, returns the original params unmodified.
+     * When params is undefined but a default language is set, returns { language: defaultLang }.
      */
     protected withLanguage<T extends {
         language?: Language;

package/dist/endpoints/base.js

@@ -17,13 +17,14 @@ export class TMDBAPIBase {
     /**
      * Ensures params contains a language: prefer explicit param, fallback to defaultOptions.language.
      * If neither is present, returns the original params unmodified.
+     * When params is undefined but a default language is set, returns { language: defaultLang }.
      */
     withLanguage(params) {
+        const defaultLang = this.defaultOptions?.language;
         if (!params)
-            return undefined; // Handle undefined params
+            return defaultLang !== undefined ? { language: defaultLang } : undefined;
         if (params.language !== undefined)
             return params;
-        const defaultLang = this.defaultOptions?.language;
         if (defaultLang === undefined)
             return params;
         return { ...params, language: defaultLang };

package/dist/endpoints/people.d.ts

@@ -0,0 +1,91 @@
+import { TMDBAPIBase } from "./base";
+import type { PersonAppendToResponseNamespace, PersonChanges, PersonChangesParams, PersonCombinedCredits, PersonCreditsParams, PersonDetails, PersonDetailsParams, PersonDetailsWithAppends, PersonExternalIDs, PersonExternalIDsParams, PersonImages, PersonImagesParams, PersonMovieCredits, PersonTaggedImages, PersonTaggedImagesParams, PersonTranslations, PersonTranslationsParams, PersonTVCredits } from "../types/people";
+export declare class PeopleAPI extends TMDBAPIBase {
+    private personPath;
+    private personSubPath;
+    /**
+     * Details
+     * GET - https://api.themoviedb.org/3/person/{person_id}
+     *
+     * Get the primary person details by TMDB person id.
+     * @param person_id The TMDB person id.
+     * @param append_to_response Additional person subresources to append.
+     * @param language Language for localized results.
+     * @reference https://developer.themoviedb.org/reference/person-details
+     */
+    details<T extends readonly PersonAppendToResponseNamespace[] = []>(params: PersonDetailsParams & {
+        append_to_response?: T[number] | T;
+    }): Promise<T extends [] ? PersonDetails : PersonDetailsWithAppends<T>>;
+    /**
+     * Changes
+     * GET - https://api.themoviedb.org/3/person/{person_id}/changes
+     *
+     * Get the change history for a person.
+     * @reference https://developer.themoviedb.org/reference/person-changes
+     */
+    changes(params: PersonChangesParams): Promise<PersonChanges>;
+    /**
+     * Combined Credits
+     * GET - https://api.themoviedb.org/3/person/{person_id}/combined_credits
+     *
+     * Get movie and TV credits in a single response.
+     * @reference https://developer.themoviedb.org/reference/person-combined-credits
+     */
+    combined_credits(params: PersonCreditsParams): Promise<PersonCombinedCredits>;
+    /**
+     * External IDs
+     * GET - https://api.themoviedb.org/3/person/{person_id}/external_ids
+     *
+     * Get external platform identifiers for a person.
+     * @reference https://developer.themoviedb.org/reference/person-external-ids
+     */
+    external_ids(params: PersonExternalIDsParams): Promise<PersonExternalIDs>;
+    /**
+     * Images
+     * GET - https://api.themoviedb.org/3/person/{person_id}/images
+     *
+     * Get profile images for a person.
+     * @reference https://developer.themoviedb.org/reference/person-images
+     */
+    images(params: PersonImagesParams): Promise<PersonImages>;
+    /**
+     * Latest
+     * GET - https://api.themoviedb.org/3/person/latest
+     *
+     * Get the newest person id added to TMDB.
+     * @reference https://developer.themoviedb.org/reference/person-latest-id
+     */
+    latest(): Promise<PersonDetails>;
+    /**
+     * Movie Credits
+     * GET - https://api.themoviedb.org/3/person/{person_id}/movie_credits
+     *
+     * Get a person's movie cast and crew credits.
+     * @reference https://developer.themoviedb.org/reference/person-movie-credits
+     */
+    movie_credits(params: PersonCreditsParams): Promise<PersonMovieCredits>;
+    /**
+     * Tagged Images
+     * GET - https://api.themoviedb.org/3/person/{person_id}/tagged_images
+     *
+     * Get images where the person has been tagged.
+     * @reference https://developer.themoviedb.org/reference/person-tagged-images
+     */
+    tagged_images(params: PersonTaggedImagesParams): Promise<PersonTaggedImages>;
+    /**
+     * Translations
+     * GET - https://api.themoviedb.org/3/person/{person_id}/translations
+     *
+     * Get the translations available for a person biography and name.
+     * @reference https://developer.themoviedb.org/reference/person-translations
+     */
+    translations(params: PersonTranslationsParams): Promise<PersonTranslations>;
+    /**
+     * TV Credits
+     * GET - https://api.themoviedb.org/3/person/{person_id}/tv_credits
+     *
+     * Get a person's TV cast and crew credits.
+     * @reference https://developer.themoviedb.org/reference/person-tv-credits
+     */
+    tv_credits(params: PersonCreditsParams): Promise<PersonTVCredits>;
+}

package/dist/endpoints/people.js

@@ -0,0 +1,128 @@
+import { ENDPOINTS } from "../routes";
+import { TMDBAPIBase } from "./base";
+export class PeopleAPI extends TMDBAPIBase {
+    personPath(person_id) {
+        return `${ENDPOINTS.PEOPLE.DETAILS}/${person_id}`;
+    }
+    personSubPath(person_id, route) {
+        return `${this.personPath(person_id)}${route}`;
+    }
+    /**
+     * Details
+     * GET - https://api.themoviedb.org/3/person/{person_id}
+     *
+     * Get the primary person details by TMDB person id.
+     * @param person_id The TMDB person id.
+     * @param append_to_response Additional person subresources to append.
+     * @param language Language for localized results.
+     * @reference https://developer.themoviedb.org/reference/person-details
+     */
+    async details(params) {
+        const { language = this.defaultOptions.language, person_id, ...rest } = params;
+        return this.client.request(this.personPath(person_id), { language, ...rest });
+    }
+    /**
+     * Changes
+     * GET - https://api.themoviedb.org/3/person/{person_id}/changes
+     *
+     * Get the change history for a person.
+     * @reference https://developer.themoviedb.org/reference/person-changes
+     */
+    async changes(params) {
+        const { person_id, ...rest } = params;
+        return this.client.request(this.personSubPath(person_id, ENDPOINTS.PEOPLE.CHANGES), rest);
+    }
+    /**
+     * Combined Credits
+     * GET - https://api.themoviedb.org/3/person/{person_id}/combined_credits
+     *
+     * Get movie and TV credits in a single response.
+     * @reference https://developer.themoviedb.org/reference/person-combined-credits
+     */
+    async combined_credits(params) {
+        const { language = this.defaultOptions.language, person_id, ...rest } = params;
+        return this.client.request(this.personSubPath(person_id, ENDPOINTS.PEOPLE.COMBINED_CREDITS), {
+            language,
+            ...rest,
+        });
+    }
+    /**
+     * External IDs
+     * GET - https://api.themoviedb.org/3/person/{person_id}/external_ids
+     *
+     * Get external platform identifiers for a person.
+     * @reference https://developer.themoviedb.org/reference/person-external-ids
+     */
+    async external_ids(params) {
+        return this.client.request(this.personSubPath(params.person_id, ENDPOINTS.PEOPLE.EXTERNAL_IDS));
+    }
+    /**
+     * Images
+     * GET - https://api.themoviedb.org/3/person/{person_id}/images
+     *
+     * Get profile images for a person.
+     * @reference https://developer.themoviedb.org/reference/person-images
+     */
+    async images(params) {
+        return this.client.request(this.personSubPath(params.person_id, ENDPOINTS.PEOPLE.IMAGES));
+    }
+    /**
+     * Latest
+     * GET - https://api.themoviedb.org/3/person/latest
+     *
+     * Get the newest person id added to TMDB.
+     * @reference https://developer.themoviedb.org/reference/person-latest-id
+     */
+    async latest() {
+        return this.client.request(`${ENDPOINTS.PEOPLE.DETAILS}${ENDPOINTS.PEOPLE.LATEST}`);
+    }
+    /**
+     * Movie Credits
+     * GET - https://api.themoviedb.org/3/person/{person_id}/movie_credits
+     *
+     * Get a person's movie cast and crew credits.
+     * @reference https://developer.themoviedb.org/reference/person-movie-credits
+     */
+    async movie_credits(params) {
+        const { language = this.defaultOptions.language, person_id, ...rest } = params;
+        return this.client.request(this.personSubPath(person_id, ENDPOINTS.PEOPLE.MOVIE_CREDITS), {
+            language,
+            ...rest,
+        });
+    }
+    /**
+     * Tagged Images
+     * GET - https://api.themoviedb.org/3/person/{person_id}/tagged_images
+     *
+     * Get images where the person has been tagged.
+     * @reference https://developer.themoviedb.org/reference/person-tagged-images
+     */
+    async tagged_images(params) {
+        const { person_id, ...rest } = params;
+        return this.client.request(this.personSubPath(person_id, ENDPOINTS.PEOPLE.TAGGED_IMAGES), rest);
+    }
+    /**
+     * Translations
+     * GET - https://api.themoviedb.org/3/person/{person_id}/translations
+     *
+     * Get the translations available for a person biography and name.
+     * @reference https://developer.themoviedb.org/reference/person-translations
+     */
+    async translations(params) {
+        return this.client.request(this.personSubPath(params.person_id, ENDPOINTS.PEOPLE.TRANSLATIONS));
+    }
+    /**
+     * TV Credits
+     * GET - https://api.themoviedb.org/3/person/{person_id}/tv_credits
+     *
+     * Get a person's TV cast and crew credits.
+     * @reference https://developer.themoviedb.org/reference/person-tv-credits
+     */
+    async tv_credits(params) {
+        const { language = this.defaultOptions.language, person_id, ...rest } = params;
+        return this.client.request(this.personSubPath(person_id, ENDPOINTS.PEOPLE.TV_CREDITS), {
+            language,
+            ...rest,
+        });
+    }
+}

package/dist/endpoints/people_lists.d.ts

@@ -0,0 +1,16 @@
+import type { PaginatedResponse } from "../types";
+import type { PersonResultItem } from "../types/search";
+import type { PeopleListParams } from "../types/people-lists";
+import { TMDBAPIBase } from "./base";
+export declare class PeopleListsAPI extends TMDBAPIBase {
+    /**
+     * Popular
+     * GET - https://api.themoviedb.org/3/person/popular
+     *
+     * Get a list of people ordered by popularity.
+     * @param language Language for localised results (Defaults to en-US or TMDB default)
+     * @param page Page number (Defaults to 1)
+     * @reference https://developer.themoviedb.org/reference/person-popular-list
+     */
+    popular(params?: PeopleListParams): Promise<PaginatedResponse<PersonResultItem>>;
+}

package/dist/endpoints/people_lists.js

@@ -0,0 +1,16 @@
+import { ENDPOINTS } from "../routes";
+import { TMDBAPIBase } from "./base";
+export class PeopleListsAPI extends TMDBAPIBase {
+    /**
+     * Popular
+     * GET - https://api.themoviedb.org/3/person/popular
+     *
+     * Get a list of people ordered by popularity.
+     * @param language Language for localised results (Defaults to en-US or TMDB default)
+     * @param page Page number (Defaults to 1)
+     * @reference https://developer.themoviedb.org/reference/person-popular-list
+     */
+    async popular(params = {}) {
+        return this.client.request(ENDPOINTS.PEOPLE_LISTS.POPULAR, this.withLanguage(params) ?? params);
+    }
+}

package/dist/endpoints/reviews.d.ts

@@ -0,0 +1,14 @@
+import type { ReviewDetails, ReviewDetailsParams } from "../types/reviews";
+import { TMDBAPIBase } from "./base";
+export declare class ReviewsAPI extends TMDBAPIBase {
+    /**
+     * Details
+     * GET - https://api.themoviedb.org/3/review/{review_id}
+     *
+     * Retrieve the details of a single review by its TMDB review ID.
+     * @param review_id The TMDB review identifier.
+     * @returns A promise that resolves to the full review details.
+     * @reference https://developer.themoviedb.org/reference/review-details
+     */
+    details(params: ReviewDetailsParams): Promise<ReviewDetails>;
+}

package/dist/endpoints/reviews.js

@@ -0,0 +1,16 @@
+import { ENDPOINTS } from "../routes";
+import { TMDBAPIBase } from "./base";
+export class ReviewsAPI extends TMDBAPIBase {
+    /**
+     * Details
+     * GET - https://api.themoviedb.org/3/review/{review_id}
+     *
+     * Retrieve the details of a single review by its TMDB review ID.
+     * @param review_id The TMDB review identifier.
+     * @returns A promise that resolves to the full review details.
+     * @reference https://developer.themoviedb.org/reference/review-details
+     */
+    async details(params) {
+        return this.client.request(`${ENDPOINTS.REVIEWS.DETAILS}/${params.review_id}`);
+    }
+}

package/dist/endpoints/tv_series.js

@@ -19,8 +19,8 @@ export class TVSeriesAPI extends TMDBAPIBase {
      * @reference https://developer.themoviedb.org/reference/tv-series-details
      */
     async details(params) {
-        const { language = this.defaultOptions.language, ...rest } = params;
-        const endpoint = this.seriesPath(params.series_id);
+        const { language = this.defaultOptions.language, series_id, ...rest } = params;
+        const endpoint = this.seriesPath(series_id);
         return this.client.request(endpoint, { language, ...rest });
     }
     /**
@@ -37,8 +37,8 @@ export class TVSeriesAPI extends TMDBAPIBase {
      * @reference https://developer.themoviedb.org/reference/tv-series-aggregate-credits
      */
     async aggregate_credits(params) {
-        const { language = this.defaultOptions.language, ...rest } = params;
-        const endpoint = this.seriesSubPath(params.series_id, ENDPOINTS.TV_SERIES.AGGREGATE_CREDITS);
+        const { language = this.defaultOptions.language, series_id, ...rest } = params;
+        const endpoint = this.seriesSubPath(series_id, ENDPOINTS.TV_SERIES.AGGREGATE_CREDITS);
         return this.client.request(endpoint, { language, ...rest });
     }
     /**
@@ -72,8 +72,9 @@ export class TVSeriesAPI extends TMDBAPIBase {
      * @reference https://developer.themoviedb.org/reference/tv-series-changes
      */
     async changes(params) {
-        const endpoint = this.seriesSubPath(params.series_id, ENDPOINTS.TV_SERIES.CHANGES);
-        return this.client.request(endpoint, { ...params });
+        const { series_id, ...rest } = params;
+        const endpoint = this.seriesSubPath(series_id, ENDPOINTS.TV_SERIES.CHANGES);
+        return this.client.request(endpoint, { ...rest });
     }
     /**
      * Content Ratings
@@ -103,8 +104,8 @@ export class TVSeriesAPI extends TMDBAPIBase {
      * @reference https://developer.themoviedb.org/reference/tv-series-credits
      */
     async credits(params) {
-        const endpoint = this.seriesSubPath(params.series_id, ENDPOINTS.TV_SERIES.CREDITS);
-        const { language = this.defaultOptions.language, ...rest } = params;
+        const { language = this.defaultOptions.language, series_id, ...rest } = params;
+        const endpoint = this.seriesSubPath(series_id, ENDPOINTS.TV_SERIES.CREDITS);
         return this.client.request(endpoint, { language, ...rest });
     }
     /**
@@ -150,8 +151,8 @@ export class TVSeriesAPI extends TMDBAPIBase {
      * @reference https://developer.themoviedb.org/reference/tv-series-images
      */
     async images(params) {
-        const { language = this.defaultOptions.language, ...rest } = params;
-        const endpoint = this.seriesSubPath(params.series_id, ENDPOINTS.TV_SERIES.IMAGES);
+        const { language = this.defaultOptions.language, series_id, ...rest } = params;
+        const endpoint = this.seriesSubPath(series_id, ENDPOINTS.TV_SERIES.IMAGES);
         return this.client.request(endpoint, { language, ...rest });
     }
     /**
@@ -192,8 +193,8 @@ export class TVSeriesAPI extends TMDBAPIBase {
      * @reference https://developer.themoviedb.org/reference/lists-copy (TODO: Check this url for updates, it's like this on TMDB docs (??))
      */
     async lists(params) {
-        const endpoint = this.seriesSubPath(params.series_id, ENDPOINTS.TV_SERIES.LISTS);
-        const { language = this.defaultOptions.language, ...rest } = params;
+        const { language = this.defaultOptions.language, series_id, ...rest } = params;
+        const endpoint = this.seriesSubPath(series_id, ENDPOINTS.TV_SERIES.LISTS);
         return this.client.request(endpoint, { language, ...rest });
     }
     /**
@@ -208,8 +209,8 @@ export class TVSeriesAPI extends TMDBAPIBase {
      * @reference https://developer.themoviedb.org/reference/tv-series-recommendations
      */
     async recommendations(params) {
-        const endpoint = this.seriesSubPath(params.series_id, ENDPOINTS.TV_SERIES.RECOMMENDATIONS);
-        const { language = this.defaultOptions.language, ...rest } = params;
+        const { language = this.defaultOptions.language, series_id, ...rest } = params;
+        const endpoint = this.seriesSubPath(series_id, ENDPOINTS.TV_SERIES.RECOMMENDATIONS);
         return this.client.request(endpoint, { language, ...rest });
     }
     /**
@@ -224,8 +225,8 @@ export class TVSeriesAPI extends TMDBAPIBase {
      * @reference https://developer.themoviedb.org/reference/tv-series-recommendations
      */
     async reviews(params) {
-        const endpoint = this.seriesSubPath(params.series_id, ENDPOINTS.TV_SERIES.REVIEWS);
-        const { language = this.defaultOptions.language, ...rest } = params;
+        const { language = this.defaultOptions.language, series_id, ...rest } = params;
+        const endpoint = this.seriesSubPath(series_id, ENDPOINTS.TV_SERIES.REVIEWS);
         return this.client.request(endpoint, { language, ...rest });
     }
     /**
@@ -253,8 +254,8 @@ export class TVSeriesAPI extends TMDBAPIBase {
      * @reference https://developer.themoviedb.org/reference/tv-series-similar
      */
     async similar(params) {
-        const endpoint = this.seriesSubPath(params.series_id, ENDPOINTS.TV_SERIES.SIMILAR);
-        const { language = this.defaultOptions.language, ...rest } = params;
+        const { language = this.defaultOptions.language, series_id, ...rest } = params;
+        const endpoint = this.seriesSubPath(series_id, ENDPOINTS.TV_SERIES.SIMILAR);
         return this.client.request(endpoint, { language, ...rest });
     }
     /**

package/dist/routes.d.ts

@@ -68,6 +68,18 @@ export declare const ENDPOINTS: {
         ALTERNATIVE_NAMES: string;
         IMAGES: string;
     };
+    PEOPLE: {
+        DETAILS: string;
+        CHANGES: string;
+        COMBINED_CREDITS: string;
+        EXTERNAL_IDS: string;
+        IMAGES: string;
+        LATEST: string;
+        MOVIE_CREDITS: string;
+        TAGGED_IMAGES: string;
+        TRANSLATIONS: string;
+        TV_CREDITS: string;
+    };
     SEARCH: {
         MOVIE: string;
         COLLECTION: string;
@@ -136,4 +148,10 @@ export declare const ENDPOINTS: {
         TV: string;
         PERSON: string;
     };
+    REVIEWS: {
+        DETAILS: string;
+    };
+    PEOPLE_LISTS: {
+        POPULAR: string;
+    };
 };

package/dist/routes.js

@@ -68,6 +68,18 @@ export const ENDPOINTS = {
         ALTERNATIVE_NAMES: "/alternative_names",
         IMAGES: "/images",
     },
+    PEOPLE: {
+        DETAILS: "/person",
+        CHANGES: "/changes",
+        COMBINED_CREDITS: "/combined_credits",
+        EXTERNAL_IDS: "/external_ids",
+        IMAGES: "/images",
+        LATEST: "/latest",
+        MOVIE_CREDITS: "/movie_credits",
+        TAGGED_IMAGES: "/tagged_images",
+        TRANSLATIONS: "/translations",
+        TV_CREDITS: "/tv_credits",
+    },
     SEARCH: {
         MOVIE: "/search/movie",
         COLLECTION: "/search/collection",
@@ -136,4 +148,10 @@ export const ENDPOINTS = {
         TV: "/trending/tv",
         PERSON: "/trending/person",
     },
+    REVIEWS: {
+        DETAILS: "/review",
+    },
+    PEOPLE_LISTS: {
+        POPULAR: "/person/popular",
+    },
 };

package/dist/tmdb.d.ts

@@ -21,6 +21,9 @@ import { TVEpisodesAPI } from "./endpoints/tv_episodes";
 import { TVEpisodeGroupsAPI } from "./endpoints/tv_episode_groups";
 import { TVSeasonsAPI } from "./endpoints/tv_seasons";
 import { TrendingAPI } from "./endpoints/trending";
+import { ReviewsAPI } from "./endpoints/reviews";
+import { PeopleListsAPI } from "./endpoints/people_lists";
+import { PeopleAPI } from "./endpoints/people";
 export declare class TMDB {
     private client;
     private options;
@@ -46,6 +49,9 @@ export declare class TMDB {
     tv_episode_groups: TVEpisodeGroupsAPI;
     tv_seasons: TVSeasonsAPI;
     trending: TrendingAPI;
+    reviews: ReviewsAPI;
+    people_lists: PeopleListsAPI;
+    people: PeopleAPI;
     /**
      * Creates a new TMDB instance.
      * @param accessToken The TMDB API access token.

package/dist/tmdb.js

@@ -23,6 +23,9 @@ import { TVEpisodesAPI } from "./endpoints/tv_episodes";
 import { TVEpisodeGroupsAPI } from "./endpoints/tv_episode_groups";
 import { TVSeasonsAPI } from "./endpoints/tv_seasons";
 import { TrendingAPI } from "./endpoints/trending";
+import { ReviewsAPI } from "./endpoints/reviews";
+import { PeopleListsAPI } from "./endpoints/people_lists";
+import { PeopleAPI } from "./endpoints/people";
 export class TMDB {
     client;
     options; // ** Default options for all requests
@@ -48,6 +51,9 @@ export class TMDB {
     tv_episode_groups;
     tv_seasons;
     trending;
+    reviews;
+    people_lists;
+    people;
     // etc...
     /**
      * Creates a new TMDB instance.
@@ -81,5 +87,8 @@ export class TMDB {
         this.tv_episode_groups = new TVEpisodeGroupsAPI(this.client, this.options);
         this.tv_seasons = new TVSeasonsAPI(this.client, this.options);
         this.trending = new TrendingAPI(this.client, this.options);
+        this.reviews = new ReviewsAPI(this.client, this.options);
+        this.people_lists = new PeopleListsAPI(this.client, this.options);
+        this.people = new PeopleAPI(this.client, this.options);
     }
 }

package/dist/types/collections.d.ts

@@ -67,5 +67,6 @@ export type CollectionBaseParam = {
 export type CollectionDetailsParams = CollectionBaseParam & WithLanguage;
 export type CollectionImagesParams = CollectionBaseParam & {
     language?: Language | LanguageISO6391;
-    include_image_language?: Language | LanguageISO6391;
+    /** Languages to include images for. Pass an array — it will be serialized as a comma-separated list (e.g. ["en", "null"]). Use "null" to include untagged images. */
+    include_image_language?: (Language | "null")[];
 };

package/dist/types/companies.d.ts

@@ -1,7 +1,7 @@
 import { AlternativeName, AlternativeNamesResult, WithLanguage } from "./common";
 import { ImagesResult, OrganizationImage } from "./common/images";
 import { CountryISO3166_1 } from "./config/countries";
-import { Language, LanguageISO6391 } from "./config/languages";
+import { Language } from "./config";
 /**
  * Minimal company data reused across company-related responses.
  */
@@ -48,5 +48,6 @@ export type CompanyBaseParam = {
 export type CompanyDetailsParams = CompanyBaseParam;
 export type CompanyAlternativeNamesParams = CompanyBaseParam;
 export type CompanyImagesParams = CompanyBaseParam & {
-    include_image_language?: Language | LanguageISO6391;
+    /** Languages to include images for. Pass an array — it will be serialized as a comma-separated list (e.g. ["en", "null"]). Use "null" to include untagged images. */
+    include_image_language?: (Language | "null")[];
 } & WithLanguage;

package/dist/types/index.d.ts

@@ -16,3 +16,6 @@ export * from "./find";
 export * from "./watch-providers";
 export * from "./keywords";
 export * from "./credits";
+export * from "./reviews";
+export * from "./people-lists";
+export * from "./people";

package/dist/types/index.js

@@ -16,3 +16,6 @@ export * from "./find";
 export * from "./watch-providers";
 export * from "./keywords";
 export * from "./credits";
+export * from "./reviews";
+export * from "./people-lists";
+export * from "./people";

package/dist/types/movies.d.ts

@@ -282,8 +282,8 @@ export type MovieChangesParams = Prettify<MovieBaseParam & WithParams<"page"> &
 export type MovieImagesParams = Prettify<MovieBaseParam & {
     /** Language for image metadata (supports both ISO-639-1 and full Language format) */
     language?: Language | LanguageISO6391;
-    /** Include images with specific language tags (comma-separated, e.g., "en,null") */
-    include_image_language?: Language | LanguageISO6391;
+    /** Languages to include images for. Pass an array — it will be serialized as a comma-separated list (e.g. ["en", "null"]). Use "null" to include untagged images. */
+    include_image_language?: (Language | "null")[];
 }>;
 /**
  * Parameters for fetching movie recommendations.

package/dist/types/people-lists.d.ts

@@ -0,0 +1,5 @@
+import type { WithLanguage, WithPage } from "./common/params";
+/**
+ * Query parameters for the people popular list endpoint.
+ */
+export type PeopleListParams = WithLanguage & WithPage;

package/dist/types/people-lists.js

@@ -0,0 +1 @@
+export {};

package/dist/types/people.d.ts

@@ -0,0 +1,214 @@
+import { Changes, DateRange, ImageItem, ImagesResult, MediaType, PaginatedResponse, TranslationResults, WithLanguage, WithPage } from "./common";
+import { MovieResultItem, TVSeriesResultItem } from "./search";
+import { Prettify } from "./utility";
+/**
+ * Top-level person details returned by TMDB.
+ */
+export type PersonDetails = {
+    /** Whether the person is marked as adult content */
+    adult: boolean;
+    /** Alternative names or aliases */
+    also_known_as: string[];
+    /** Localized or default biography text */
+    biography?: string;
+    /** Date of birth in ISO 8601 format */
+    birthday?: string;
+    /** Date of death in ISO 8601 format, if applicable */
+    deathday?: string;
+    /** Gender code reported by TMDB */
+    gender: number;
+    /** Official homepage URL, if available */
+    homepage?: string;
+    /** TMDB person identifier */
+    id: number;
+    /** IMDb identifier, if linked */
+    imdb_id?: string;
+    /** Primary department the person is known for */
+    known_for_department?: string;
+    /** Display name */
+    name: string;
+    /** Place of birth, if known */
+    place_of_birth?: string;
+    /** Popularity score */
+    popularity: number;
+    /** Relative path to the profile image */
+    profile_path?: string;
+};
+/**
+ * Endpoints that can be appended to a person details request.
+ */
+export type PersonAppendToResponseNamespace = "changes" | "combined_credits" | "external_ids" | "images" | "movie_credits" | "tagged_images" | "translations" | "tv_credits";
+/**
+ * Person details with appended subresources.
+ */
+export type PersonDetailsWithAppends<T extends readonly PersonAppendToResponseNamespace[]> = PersonDetails & {
+    [K in T[number]]: PersonAppendableMap[K];
+};
+/**
+ * Changes made to a person resource.
+ */
+export type PersonChanges = Changes;
+/**
+ * External identifiers linked to a person.
+ */
+export type PersonExternalIDs = {
+    id: number;
+    freebase_mid?: string;
+    freebase_id?: string;
+    imdb_id?: string;
+    tvrage_id?: number;
+    wikidata_id?: string;
+    facebook_id?: string;
+    instagram_id?: string;
+    tiktok_id?: string;
+    twitter_id?: string;
+    youtube_id?: string;
+};
+/**
+ * Profile images belonging to a person.
+ */
+export type PersonImages = ImagesResult<ImageItem, "profiles">;
+/**
+ * Cast credit for a movie on a person profile.
+ */
+export type PersonMovieCastCredit = MovieResultItem & {
+    character: string;
+    credit_id: string;
+    order: number;
+};
+/**
+ * Crew credit for a movie on a person profile.
+ */
+export type PersonMovieCrewCredit = MovieResultItem & {
+    credit_id: string;
+    department: string;
+    job: string;
+};
+/**
+ * Movie credits for a person.
+ */
+export type PersonMovieCredits = {
+    id: number;
+    cast: PersonMovieCastCredit[];
+    crew: PersonMovieCrewCredit[];
+};
+/**
+ * Cast credit for a TV show on a person profile.
+ */
+export type PersonTVCastCredit = TVSeriesResultItem & {
+    character: string;
+    credit_id: string;
+    episode_count: number;
+};
+/**
+ * Crew credit for a TV show on a person profile.
+ */
+export type PersonTVCrewCredit = TVSeriesResultItem & {
+    credit_id: string;
+    department: string;
+    episode_count: number;
+    job: string;
+};
+/**
+ * TV credits for a person.
+ */
+export type PersonTVCredits = {
+    id: number;
+    cast: PersonTVCastCredit[];
+    crew: PersonTVCrewCredit[];
+};
+/**
+ * Combined movie/TV cast credit for a person.
+ */
+export type PersonCombinedCastCredit = (PersonMovieCastCredit & {
+    media_type: "movie";
+}) | (PersonTVCastCredit & {
+    media_type: "tv";
+});
+/**
+ * Combined movie/TV crew credit for a person.
+ */
+export type PersonCombinedCrewCredit = (PersonMovieCrewCredit & {
+    media_type: "movie";
+}) | (PersonTVCrewCredit & {
+    media_type: "tv";
+});
+/**
+ * Combined credits for a person.
+ */
+export type PersonCombinedCredits = {
+    id: number;
+    cast: PersonCombinedCastCredit[];
+    crew: PersonCombinedCrewCredit[];
+};
+/**
+ * Tagged image media payload associated with a person image tag.
+ */
+export type PersonTaggedImageMedia = (MovieResultItem & {
+    media_type: "movie";
+}) | (TVSeriesResultItem & {
+    media_type: "tv";
+});
+/**
+ * A single tagged image entry for a person.
+ */
+export type PersonTaggedImage = ImageItem & {
+    id: string;
+    image_type: string;
+    media: PersonTaggedImageMedia;
+    media_type: MediaType;
+};
+/**
+ * Paginated tagged images for a person.
+ */
+export type PersonTaggedImages = PaginatedResponse<PersonTaggedImage> & {
+    id: number;
+};
+/**
+ * Translation payload for person records.
+ */
+export type PersonTranslationData = {
+    biography?: string;
+    name?: string;
+};
+/**
+ * Available translations for a person.
+ */
+export type PersonTranslations = TranslationResults<PersonTranslationData>;
+/**
+ * Mapping of person append keys to their response types.
+ */
+export type PersonAppendableMap = {
+    changes: PersonChanges;
+    combined_credits: PersonCombinedCredits;
+    external_ids: PersonExternalIDs;
+    images: PersonImages;
+    movie_credits: PersonMovieCredits;
+    tagged_images: PersonTaggedImages;
+    translations: PersonTranslations;
+    tv_credits: PersonTVCredits;
+};
+/**
+ * Base param for person-specific endpoints.
+ */
+export type PersonBaseParam = {
+    person_id: number;
+};
+/**
+ * Parameters for fetching person details.
+ */
+export type PersonDetailsParams = Prettify<PersonBaseParam & {
+    append_to_response?: PersonAppendToResponseNamespace | PersonAppendToResponseNamespace[];
+} & WithLanguage>;
+/**
+ * Parameters for fetching person changes.
+ */
+export type PersonChangesParams = Prettify<PersonBaseParam & WithPage & DateRange>;
+/**
+ * Parameters for language-aware person credit endpoints.
+ */
+export type PersonCreditsParams = Prettify<PersonBaseParam & WithLanguage>;
+export type PersonExternalIDsParams = PersonBaseParam;
+export type PersonImagesParams = PersonBaseParam;
+export type PersonTranslationsParams = PersonBaseParam;
+export type PersonTaggedImagesParams = Prettify<PersonBaseParam & WithPage>;

package/dist/types/people.js

@@ -0,0 +1 @@
+export {};

package/dist/types/reviews.d.ts

@@ -0,0 +1,22 @@
+import type { Review } from "./common/media";
+/**
+ * Full details for a single TMDB review, as returned by GET /review/{review_id}.
+ * Extends the base Review type with media context fields.
+ */
+export type ReviewDetails = Review & {
+    /** ISO 639-1 language code of the review content */
+    iso_639_1: string;
+    /** The TMDB ID of the reviewed media */
+    media_id: number;
+    /** The title of the reviewed media */
+    media_title: string;
+    /** The type of media being reviewed */
+    media_type: "movie" | "tv";
+};
+/**
+ * Parameters for fetching a review by its TMDB review ID.
+ */
+export type ReviewDetailsParams = {
+    /** The TMDB review identifier */
+    review_id: string;
+};

package/dist/types/reviews.js

@@ -0,0 +1 @@
+export {};

package/dist/types/tv-episodes.d.ts

@@ -93,5 +93,6 @@ export type TVEpisodeDetailsParams = Prettify<TVEpisodeBaseParams & {
 /** Parameters for tv episode credits endpoint */
 export type TVEpisodeCreditsParams = TVEpisodeBaseParams & WithLanguage;
 export type TVEpisodeImagesParams = TVEpisodeBaseParams & WithLanguage & {
-    include_image_language?: Language;
+    /** Languages to include images for. Pass an array — it will be serialized as a comma-separated list (e.g. ["en", "null"]). Use "null" to include untagged images. */
+    include_image_language?: (Language | "null")[];
 };

package/dist/types/tv-seasons.d.ts

@@ -1,4 +1,5 @@
 import { Cast, Crew, DateRange, ImageItem, ImagesResult, TranslationResults, VideoResults, WithLanguage, WithParams } from "./common";
+import { Language } from "./config";
 import { TVAggregateCredits, TVBaseParam, TVEpisodeItem, TVExternalIDs } from "./tv-series";
 import { MediaWatchProviders } from "./common/media";
 import { NetworkItem } from "./networks";
@@ -119,7 +120,8 @@ export type TVSeasonAggregateCreditsParams = TVSeasonBaseParams & WithLanguage;
 export type TVSeasonCreditsParams = TVSeasonBaseParams & WithLanguage;
 /** Parameters for the season images endpoint, with optional language filtering. */
 export type TVSeasonImagesParams = TVSeasonBaseParams & WithLanguage & {
-    include_image_language?: string;
+    /** Languages to include images for. Pass an array — it will be serialized as a comma-separated list (e.g. ["en", "null"]). Use "null" to include untagged images. */
+    include_image_language?: (Language | "null")[];
 };
 /** Parameters for the season videos endpoint, with optional language filtering. */
 export type TVSeasonVideosParams = TVSeasonBaseParams & WithLanguage & {

package/dist/types/tv-series.d.ts

@@ -424,8 +424,8 @@ export type TVCreditsParams = Prettify<TVBaseParam & WithLanguage>;
 export type TVImagesParams = Prettify<TVBaseParam & {
     /** Language for image metadata (supports both ISO-639-1 and full Language format) */
     language?: Language | LanguageISO6391;
-    /** Include images with specific language tags (comma-separated, e.g., "en,null") */
-    include_image_language?: Language | LanguageISO6391;
+    /** Languages to include images for. Pass an array — it will be serialized as a comma-separated list (e.g. ["en", "null"]). Use "null" to include untagged images. */
+    include_image_language?: (Language | "null")[];
 }>;
 /**
  * Parameters for fetching TV series lists (lists endpoint, different from airing_today ecc...).

package/dist/utils/index.d.ts

@@ -1 +1,2 @@
 export * from "./logger";
+export * from "./jwt";

package/dist/utils/index.js

@@ -1 +1,2 @@
 export * from "./logger";
+export * from "./jwt";

package/dist/utils/jwt.d.ts

@@ -0,0 +1 @@
+export declare function isJwt(token: string): boolean;

package/dist/utils/jwt.js

@@ -0,0 +1,61 @@
+function isBase64Url(str) {
+    return /^[A-Za-z0-9\-_]+$/.test(str);
+}
+function decodeBase64Url(str) {
+    try {
+        const base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), "=");
+        return atob(padded);
+    }
+    catch {
+        return null;
+    }
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+function isJwtHeader(value) {
+    if (!isObject(value))
+        return false;
+    return typeof value.alg === "string";
+}
+function isJwtPayload(value) {
+    if (!isObject(value))
+        return false;
+    if ("exp" in value && typeof value.exp !== "number")
+        return false;
+    if ("nbf" in value && typeof value.nbf !== "number")
+        return false;
+    if ("iat" in value && typeof value.iat !== "number")
+        return false;
+    return true;
+}
+export function isJwt(token) {
+    if (typeof token !== "string")
+        return false;
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return false;
+    const [headerB64, payloadB64, signatureB64] = parts;
+    if (!isBase64Url(headerB64) || !isBase64Url(payloadB64) || !isBase64Url(signatureB64)) {
+        return false;
+    }
+    const headerStr = decodeBase64Url(headerB64);
+    const payloadStr = decodeBase64Url(payloadB64);
+    if (!headerStr || !payloadStr)
+        return false;
+    let parsedHeader;
+    let parsedPayload;
+    try {
+        parsedHeader = JSON.parse(headerStr);
+        parsedPayload = JSON.parse(payloadStr);
+    }
+    catch {
+        return false;
+    }
+    if (!isJwtHeader(parsedHeader))
+        return false;
+    if (!isJwtPayload(parsedPayload))
+        return false;
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lorenzopant/tmdb",
-	"version": "1.15.1",
+	"version": "1.17.0",
 	"description": "A completely type-safe The Movie Database (TMDB) API wrapper for typescript applications.",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -21,6 +21,8 @@
 		"dev": "tsc --watch",
 		"typecheck": "tsc --noEmit",
 		"test": "vitest",
+		"test:unit": "vitest run --exclude '**/*.integration.test.ts'",
+		"test:integration": "vitest run integration",
 		"test:ui": "vitest --ui",
 		"test:coverage": "vitest --coverage",
 		"prepare": "husky",
@@ -43,7 +45,7 @@
 		"@eslint/compat": "^2.0.0",
 		"@eslint/eslintrc": "^3.3.1",
 		"@eslint/js": "^9.30.0",
-		"@types/node": "^22.15.2",
+		"@types/node": "^22.19.11",
 		"@typescript-eslint/eslint-plugin": "^8.35.0",
 		"@typescript-eslint/parser": "^8.35.0",
 		"@vitest/coverage-v8": "^4.0.9",