@lorenzopant/tmdb 1.15.1 → 1.16.0

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_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

@@ -136,4 +136,10 @@ export declare const ENDPOINTS: {
         TV: string;
         PERSON: string;
     };
+    REVIEWS: {
+        DETAILS: string;
+    };
+    PEOPLE_LISTS: {
+        POPULAR: string;
+    };
 };

package/dist/routes.js

@@ -136,4 +136,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,8 @@ 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";
 export declare class TMDB {
     private client;
     private options;
@@ -46,6 +48,8 @@ export declare class TMDB {
     tv_episode_groups: TVEpisodeGroupsAPI;
     tv_seasons: TVSeasonsAPI;
     trending: TrendingAPI;
+    reviews: ReviewsAPI;
+    people_lists: PeopleListsAPI;
     /**
      * Creates a new TMDB instance.
      * @param accessToken The TMDB API access token.

package/dist/tmdb.js

@@ -23,6 +23,8 @@ 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";
 export class TMDB {
     client;
     options; // ** Default options for all requests
@@ -48,6 +50,8 @@ export class TMDB {
     tv_episode_groups;
     tv_seasons;
     trending;
+    reviews;
+    people_lists;
     // etc...
     /**
      * Creates a new TMDB instance.
@@ -81,5 +85,7 @@ 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);
     }
 }

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,5 @@ export * from "./find";
 export * from "./watch-providers";
 export * from "./keywords";
 export * from "./credits";
+export * from "./reviews";
+export * from "./people-lists";

package/dist/types/index.js

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

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/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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lorenzopant/tmdb",
-	"version": "1.15.1",
+	"version": "1.16.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",