@tdanks2000/tmdb-wrapper 1.3.4 → 1.5.0

package/dist/index.mjs

@@ -113,9 +113,32 @@ let ReleaseDateType = /* @__PURE__ */ function(ReleaseDateType$1) {
 //#endregion
 //#region src/utils/api.ts
 const BASE_URL_V3 = "https://api.themoviedb.org/3";
+/**
+* Lightweight TMDB v3 API client.
+*
+* - Sends requests to `https://api.themoviedb.org/3`.
+* - Supports authentication via:
+*   - v4 API Read Access Token (Bearer), and/or
+*   - v3 API key via `api_key` query parameter.
+*
+* Notes:
+* - Many endpoints accept either method depending on your TMDB settings.
+* - When an API key is present, it is appended as `api_key` in the query string.
+*/
 var API = class {
+	/**
+	* Optional v3 API key (sent as `api_key` query param).
+	*/
 	apiKey;
+	/**
+	* Optional v4 read access token (sent as `Authorization: Bearer ...`).
+	*/
 	accessToken;
+	/**
+	* Create a new API client.
+	*
+	* @param {TokenType} auth - Authentication information.
+	*/
 	constructor(auth) {
 		if (typeof auth === "string") this.accessToken = auth;
 		else {
@@ -124,9 +147,16 @@ var API = class {
 		}
 	}
 	/**
-	* Generic GET:
-	* @template T — response type
-	* @template O — options (query params) type
+	* Generic HTTP GET request.
+	*
+	* @template T - Response JSON type.
+	* @template O - Query options (query params) type.
+	*
+	* @param {string} path - The TMDB path beginning with `/`, e.g. `/movie/550`.
+	* @param {O} [options] - Query parameters to serialize.
+	*
+	* @returns {Promise<T>} Resolves with parsed JSON typed as `T`.
+	* @throws {ErrorResponse} Rejects with parsed TMDB error payload when `response.ok` is false.
 	*/
 	async get(path, options) {
 		const rawOptions = {
@@ -148,6 +178,16 @@ var API = class {
 		return await response.json();
 	}
 };
+/**
+* Serializes an options object into a query string.
+*
+* - Skips `undefined` and `null`.
+* - Arrays are expanded into repeated keys:
+*   `{ with_genres: ["12", "16"] }` -> `with_genres=12&with_genres=16`
+*
+* @param {Record<string, unknown>} [options] - Options to serialize.
+* @returns {string} Query string without the leading `?`.
+*/
 const parseOptions = (options) => {
 	if (!options) return "";
 	const entries = [];
@@ -161,31 +201,7 @@ const parseOptions = (options) => {
 
 //#endregion
 //#region src/utils/getimagePath.ts
-/**
-* Utility method to construct full url for image
-* based on configuration
-*
-* https://developers.themoviedb.org/3/getting-started/images
-* @param {string} baseUrl base image url (e.g., 'https://image.tmdb.org/t/p/')
-* @param {string} fileSize file size (e.g., 'original', 'w500')
-* @param {string} imagePath raw image path
-* @param {string} format override image format (e.g., 'svg', 'png', 'jpg')
-* @returns {string} The complete image URL
-*/
-const getFullImagePath = (baseUrl, fileSize, imagePath, format) => {
-	if (!imagePath) return "";
-	const hasExtension = imagePath.includes(".");
-	if (hasExtension) {
-		const imagePathArr = imagePath.split(".");
-		const imageFormat$1 = format || imagePathArr[1];
-		return `${baseUrl}${fileSize}${imagePathArr[0]}.${imageFormat$1}`;
-	}
-	const imageFormat = format || "jpg";
-	return `${baseUrl}${fileSize}${imagePath}.${imageFormat}`;
-};
-/**
-* Common image sizes available in TMDB
-*/
+const TMDB_IMAGE_BASE_URL = "https://image.tmdb.org/t/p/";
 const ImageSizes = {
 	ORIGINAL: "original",
 	W500: "w500",
@@ -194,19 +210,67 @@ const ImageSizes = {
 	W92: "w92",
 	H632: "h632"
 };
-/**
-* Image formats supported by TMDB
-*/
 const ImageFormats = {
 	JPG: "jpg",
 	PNG: "png",
 	SVG: "svg"
 };
+const isAbsoluteUrl = (value) => /^https?:\/\//i.test(value);
+const normalizeBaseUrl = (baseUrl) => baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+const normalizeSize = (size) => size.replace(/^\/+|\/+$/g, "");
+const normalizePath = (path) => path.startsWith("/") ? path : `/${path}`;
+const setExtension = (path, format) => {
+	const lastSlash = path.lastIndexOf("/");
+	const lastDot = path.lastIndexOf(".");
+	const hasExt = lastDot > lastSlash;
+	if (!hasExt) return `${path}.${format}`;
+	return `${path.slice(0, lastDot + 1)}${format}`;
+};
+/**
+* Constructs a TMDB image URL.
+*
+* - Keeps paths as-is unless `format` is provided (then it replaces/appends
+*   the extension safely using the last dot after the last slash).
+* - Handles leading/trailing slashes robustly.
+* - If `imagePath` is already an absolute URL, it is returned unchanged.
+*/
+const getFullImagePath = (baseUrl, fileSize, imagePath, format) => {
+	if (!imagePath) return "";
+	if (isAbsoluteUrl(imagePath)) return imagePath;
+	const base = normalizeBaseUrl(baseUrl);
+	const size = normalizeSize(fileSize);
+	let path = normalizePath(imagePath);
+	if (format) path = setExtension(path, format);
+	return `${base}${size}${path}`;
+};
+/**
+* Convenience helper for TMDB `Image` objects.
+*/
+const formImage = (image, fileSize, format) => {
+	const path = image?.file_path;
+	if (!path) return void 0;
+	return getFullImagePath(TMDB_IMAGE_BASE_URL, fileSize, path, format);
+};
 
 //#endregion
 //#region src/@types/models/baseEndpoint.ts
+/**
+* Base class for all TMDB API endpoints.
+*
+* Provides a configured {@link API} client instance to subclasses.
+*/
 var BaseEndpoint = class {
+	/**
+	* Low-level HTTP client wrapper used by all endpoints.
+	*/
 	api;
+	/**
+	* Create a new endpoint instance.
+	*
+	* @param {TokenType} auth - Authentication information.
+	* - If a string: treated as a v4 API Read Access Token (Bearer token).
+	* - If an object: can include an API key and/or access token, depending on your {@link TokenType}.
+	*/
 	constructor(auth) {
 		this.auth = auth;
 		this.api = new API(auth);
@@ -217,11 +281,20 @@ var BaseEndpoint = class {
 //#region src/endpoints/account.ts
 /**
 * Represents an endpoint for retrieving account details.
+*
+* TMDB v3 reference:
+* - GET /account/{account_id}
+*
+* Note:
+* TMDB does not expose a generic "GET /account" for account details. You must
+* provide an `account_id`. Most apps obtain it from an auth flow and then cache
+* it for subsequent requests.
 */
 var AccountEndpoint = class extends BaseEndpoint {
 	/**
 	* Constructs a new AccountEndpoint instance.
-	* @param {string} access_token - The access token used for authentication.
+	*
+	* @param {TokenType} access_token - The access token used for authentication.
 	*/
 	constructor(access_token) {
 		super(access_token);
@@ -229,10 +302,14 @@ var AccountEndpoint = class extends BaseEndpoint {
 	}
 	/**
 	* Retrieves account details asynchronously.
+	*
+	* TMDB: GET /account/{account_id}
+	*
+	* @param {number} accountId - The TMDB account ID.
 	* @returns {Promise<AccountDetails>} A Promise that resolves with the account details.
 	*/
-	async details() {
-		return await this.api.get("/account");
+	details(accountId) {
+		return this.api.get(`/account/${accountId}`);
 	}
 };
 
@@ -240,11 +317,16 @@ var AccountEndpoint = class extends BaseEndpoint {
 //#region src/endpoints/certification.ts
 /**
 * Represents an endpoint for retrieving certifications for movies and TV shows.
+*
+* TMDB v3 reference:
+* - GET /certification/movie/list
+* - GET /certification/tv/list
 */
 var CertificationEndpoint = class extends BaseEndpoint {
 	/**
 	* Constructs a new CertificationEndpoint instance.
-	* @param {string} access_token - The access token used for authentication.
+	*
+	* @param {TokenType} access_token - The access token used for authentication.
 	*/
 	constructor(access_token) {
 		super(access_token);
@@ -252,17 +334,23 @@ var CertificationEndpoint = class extends BaseEndpoint {
 	}
 	/**
 	* Retrieves certifications for movies asynchronously.
+	*
+	* TMDB: GET /certification/movie/list
+	*
 	* @returns {Promise<Certifications>} A Promise that resolves with the certifications for movies.
 	*/
-	async movies() {
-		return await this.api.get("/certification/movie/list");
+	movies() {
+		return this.api.get("/certification/movie/list");
 	}
 	/**
 	* Retrieves certifications for TV shows asynchronously.
+	*
+	* TMDB: GET /certification/tv/list
+	*
 	* @returns {Promise<Certifications>} A Promise that resolves with the certifications for TV shows.
 	*/
-	async tv() {
-		return await this.api.get("/certification/tv/list");
+	tv() {
+		return this.api.get("/certification/tv/list");
 	}
 };
 
@@ -270,11 +358,17 @@ var CertificationEndpoint = class extends BaseEndpoint {
 //#region src/endpoints/changes.ts
 /**
 * Represents an endpoint for retrieving changes in movies, TV shows, and persons.
+*
+* TMDB v3 reference:
+* - GET /movie/changes
+* - GET /tv/changes
+* - GET /person/changes
 */
 var ChangeEndpoint = class extends BaseEndpoint {
 	/**
 	* Constructs a new ChangeEndpoint instance.
-	* @param {string} access_token - The access token used for authentication.
+	*
+	* @param {TokenType} access_token - The access token used for authentication.
 	*/
 	constructor(access_token) {
 		super(access_token);
@@ -282,27 +376,36 @@ var ChangeEndpoint = class extends BaseEndpoint {
 	}
 	/**
 	* Retrieves changes in movies asynchronously.
+	*
+	* TMDB: GET /movie/changes
+	*
 	* @param {ChangeOption} [options] - Optional parameters for filtering the changes.
 	* @returns {Promise<MediaChanges>} A Promise that resolves with the changes in movies.
 	*/
-	async movies(options) {
-		return await this.api.get("/movie/changes", options);
+	movies(options) {
+		return this.api.get("/movie/changes", options);
 	}
 	/**
 	* Retrieves changes in TV shows asynchronously.
+	*
+	* TMDB: GET /tv/changes
+	*
 	* @param {ChangeOption} [options] - Optional parameters for filtering the changes.
 	* @returns {Promise<MediaChanges>} A Promise that resolves with the changes in TV shows.
 	*/
-	async tv(options) {
-		return await this.api.get("/tv/changes", options);
+	tv(options) {
+		return this.api.get("/tv/changes", options);
 	}
 	/**
 	* Retrieves changes related to persons asynchronously.
+	*
+	* TMDB: GET /person/changes
+	*
 	* @param {ChangeOption} [options] - Optional parameters for filtering the changes.
 	* @returns {Promise<MediaChanges>} A Promise that resolves with the changes related to persons.
 	*/
-	async person(options) {
-		return await this.api.get("/person/changes", options);
+	person(options) {
+		return this.api.get("/person/changes", options);
 	}
 };
 
@@ -446,11 +549,16 @@ var CreditsEndpoint = class extends BaseEndpoint {
 const BASE_DISCOVER = "/discover";
 /**
 * Represents an endpoint for discovering movies and TV shows based on various criteria.
+*
+* TMDB v3 reference:
+* - GET /discover/movie
+* - GET /discover/tv
 */
 var DiscoverEndpoint = class extends BaseEndpoint {
 	/**
 	* Constructs a new DiscoverEndpoint instance.
-	* @param {string} access_token - The access token used for authentication.
+	*
+	* @param {TokenType} access_token - The access token used for authentication.
 	*/
 	constructor(access_token) {
 		super(access_token);
@@ -458,19 +566,25 @@ var DiscoverEndpoint = class extends BaseEndpoint {
 	}
 	/**
 	* Retrieves a list of movies based on the provided query options asynchronously.
+	*
+	* TMDB: GET /discover/movie
+	*
 	* @param {MovieQueryOptions} [options] - Optional parameters for refining the movie discovery.
 	* @returns {Promise<MovieDiscoverResult>} A Promise that resolves with the movie discovery results.
 	*/
-	async movie(options) {
-		return await this.api.get(`${BASE_DISCOVER}/movie`, options);
+	movie(options) {
+		return this.api.get(`${BASE_DISCOVER}/movie`, options);
 	}
 	/**
 	* Retrieves a list of TV shows based on the provided query options asynchronously.
+	*
+	* TMDB: GET /discover/tv
+	*
 	* @param {TvShowQueryOptions} [options] - Optional parameters for refining the TV show discovery.
 	* @returns {Promise<TvShowDiscoverResult>} A Promise that resolves with the TV show discovery results.
 	*/
-	async tvShow(options) {
-		return await this.api.get(`${BASE_DISCOVER}/tv`, options);
+	tvShow(options) {
+		return this.api.get(`${BASE_DISCOVER}/tv`, options);
 	}
 };
 
@@ -1557,5 +1671,5 @@ var TMDB = class {
 };
 
 //#endregion
-export { API, BackdropSizes, BaseEndpoint, ChangeKeys, ImageFormats, ImageSizes, LogoSizes, PosterSizes, ProfileSizes, ReleaseDateType, StillSizes, TMDB, getFullImagePath, parseOptions };
+export { API, BackdropSizes, BaseEndpoint, ChangeKeys, ImageFormats, ImageSizes, LogoSizes, PosterSizes, ProfileSizes, ReleaseDateType, StillSizes, TMDB, TMDB_IMAGE_BASE_URL, formImage, getFullImagePath, parseOptions };
 //# sourceMappingURL=index.mjs.map