@tdanks2000/tmdb-wrapper 1.3.4 → 1.5.0

package/README.md

@@ -192,36 +192,97 @@ The wrapper also provides access to these additional endpoints:
 
 ## Image Handling
 
-The wrapper provides enhanced utilities for handling TMDB images:
+## Image Handling
+
+The wrapper includes utilities to reliably construct TMDB image URLs, plus a convenience helper for TMDB `Image` objects.
+
+```typescript
+import {
+	formImage,
+	getFullImagePath,
+	ImageSizes,
+	ImageFormats,
+} from "@tdanks2000/tmdb-wrapper";
+```
+
+### `getFullImagePath(...)`
 
 ```typescript
-import { getFullImagePath, ImageSizes, ImageFormats } from '@tdanks2000/tmdb-wrapper';
+getFullImagePath(
+  baseUrl: string,      // e.g. "https://image.tmdb.org/t/p/"
+  fileSize: string,     // e.g. ImageSizes.W500 or "w780"
+  imagePath: string,    // e.g. "/abc123" or "/abc123.jpg"
+  format?: string       // optional: ImageFormats.JPG / PNG / SVG
+): string
+```
+
+Notes:
+- `imagePath` can be with or without a leading `/` (both work).
+- If `imagePath` is already an absolute URL (`https://...`), it’s returned unchanged.
+- If you provide `format`, the extension is appended/replaced safely.
+- If you omit `format`, the original path is preserved (no forced default extension).
+
+### `formImage(image, fileSize, format?)`
+
+`formImage` is a small helper that reads `file_path` from a TMDB `Image` object and returns a ready-to-use URL. If the image object doesn’t include a `file_path`, it returns `undefined`.
+
+```typescript
+formImage(
+  image: Image,
+  fileSize: ImageSizes,
+  format?: ImageFormats
+): string | undefined
+```
+
+### Examples
+
+Poster path without extension (add one via `format`):
 
-// Example usage for movie poster
+```typescript
 const posterUrl = getFullImagePath(
-  'https://image.tmdb.org/t/p/',
-  ImageSizes.W500,
-  '/wwemzKWzjKYJFfCeiB57q3r4Bcm',
-  ImageFormats.JPG
+	"https://image.tmdb.org/t/p/",
+	ImageSizes.W500,
+	"/wwemzKWzjKYJFfCeiB57q3r4Bcm",
+	ImageFormats.JPG,
 );
-// Results in: https://image.tmdb.org/t/p/w500/wwemzKWzjKYJFfCeiB57q3r4Bcm.jpg
+// https://image.tmdb.org/t/p/w500/wwemzKWzjKYJFfCeiB57q3r4Bcm.jpg
+```
 
-// Example usage for profile image
+Profile path that already includes an extension (no need to pass `format`):
+
+```typescript
 const profileUrl = getFullImagePath(
-  'https://image.tmdb.org/t/p/',
-  ImageSizes.W185,
-  '/5XBzD5WuTyVQZeS4VI25z2moMeY.jpg',
-  ImageFormats.JPG
+	"https://image.tmdb.org/t/p/",
+	ImageSizes.W185,
+	"/5XBzD5WuTyVQZeS4VI25z2moMeY.jpg",
 );
-// Results in: https://image.tmdb.org/t/p/w185/5XBzD5WuTyVQZeS4VI25z2moMeY.jpg
+// https://image.tmdb.org/t/p/w185/5XBzD5WuTyVQZeS4VI25z2moMeY.jpg
+```
+
+Using `formImage` with a TMDB response image object:
+
+```typescript
+const images = await tmdb.movies.getImages(550);
+const poster = images.posters[0];
+
+const posterUrl = formImage(poster, ImageSizes.W500);
+// e.g. https://image.tmdb.org/t/p/w500/xxxxx.jpg
 ```
 
-The utility supports all TMDB image sizes and formats:
+Override the output extension (append/replace) with `format`:
+
+```typescript
+const posterPngUrl = formImage(poster, ImageSizes.W500, ImageFormats.PNG);
+```
+
+### Sizes & formats
+
+This package exports common presets:
 
-- **Sizes**: W45, W92, W154, W185, W300, W342, W500, W780, W1280, Original
-- **Formats**: JPG, PNG, SVG
+- **Sizes**: `ImageSizes.ORIGINAL`, `W500`, `W300`, `W185`, `W92`, `H632`
+- **Formats**: `ImageFormats.JPG`, `PNG`, `SVG`
 
-## Examples
+TMDB can support additional sizes depending on their configuration; you can also pass any valid TMDB size string directly (e.g. `"w780"`, `"w1280"`).
 
 ### Searching for Content
 

package/dist/index.cjs

@@ -114,9 +114,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 {
@@ -125,9 +148,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 = {
@@ -149,6 +179,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 = [];
@@ -162,31 +202,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",
@@ -195,19 +211,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);
@@ -218,11 +282,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);
@@ -230,10 +303,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}`);
 	}
 };
 
@@ -241,11 +318,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);
@@ -253,17 +335,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");
 	}
 };
 
@@ -271,11 +359,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);
@@ -283,27 +377,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);
 	}
 };
 
@@ -447,11 +550,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);
@@ -459,19 +567,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);
 	}
 };
 
@@ -1570,5 +1684,7 @@ exports.ProfileSizes = ProfileSizes;
 exports.ReleaseDateType = ReleaseDateType;
 exports.StillSizes = StillSizes;
 exports.TMDB = TMDB;
+exports.TMDB_IMAGE_BASE_URL = TMDB_IMAGE_BASE_URL;
+exports.formImage = formImage;
 exports.getFullImagePath = getFullImagePath;
 exports.parseOptions = parseOptions;