tmdb-kit 0.1.0-beta.3 → 1.0.0

package/dist/index.cjs

@@ -37,13 +37,86 @@ var TMDBResponseError = class extends TMDBError {
 		this.statusCode = body?.status_code;
 		this.statusMessage = body?.status_message;
 	}
+	/** True when TMDB has asked the caller to back off (HTTP 429). */
+	get isRateLimit() {
+		return this.status === 429;
+	}
+	/** True when the resource was not found (HTTP 404). */
+	get isNotFound() {
+		return this.status === 404;
+	}
+	/** True when the request was rejected as unauthenticated (HTTP 401). */
+	get isUnauthorized() {
+		return this.status === 401;
+	}
+	/** True when the request was rejected as forbidden (HTTP 403). */
+	get isForbidden() {
+		return this.status === 403;
+	}
+	/** True when the upstream returned a 5xx server error. */
+	get isServerError() {
+		return this.status >= 500 && this.status < 600;
+	}
 };
+/**
+* Thrown when TMDB returns HTTP 429.
+*
+* The SDK does NOT retry automatically — that decision is left to the
+* caller, since retry policies vary widely. Inspect `retryAfter` to
+* implement your own backoff.
+*/
+var TMDBRateLimitError = class extends TMDBResponseError {
+	retryAfter;
+	constructor(message, options) {
+		super(message, options);
+		this.name = "TMDBRateLimitError";
+		this.retryAfter = options.retryAfter;
+	}
+};
+/**
+* Create the appropriate error instance for a non-2xx TMDB response.
+*
+* Returns a {@link TMDBRateLimitError} when the status is 429, otherwise
+* a generic {@link TMDBResponseError}. The error message is extracted from
+* the TMDB `status_message` field when available.
+*/
 function createResponseError(options) {
-	return new TMDBResponseError((isErrorResponseBody(options.body) ? options.body : void 0)?.status_message ?? `${options.status} ${options.statusText}`.trim(), options);
+	const message = (isErrorResponseBody(options.body) ? options.body : void 0)?.status_message ?? `${options.status} ${options.statusText}`.trim();
+	if (options.status === 429) return new TMDBRateLimitError(message, {
+		...options,
+		retryAfter: parseRetryAfter(options.headers.get("retry-after"))
+	});
+	return new TMDBResponseError(message, options);
 }
+/**
+* Parse the `Retry-After` header into seconds. Accepts both delta-seconds
+* (e.g. "5") and HTTP-date forms (e.g. "Wed, 21 Oct 2026 07:28:00 GMT").
+* Falls back to 1 second when the header is missing or unparseable.
+*/
+function parseRetryAfter(value) {
+	if (value === null || value === void 0) return 1;
+	const trimmed = value.trim();
+	if (trimmed === "") return 1;
+	const seconds = Number(trimmed);
+	if (Number.isFinite(seconds) && seconds >= 0) return seconds;
+	const date = Date.parse(trimmed);
+	if (Number.isFinite(date)) {
+		const deltaMs = date - Date.now();
+		return Math.max(1, Math.ceil(deltaMs / 1e3));
+	}
+	return 1;
+}
+/** Check if a value has the shape of a TMDB error response body. */
 function isErrorResponseBody(value) {
 	return typeof value === "object" && value !== null;
 }
+/**
+* Append query parameters to a URL object.
+*
+* - `undefined` and `null` values are skipped.
+* - Arrays are joined with commas (TMDB convention).
+* - All values are converted to strings.
+*/
 function appendQuery(url, query) {
 	for (const [key, value] of Object.entries(query)) {
 		if (value === void 0 || value === null) continue;
@@ -54,6 +127,12 @@ function appendQuery(url, query) {
 		url.searchParams.set(key, String(value));
 	}
 }
+/**
+* Merge a language query parameter with client defaults.
+*
+* If `query.language` is set it takes precedence; otherwise the client's
+* default language is used.
+*/
 function withLanguage(defaults, query) {
 	const language = typeof query.language === "string" ? query.language : defaults.language;
 	return {
@@ -61,6 +140,11 @@ function withLanguage(defaults, query) {
 		language
 	};
 }
+/**
+* Merge language and region defaults for list endpoints.
+*
+* Combines {@link withLanguage} with region fallback from client defaults.
+*/
 function withListDefaults(defaults, query) {
 	const region = typeof query.region === "string" ? query.region : defaults.region;
 	return {
@@ -68,19 +152,40 @@ function withListDefaults(defaults, query) {
 		region
 	};
 }
+/**
+* Convert a string or string array to a comma-separated list.
+*
+* Returns `undefined` if the input is `undefined` (skips the parameter).
+* TMDB uses comma-separated values for multi-value query parameters.
+*/
 function toCommaList(value) {
 	if (value === void 0) return;
 	return typeof value === "string" ? value : value.join(",");
 }
+/**
+* Validate and convert a numeric ID to a string for use in URL paths.
+*
+* @throws {TMDBRequestError} If `value` is not a positive integer.
+*/
 function toId(value, name) {
 	if (!Number.isInteger(value) || value <= 0) throw new TMDBRequestError(`${name} must be a positive integer`);
 	return String(value);
 }
+/**
+* Validate and trim a search query string.
+*
+* @throws {TMDBRequestError} If the query is empty after trimming.
+*/
 function toSearchQuery(value) {
 	const query = value.trim();
 	if (query.length === 0) throw new TMDBRequestError("search query must not be empty");
 	return query;
 }
+/**
+* Validate a trending time window value.
+*
+* @throws {TMDBRequestError} If `value` is not `"day"` or `"week"`.
+*/
 function toTimeWindow(value) {
 	if (value !== "day" && value !== "week") throw new TMDBRequestError("timeWindow must be either \"day\" or \"week\"");
 	return value;
@@ -91,15 +196,27 @@ function toTimeWindow(value) {
 */
 function buildImageUrl(path, size = "original", options = {}) {
 	if (path === void 0 || path === null || path.trim() === "") return null;
-	return `${normalizeBaseUrl(options.baseUrl ?? "https://image.tmdb.org/t/p")}/${size}${path.startsWith("/") ? path : `/${path}`}`;
+	const url = `${normalizeBaseUrl(options.baseUrl ?? "https://image.tmdb.org/t/p")}/${size}${path.startsWith("/") ? path : `/${path}`}`;
+	return options.transform ? options.transform(url) : url;
 }
+/**
+* Strip trailing slashes from a base URL to ensure consistent path joining.
+*/
 function normalizeBaseUrl(baseUrl) {
 	return baseUrl.replace(/\/+$/, "");
 }
 //#endregion
 //#region src/http.ts
+/**
+* Built-in HTTP transport that uses the Fetch API.
+*
+* Handles authentication (API key or access token), URL construction,
+* request headers, and response parsing. Use the factory function
+* {@link createTMDB} instead of instantiating this directly.
+*/
 var TMDBHttpClient = class {
 	defaults;
+	imageTransform;
 	#apiKey;
 	#accessToken;
 	#baseUrl;
@@ -109,25 +226,25 @@ var TMDBHttpClient = class {
 		const accessToken = normalizeSecret("accessToken" in options ? options.accessToken : void 0);
 		const apiKey = normalizeSecret("apiKey" in options ? options.apiKey : void 0);
 		if (Boolean(accessToken) === Boolean(apiKey)) throw new TMDBRequestError("Provide exactly one of accessToken or apiKey");
-		const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
-		if (typeof fetchImpl !== "function") throw new TMDBRequestError("No fetch implementation found. Pass options.fetch in this runtime.");
 		this.#accessToken = accessToken;
 		this.#apiKey = apiKey;
 		this.#baseUrl = normalizeBaseUrl(options.baseUrl ?? "https://api.themoviedb.org/3");
-		this.#fetch = fetchImpl;
+		this.#fetch = options.fetch;
 		this.#headers = options.headers;
 		this.defaults = {
 			imageBaseUrl: normalizeBaseUrl(options.imageBaseUrl ?? "https://image.tmdb.org/t/p"),
 			language: options.defaultLanguage,
 			region: options.defaultRegion
 		};
+		this.imageTransform = options.images?.transform;
 	}
 	async get(path, options = {}) {
 		const url = this.#createUrl(path, options.query ?? {});
 		const headers = this.#createHeaders(options.headers);
+		const fetchImpl = this.#resolveFetch();
 		let response;
 		try {
-			response = await this.#fetch(url, {
+			response = await fetchImpl(url, {
 				headers,
 				method: "GET",
 				signal: options.signal
@@ -145,6 +262,12 @@ var TMDBHttpClient = class {
 		});
 		return body;
 	}
+	#resolveFetch() {
+		if (this.#fetch !== void 0) return this.#fetch;
+		const globalFetch = globalThis.fetch;
+		if (typeof globalFetch !== "function") throw new TMDBRequestError("No fetch implementation found. Pass options.fetch in this runtime.");
+		return globalFetch.bind(globalThis);
+	}
 	#createHeaders(headersInit) {
 		const headers = new Headers(this.#headers);
 		const requestHeaders = new Headers(headersInit);
@@ -163,6 +286,13 @@ var TMDBHttpClient = class {
 		return url.toString();
 	}
 };
+/**
+* Read and parse a JSON response body.
+*
+* Returns `undefined` for empty responses. If the body is not valid JSON,
+* the raw text string is returned as-is (TMDB occasionally returns plain
+* text for certain error conditions).
+*/
 async function readJson(response) {
 	const text = await response.text();
 	if (text.length === 0) return;
@@ -172,12 +302,21 @@ async function readJson(response) {
 		return text;
 	}
 }
+/**
+* Normalize a secret value by trimming whitespace and treating empty
+* strings as undefined (not provided).
+*/
 function normalizeSecret(value) {
 	const secret = value?.trim();
 	return secret === "" ? void 0 : secret;
 }
 //#endregion
 //#region src/resources/configuration.ts
+/**
+* Access TMDB configuration data (image sizes, countries, languages, etc.).
+*
+* Obtained via `client.configuration`.
+*/
 var ConfigurationResource = class {
 	#transport;
 	constructor(transport) {
@@ -204,6 +343,11 @@ var ConfigurationResource = class {
 };
 //#endregion
 //#region src/resources/genres.ts
+/**
+* Access TMDB genre lists for movies and TV shows.
+*
+* Obtained via `client.genres`.
+*/
 var GenresResource = class {
 	#transport;
 	constructor(transport) {
@@ -218,17 +362,33 @@ var GenresResource = class {
 };
 //#endregion
 //#region src/resources/images.ts
+/**
+* Helper for constructing TMDB image URLs from API path values.
+*
+* Obtained via `client.images`. Supports optional URL transforms for
+* routing image requests through a CDN or proxy.
+*/
 var ImagesHelper = class {
 	#transport;
-	constructor(transport) {
+	#transform;
+	constructor(transport, transform) {
 		this.#transport = transport;
+		this.#transform = transform;
 	}
-	url(path, size = "original") {
-		return buildImageUrl(path, size, { baseUrl: this.#transport.defaults.imageBaseUrl });
+	url(path, size = "original", options = {}) {
+		return buildImageUrl(path, size, {
+			baseUrl: this.#transport.defaults.imageBaseUrl,
+			transform: options.transform ?? this.#transform
+		});
 	}
 };
 //#endregion
 //#region src/resources/movies.ts
+/**
+* Access TMDB movie endpoints (popular, top-rated, details, credits, etc.).
+*
+* Obtained via `client.movies`.
+*/
 var MoviesResource = class {
 	#transport;
 	constructor(transport) {
@@ -271,6 +431,7 @@ var MoviesResource = class {
 		return this.#transport.get(`/movie/${toId(movieId, "movieId")}/videos`, { query: withLanguage(this.#transport.defaults, { language: options.language }) });
 	}
 };
+/** Build query parameters for movie list endpoints. */
 function movieListQuery(transport, options) {
 	return withListDefaults(transport.defaults, {
 		language: options.language,
@@ -280,6 +441,11 @@ function movieListQuery(transport, options) {
 }
 //#endregion
 //#region src/resources/people.ts
+/**
+* Access TMDB person (actor, director, etc.) endpoints.
+*
+* Obtained via `client.people`.
+*/
 var PeopleResource = class {
 	#transport;
 	constructor(transport) {
@@ -292,6 +458,7 @@ var PeopleResource = class {
 		return this.#transport.get(`/person/${toId(personId, "personId")}`, { query: withLanguage(this.#transport.defaults, { language: options.language }) });
 	}
 };
+/** Build query parameters for person list endpoints. */
 function peopleListQuery(transport, options) {
 	return withLanguage(transport.defaults, {
 		language: options.language,
@@ -300,6 +467,11 @@ function peopleListQuery(transport, options) {
 }
 //#endregion
 //#region src/resources/search.ts
+/**
+* Search TMDB for movies, TV shows, people, or all media types.
+*
+* Obtained via `client.search`.
+*/
 var SearchResource = class {
 	#transport;
 	constructor(transport) {
@@ -314,10 +486,18 @@ var SearchResource = class {
 	people(query, options = {}) {
 		return this.#transport.get("/search/person", { query: commonSearchQuery(this.#transport, query, options) });
 	}
-	multi(query, options = {}) {
-		return this.#transport.get("/search/multi", { query: commonSearchQuery(this.#transport, query, options) });
+	async multi(query, options = {}) {
+		const response = await this.#transport.get("/search/multi", { query: commonSearchQuery(this.#transport, query, options) });
+		const excluded = options.exclude;
+		if (excluded === void 0 || excluded.length === 0) return response;
+		const excludedSet = new Set(excluded);
+		return {
+			...response,
+			results: response.results.filter((result) => !excludedSet.has(result.media_type))
+		};
 	}
 };
+/** Build query parameters for movie search. */
 function movieSearchQuery(transport, query, options) {
 	return withListDefaults(transport.defaults, {
 		include_adult: options.includeAdult,
@@ -329,6 +509,7 @@ function movieSearchQuery(transport, query, options) {
 		year: options.year
 	});
 }
+/** Build query parameters for TV search. */
 function tvSearchQuery(transport, query, options) {
 	return withLanguage(transport.defaults, {
 		first_air_date_year: options.firstAirDateYear,
@@ -339,6 +520,7 @@ function tvSearchQuery(transport, query, options) {
 		year: options.year
 	});
 }
+/** Build query parameters for person and multi-search. */
 function commonSearchQuery(transport, query, options) {
 	return withLanguage(transport.defaults, {
 		include_adult: options.includeAdult,
@@ -349,6 +531,11 @@ function commonSearchQuery(transport, query, options) {
 }
 //#endregion
 //#region src/resources/trending.ts
+/**
+* Access TMDB trending content (movies, TV, people) for day/week windows.
+*
+* Obtained via `client.trending`.
+*/
 var TrendingResource = class {
 	#transport;
 	constructor(transport) {
@@ -369,6 +556,11 @@ var TrendingResource = class {
 };
 //#endregion
 //#region src/resources/tv.ts
+/**
+* Access TMDB TV show endpoints (popular, top-rated, details, seasons, etc.).
+*
+* Obtained via `client.tv`.
+*/
 var TVResource = class {
 	#transport;
 	constructor(transport) {
@@ -417,6 +609,7 @@ var TVResource = class {
 		}) });
 	}
 };
+/** Build query parameters for TV list endpoints. */
 function tvListQuery(transport, options) {
 	return withLanguage(transport.defaults, {
 		language: options.language,
@@ -441,31 +634,190 @@ var TMDBClient = class {
 	search;
 	trending;
 	tv;
-	#http;
+	#transport;
 	constructor(options) {
-		this.#http = new TMDBHttpClient(options);
-		this.configuration = new ConfigurationResource(this.#http);
-		this.genres = new GenresResource(this.#http);
-		this.images = new ImagesHelper(this.#http);
-		this.movies = new MoviesResource(this.#http);
-		this.people = new PeopleResource(this.#http);
-		this.search = new SearchResource(this.#http);
-		this.trending = new TrendingResource(this.#http);
-		this.tv = new TVResource(this.#http);
-	}
+		const { transport, images, ...httpOptions } = options;
+		const fallbackTransform = images?.transform;
+		const builtInClient = transport === void 0 ? new TMDBHttpClient({
+			...httpOptions,
+			images
+		}) : void 0;
+		this.#transport = builtInClient ?? transport;
+		this.configuration = new ConfigurationResource(this.#transport);
+		this.genres = new GenresResource(this.#transport);
+		this.images = new ImagesHelper(this.#transport, builtInClient ? builtInClient.imageTransform : fallbackTransform);
+		this.movies = new MoviesResource(this.#transport);
+		this.people = new PeopleResource(this.#transport);
+		this.search = new SearchResource(this.#transport);
+		this.trending = new TrendingResource(this.#transport);
+		this.tv = new TVResource(this.#transport);
+	}
+	/**
+	* Make a raw GET request to any TMDB endpoint.
+	*
+	* This is an escape hatch for endpoints not covered by the typed resource
+	* helpers. The `path` should be relative to the API base URL (e.g.
+	* `/movie/{id}/credits`). Response is parsed as JSON and cast to `T`.
+	*
+	* @param path - API path relative to the base URL (e.g. `/movie/123`)
+	* @param options - Optional request-level overrides (headers, query, signal)
+	* @returns Parsed JSON response typed as `T`
+	*/
 	request(path, options) {
-		return this.#http.get(path, options);
+		return this.#transport.get(path, options);
 	}
 };
+/**
+* Create a new {@link TMDBClient} instance.
+*
+* @example
+* ```ts
+* const tmdb = createTMDB({ accessToken: 'YOUR_TOKEN' })
+* const { results } = await tmdb.search.movies('Inception')
+* ```
+*
+* @param options - Authentication and configuration options
+* @returns A configured TMDBClient ready to make API calls
+*/
 function createTMDB(options) {
 	return new TMDBClient(options);
 }
 //#endregion
+//#region src/search-guards.ts
+function isMovieSearchResult(result) {
+	return isObjectWithMediaType(result, "movie");
+}
+function isTVSearchResult(result) {
+	return isObjectWithMediaType(result, "tv");
+}
+function isPersonSearchResult(result) {
+	return isObjectWithMediaType(result, "person");
+}
+function isMovie(result) {
+	return isObjectWithMediaType(result, "movie");
+}
+function isTV(result) {
+	return isObjectWithMediaType(result, "tv");
+}
+function isPerson(result) {
+	return isObjectWithMediaType(result, "person");
+}
+/** Internal helper: check if a value is an object with a matching `media_type` field. */
+function isObjectWithMediaType(value, mediaType) {
+	return typeof value === "object" && value !== null && "media_type" in value && value.media_type === mediaType;
+}
+//#endregion
+//#region src/types.ts
+/**
+* Public set of image sizes TMDB currently documents. The SDK does not
+* pin to a static copy of the TMDB docs — TMDB has added new sizes in
+* the past (e.g. `h632` for profile) without notice — but exposing the
+* canonical list lets callers:
+*
+* - iterate over the set to build a size picker
+* - validate user-supplied sizes with `isKnownBackdropSize(...)` etc.
+* - type a variable as a "known" size without giving up the
+*   `(string & {})` escape hatch for forward-compatibility
+*
+* If TMDB publishes a new size, the SDK will still accept it at runtime
+* (every helper is `(string & {})` permissive), but you will need to
+* add the literal to these constants to get autocomplete on it.
+*/
+const KNOWN_BACKDROP_SIZES = Object.freeze([
+	"w300",
+	"w780",
+	"w1280",
+	"original"
+]);
+const KNOWN_LOGO_SIZES = Object.freeze([
+	"w45",
+	"w92",
+	"w154",
+	"w185",
+	"w300",
+	"w500",
+	"original"
+]);
+const KNOWN_POSTER_SIZES = Object.freeze([
+	"w92",
+	"w154",
+	"w185",
+	"w342",
+	"w500",
+	"w780",
+	"original"
+]);
+const KNOWN_PROFILE_SIZES = Object.freeze([
+	"w45",
+	"w185",
+	"h632",
+	"original"
+]);
+const KNOWN_STILL_SIZES = Object.freeze([
+	"w92",
+	"w185",
+	"w300",
+	"original"
+]);
+/** Union of every documented image size. */
+const KNOWN_IMAGE_SIZES = Object.freeze([
+	...KNOWN_BACKDROP_SIZES,
+	...KNOWN_LOGO_SIZES,
+	...KNOWN_POSTER_SIZES,
+	...KNOWN_PROFILE_SIZES,
+	...KNOWN_STILL_SIZES
+]);
+/** O(1) membership check backed by a Set. */
+const KNOWN_BACKDROP_SET = new Set(KNOWN_BACKDROP_SIZES);
+const KNOWN_LOGO_SET = new Set(KNOWN_LOGO_SIZES);
+const KNOWN_POSTER_SET = new Set(KNOWN_POSTER_SIZES);
+const KNOWN_PROFILE_SET = new Set(KNOWN_PROFILE_SIZES);
+const KNOWN_STILL_SET = new Set(KNOWN_STILL_SIZES);
+const KNOWN_IMAGE_SET = new Set(KNOWN_IMAGE_SIZES);
+function isKnownBackdropSize(value) {
+	return KNOWN_BACKDROP_SET.has(value);
+}
+function isKnownLogoSize(value) {
+	return KNOWN_LOGO_SET.has(value);
+}
+function isKnownPosterSize(value) {
+	return KNOWN_POSTER_SET.has(value);
+}
+function isKnownProfileSize(value) {
+	return KNOWN_PROFILE_SET.has(value);
+}
+function isKnownStillSize(value) {
+	return KNOWN_STILL_SET.has(value);
+}
+/** True if `value` is in any documented size set. */
+function isKnownImageSize(value) {
+	return KNOWN_IMAGE_SET.has(value);
+}
+//#endregion
+exports.KNOWN_BACKDROP_SIZES = KNOWN_BACKDROP_SIZES;
+exports.KNOWN_IMAGE_SIZES = KNOWN_IMAGE_SIZES;
+exports.KNOWN_LOGO_SIZES = KNOWN_LOGO_SIZES;
+exports.KNOWN_POSTER_SIZES = KNOWN_POSTER_SIZES;
+exports.KNOWN_PROFILE_SIZES = KNOWN_PROFILE_SIZES;
+exports.KNOWN_STILL_SIZES = KNOWN_STILL_SIZES;
 exports.TMDBClient = TMDBClient;
 exports.TMDBError = TMDBError;
+exports.TMDBRateLimitError = TMDBRateLimitError;
 exports.TMDBRequestError = TMDBRequestError;
 exports.TMDBResponseError = TMDBResponseError;
 exports.buildImageUrl = buildImageUrl;
 exports.createTMDB = createTMDB;
+exports.isKnownBackdropSize = isKnownBackdropSize;
+exports.isKnownImageSize = isKnownImageSize;
+exports.isKnownLogoSize = isKnownLogoSize;
+exports.isKnownPosterSize = isKnownPosterSize;
+exports.isKnownProfileSize = isKnownProfileSize;
+exports.isKnownStillSize = isKnownStillSize;
+exports.isMovie = isMovie;
+exports.isMovieSearchResult = isMovieSearchResult;
+exports.isPerson = isPerson;
+exports.isPersonSearchResult = isPersonSearchResult;
+exports.isTV = isTV;
+exports.isTVSearchResult = isTVSearchResult;
 
 //# sourceMappingURL=index.cjs.map