@lorenzopant/tmdb 1.16.0 → 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/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/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;

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",

package/dist/tmdb.d.ts

@@ -23,6 +23,7 @@ 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;
@@ -50,6 +51,7 @@ export declare class TMDB {
     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

@@ -25,6 +25,7 @@ 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
@@ -52,6 +53,7 @@ export class TMDB {
     trending;
     reviews;
     people_lists;
+    people;
     // etc...
     /**
      * Creates a new TMDB instance.
@@ -87,5 +89,6 @@ export class TMDB {
         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/index.d.ts

@@ -18,3 +18,4 @@ export * from "./keywords";
 export * from "./credits";
 export * from "./reviews";
 export * from "./people-lists";
+export * from "./people";

package/dist/types/index.js

@@ -18,3 +18,4 @@ export * from "./keywords";
 export * from "./credits";
 export * from "./reviews";
 export * from "./people-lists";
+export * from "./people";

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/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.16.0",
+	"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",
@@ -45,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",