tmdb-kit 0.1.0-beta.0

package/README.md

@@ -0,0 +1,159 @@
+# tmdb-kit
+
+A tiny, typed, zero-runtime-dependency TMDB SDK for Node.js, Bun, Deno, and edge runtimes.
+
+This package intentionally does not generate code from OpenAPI. It ships a small hand-designed API surface for common TMDB workflows, plus a typed `request<T>()` escape hatch for endpoints that are not wrapped yet.
+
+## Features
+
+- Zero runtime dependencies.
+- Built with tsdown and published as ESM + CommonJS.
+- Uses only Web standard APIs: `fetch`, `Headers`, `URL`, and `AbortSignal`.
+- Works in Node.js 18+, Bun, Deno, Cloudflare Workers, Vercel Edge, and other fetch-compatible runtimes.
+- Typed resources for movies, TV, search, trending, people, genres, configuration, credits, videos, and images.
+- High-coverage unit tests with mocked fetch; no real TMDB requests in tests.
+
+## Install
+
+```bash
+npm install tmdb-kit
+```
+
+## Quick Start
+
+```ts
+import { createTMDB } from 'tmdb-kit'
+
+const tmdb = createTMDB({
+  accessToken: process.env.TMDB_ACCESS_TOKEN!,
+  defaultLanguage: 'en-US',
+})
+
+const popular = await tmdb.movies.popular({ page: 1 })
+const movie = await tmdb.movies.details(popular.results[0]!.id, {
+  appendToResponse: ['credits', 'videos'],
+})
+
+const posterUrl = tmdb.images.url(movie.poster_path, 'w500')
+```
+
+CommonJS:
+
+```js
+const { createTMDB } = require('tmdb-kit')
+
+const tmdb = createTMDB({ accessToken: process.env.TMDB_ACCESS_TOKEN })
+```
+
+Deno:
+
+```ts
+import { createTMDB } from 'npm:tmdb-kit'
+
+const tmdb = createTMDB({ accessToken: Deno.env.get('TMDB_ACCESS_TOKEN')! })
+```
+
+## Authentication
+
+The recommended option is TMDB's API Read Access Token:
+
+```ts
+createTMDB({ accessToken: 'tmdb-read-access-token' })
+```
+
+The legacy v3 `api_key` query parameter is also supported:
+
+```ts
+createTMDB({ apiKey: 'tmdb-v3-api-key' })
+```
+
+Exactly one of `accessToken` or `apiKey` is required.
+
+## Supported Resources
+
+```ts
+tmdb.movies.popular()
+tmdb.movies.topRated()
+tmdb.movies.nowPlaying()
+tmdb.movies.upcoming()
+tmdb.movies.details(550, { appendToResponse: ['credits', 'videos'] })
+tmdb.movies.credits(550)
+tmdb.movies.images(550)
+tmdb.movies.recommendations(550)
+tmdb.movies.similar(550)
+tmdb.movies.videos(550)
+
+tmdb.tv.popular()
+tmdb.tv.topRated()
+tmdb.tv.airingToday()
+tmdb.tv.onTheAir()
+tmdb.tv.details(1399)
+tmdb.tv.credits(1399)
+tmdb.tv.images(1399)
+tmdb.tv.recommendations(1399)
+tmdb.tv.similar(1399)
+tmdb.tv.videos(1399)
+
+tmdb.search.movies('Dune')
+tmdb.search.tv('Dark')
+tmdb.search.people('Sofia Coppola')
+tmdb.search.multi('Tom Hardy')
+
+tmdb.trending.all('week')
+tmdb.trending.movies('day')
+tmdb.trending.tv('day')
+tmdb.trending.people('week')
+
+tmdb.people.popular()
+tmdb.people.details(31)
+
+tmdb.genres.movies()
+tmdb.genres.tv()
+
+tmdb.configuration.details()
+tmdb.configuration.countries()
+tmdb.configuration.jobs()
+tmdb.configuration.languages()
+tmdb.configuration.primaryTranslations()
+tmdb.configuration.timezones()
+```
+
+For an endpoint that is not wrapped yet:
+
+```ts
+const response = await tmdb.request<{ results: unknown[] }>('/discover/movie', {
+  query: {
+    sort_by: 'popularity.desc',
+    with_genres: [28, 12],
+  },
+})
+```
+
+## Errors
+
+```ts
+import { TMDBResponseError } from 'tmdb-kit'
+
+try {
+  await tmdb.movies.popular()
+} catch (error) {
+  if (error instanceof TMDBResponseError) {
+    console.log(error.status, error.statusCode, error.statusMessage)
+  }
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run test:coverage
+npm run build
+```
+
+## References
+
+- [TMDB authentication](https://developer.themoviedb.org/docs/authentication-application)
+- [TMDB API reference](https://developer.themoviedb.org/reference/intro/getting-started)
+- [tsdown output formats](https://tsdown.dev/options/output-format)

package/dist/index.cjs

@@ -0,0 +1,465 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/errors.ts
+/** Base class for all SDK-originated errors. */
+var TMDBError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "TMDBError";
+	}
+};
+/** Thrown before a request is sent or when fetch itself rejects. */
+var TMDBRequestError = class extends TMDBError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "TMDBRequestError";
+	}
+};
+/** Thrown when TMDB returns a non-2xx response. */
+var TMDBResponseError = class extends TMDBError {
+	body;
+	headers;
+	requestId;
+	status;
+	statusCode;
+	statusMessage;
+	statusText;
+	url;
+	constructor(message, options) {
+		super(message);
+		this.name = "TMDBResponseError";
+		this.body = options.body;
+		this.headers = options.headers;
+		this.requestId = options.headers.get("x-request-id");
+		this.status = options.status;
+		this.statusText = options.statusText;
+		this.url = options.url;
+		const body = isErrorResponseBody(options.body) ? options.body : void 0;
+		this.statusCode = body?.status_code;
+		this.statusMessage = body?.status_message;
+	}
+};
+function createResponseError(options) {
+	return new TMDBResponseError((isErrorResponseBody(options.body) ? options.body : void 0)?.status_message ?? `${options.status} ${options.statusText}`.trim(), options);
+}
+function isErrorResponseBody(value) {
+	return typeof value === "object" && value !== null;
+}
+function appendQuery(url, query) {
+	for (const [key, value] of Object.entries(query)) {
+		if (value === void 0 || value === null) continue;
+		if (Array.isArray(value)) {
+			url.searchParams.set(key, value.map(String).join(","));
+			continue;
+		}
+		url.searchParams.set(key, String(value));
+	}
+}
+function withLanguage(defaults, query) {
+	const language = typeof query.language === "string" ? query.language : defaults.language;
+	return {
+		...query,
+		language
+	};
+}
+function withListDefaults(defaults, query) {
+	const region = typeof query.region === "string" ? query.region : defaults.region;
+	return {
+		...withLanguage(defaults, query),
+		region
+	};
+}
+function toCommaList(value) {
+	if (value === void 0) return;
+	return typeof value === "string" ? value : value.join(",");
+}
+function toId(value, name) {
+	if (!Number.isInteger(value) || value <= 0) throw new TMDBRequestError(`${name} must be a positive integer`);
+	return String(value);
+}
+function toSearchQuery(value) {
+	const query = value.trim();
+	if (query.length === 0) throw new TMDBRequestError("search query must not be empty");
+	return query;
+}
+function toTimeWindow(value) {
+	if (value !== "day" && value !== "week") throw new TMDBRequestError("timeWindow must be either \"day\" or \"week\"");
+	return value;
+}
+/**
+* Build a full TMDB image URL from the path returned by API payloads.
+* Returns null for nullish image paths so UI code can branch naturally.
+*/
+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}`}`;
+}
+function normalizeBaseUrl(baseUrl) {
+	return baseUrl.replace(/\/+$/, "");
+}
+//#endregion
+//#region src/http.ts
+var TMDBHttpClient = class {
+	defaults;
+	#apiKey;
+	#accessToken;
+	#baseUrl;
+	#fetch;
+	#headers;
+	constructor(options) {
+		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.#headers = options.headers;
+		this.defaults = {
+			imageBaseUrl: normalizeBaseUrl(options.imageBaseUrl ?? "https://image.tmdb.org/t/p"),
+			language: options.defaultLanguage,
+			region: options.defaultRegion
+		};
+	}
+	async get(path, options = {}) {
+		const url = this.#createUrl(path, options.query ?? {});
+		const headers = this.#createHeaders(options.headers);
+		let response;
+		try {
+			response = await this.#fetch(url, {
+				headers,
+				method: "GET",
+				signal: options.signal
+			});
+		} catch (error) {
+			throw new TMDBRequestError(`TMDB request failed: ${String(error)}`, { cause: error });
+		}
+		const body = await readJson(response);
+		if (!response.ok) throw createResponseError({
+			body,
+			headers: response.headers,
+			status: response.status,
+			statusText: response.statusText,
+			url
+		});
+		return body;
+	}
+	#createHeaders(headersInit) {
+		const headers = new Headers(this.#headers);
+		const requestHeaders = new Headers(headersInit);
+		headers.set("Accept", "application/json");
+		for (const [key, value] of requestHeaders) headers.set(key, value);
+		if (this.#accessToken !== void 0) headers.set("Authorization", `Bearer ${this.#accessToken}`);
+		return headers;
+	}
+	#createUrl(path, query) {
+		const relativePath = path.replace(/^\/+/, "");
+		const url = new URL(relativePath, `${this.#baseUrl}/`);
+		appendQuery(url, {
+			...query,
+			api_key: this.#apiKey
+		});
+		return url.toString();
+	}
+};
+async function readJson(response) {
+	const text = await response.text();
+	if (text.length === 0) return;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+function normalizeSecret(value) {
+	const secret = value?.trim();
+	return secret === "" ? void 0 : secret;
+}
+//#endregion
+//#region src/resources/configuration.ts
+var ConfigurationResource = class {
+	#transport;
+	constructor(transport) {
+		this.#transport = transport;
+	}
+	details() {
+		return this.#transport.get("/configuration");
+	}
+	countries() {
+		return this.#transport.get("/configuration/countries");
+	}
+	jobs() {
+		return this.#transport.get("/configuration/jobs");
+	}
+	languages() {
+		return this.#transport.get("/configuration/languages");
+	}
+	primaryTranslations() {
+		return this.#transport.get("/configuration/primary_translations");
+	}
+	timezones() {
+		return this.#transport.get("/configuration/timezones");
+	}
+};
+//#endregion
+//#region src/resources/genres.ts
+var GenresResource = class {
+	#transport;
+	constructor(transport) {
+		this.#transport = transport;
+	}
+	movies(options = {}) {
+		return this.#transport.get("/genre/movie/list", { query: withLanguage(this.#transport.defaults, { language: options.language }) });
+	}
+	tv(options = {}) {
+		return this.#transport.get("/genre/tv/list", { query: withLanguage(this.#transport.defaults, { language: options.language }) });
+	}
+};
+//#endregion
+//#region src/resources/images.ts
+var ImagesHelper = class {
+	#transport;
+	constructor(transport) {
+		this.#transport = transport;
+	}
+	url(path, size = "original") {
+		return buildImageUrl(path, size, { baseUrl: this.#transport.defaults.imageBaseUrl });
+	}
+};
+//#endregion
+//#region src/resources/movies.ts
+var MoviesResource = class {
+	#transport;
+	constructor(transport) {
+		this.#transport = transport;
+	}
+	popular(options = {}) {
+		return this.#transport.get("/movie/popular", { query: movieListQuery(this.#transport, options) });
+	}
+	topRated(options = {}) {
+		return this.#transport.get("/movie/top_rated", { query: movieListQuery(this.#transport, options) });
+	}
+	nowPlaying(options = {}) {
+		return this.#transport.get("/movie/now_playing", { query: movieListQuery(this.#transport, options) });
+	}
+	upcoming(options = {}) {
+		return this.#transport.get("/movie/upcoming", { query: movieListQuery(this.#transport, options) });
+	}
+	details(movieId, options = {}) {
+		return this.#transport.get(`/movie/${toId(movieId, "movieId")}`, { query: withLanguage(this.#transport.defaults, {
+			append_to_response: toCommaList(options.appendToResponse),
+			language: options.language
+		}) });
+	}
+	credits(movieId, options = {}) {
+		return this.#transport.get(`/movie/${toId(movieId, "movieId")}/credits`, { query: withLanguage(this.#transport.defaults, { language: options.language }) });
+	}
+	images(movieId, options = {}) {
+		return this.#transport.get(`/movie/${toId(movieId, "movieId")}/images`, { query: withLanguage(this.#transport.defaults, {
+			include_image_language: toCommaList(options.includeImageLanguage),
+			language: options.language
+		}) });
+	}
+	recommendations(movieId, options = {}) {
+		return this.#transport.get(`/movie/${toId(movieId, "movieId")}/recommendations`, { query: movieListQuery(this.#transport, options) });
+	}
+	similar(movieId, options = {}) {
+		return this.#transport.get(`/movie/${toId(movieId, "movieId")}/similar`, { query: movieListQuery(this.#transport, options) });
+	}
+	videos(movieId, options = {}) {
+		return this.#transport.get(`/movie/${toId(movieId, "movieId")}/videos`, { query: withLanguage(this.#transport.defaults, { language: options.language }) });
+	}
+};
+function movieListQuery(transport, options) {
+	return withListDefaults(transport.defaults, {
+		language: options.language,
+		page: options.page,
+		region: options.region
+	});
+}
+//#endregion
+//#region src/resources/people.ts
+var PeopleResource = class {
+	#transport;
+	constructor(transport) {
+		this.#transport = transport;
+	}
+	popular(options = {}) {
+		return this.#transport.get("/person/popular", { query: peopleListQuery(this.#transport, options) });
+	}
+	details(personId, options = {}) {
+		return this.#transport.get(`/person/${toId(personId, "personId")}`, { query: withLanguage(this.#transport.defaults, { language: options.language }) });
+	}
+};
+function peopleListQuery(transport, options) {
+	return withLanguage(transport.defaults, {
+		language: options.language,
+		page: options.page
+	});
+}
+//#endregion
+//#region src/resources/search.ts
+var SearchResource = class {
+	#transport;
+	constructor(transport) {
+		this.#transport = transport;
+	}
+	movies(query, options = {}) {
+		return this.#transport.get("/search/movie", { query: movieSearchQuery(this.#transport, query, options) });
+	}
+	tv(query, options = {}) {
+		return this.#transport.get("/search/tv", { query: tvSearchQuery(this.#transport, query, options) });
+	}
+	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) });
+	}
+};
+function movieSearchQuery(transport, query, options) {
+	return withListDefaults(transport.defaults, {
+		include_adult: options.includeAdult,
+		language: options.language,
+		page: options.page,
+		primary_release_year: options.primaryReleaseYear,
+		query: toSearchQuery(query),
+		region: options.region,
+		year: options.year
+	});
+}
+function tvSearchQuery(transport, query, options) {
+	return withLanguage(transport.defaults, {
+		first_air_date_year: options.firstAirDateYear,
+		include_adult: options.includeAdult,
+		language: options.language,
+		page: options.page,
+		query: toSearchQuery(query),
+		year: options.year
+	});
+}
+function commonSearchQuery(transport, query, options) {
+	return withLanguage(transport.defaults, {
+		include_adult: options.includeAdult,
+		language: options.language,
+		page: options.page,
+		query: toSearchQuery(query)
+	});
+}
+//#endregion
+//#region src/resources/trending.ts
+var TrendingResource = class {
+	#transport;
+	constructor(transport) {
+		this.#transport = transport;
+	}
+	all(timeWindow = "day", options = {}) {
+		return this.#transport.get(`/trending/all/${toTimeWindow(timeWindow)}`, { query: withLanguage(this.#transport.defaults, { language: options.language }) });
+	}
+	movies(timeWindow = "day", options = {}) {
+		return this.#transport.get(`/trending/movie/${toTimeWindow(timeWindow)}`, { query: withLanguage(this.#transport.defaults, { language: options.language }) });
+	}
+	tv(timeWindow = "day", options = {}) {
+		return this.#transport.get(`/trending/tv/${toTimeWindow(timeWindow)}`, { query: withLanguage(this.#transport.defaults, { language: options.language }) });
+	}
+	people(timeWindow = "day", options = {}) {
+		return this.#transport.get(`/trending/person/${toTimeWindow(timeWindow)}`, { query: withLanguage(this.#transport.defaults, { language: options.language }) });
+	}
+};
+//#endregion
+//#region src/resources/tv.ts
+var TVResource = class {
+	#transport;
+	constructor(transport) {
+		this.#transport = transport;
+	}
+	popular(options = {}) {
+		return this.#transport.get("/tv/popular", { query: tvListQuery(this.#transport, options) });
+	}
+	topRated(options = {}) {
+		return this.#transport.get("/tv/top_rated", { query: tvListQuery(this.#transport, options) });
+	}
+	airingToday(options = {}) {
+		return this.#transport.get("/tv/airing_today", { query: tvListQuery(this.#transport, options) });
+	}
+	onTheAir(options = {}) {
+		return this.#transport.get("/tv/on_the_air", { query: tvListQuery(this.#transport, options) });
+	}
+	details(seriesId, options = {}) {
+		return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}`, { query: withLanguage(this.#transport.defaults, {
+			append_to_response: toCommaList(options.appendToResponse),
+			language: options.language
+		}) });
+	}
+	credits(seriesId, options = {}) {
+		return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/credits`, { query: withLanguage(this.#transport.defaults, { language: options.language }) });
+	}
+	images(seriesId, options = {}) {
+		return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/images`, { query: withLanguage(this.#transport.defaults, {
+			include_image_language: toCommaList(options.includeImageLanguage),
+			language: options.language
+		}) });
+	}
+	recommendations(seriesId, options = {}) {
+		return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/recommendations`, { query: tvListQuery(this.#transport, options) });
+	}
+	similar(seriesId, options = {}) {
+		return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/similar`, { query: tvListQuery(this.#transport, options) });
+	}
+	videos(seriesId, options = {}) {
+		return this.#transport.get(`/tv/${toId(seriesId, "seriesId")}/videos`, { query: withLanguage(this.#transport.defaults, { language: options.language }) });
+	}
+};
+function tvListQuery(transport, options) {
+	return withLanguage(transport.defaults, {
+		language: options.language,
+		page: options.page
+	});
+}
+//#endregion
+//#region src/client.ts
+/**
+* Main SDK entry point.
+*
+* Resource properties are intentionally small and explicit. The SDK focuses on
+* common TMDB workflows first, while request<T>() keeps uncommon endpoints easy
+* to call without waiting for a generated surface area.
+*/
+var TMDBClient = class {
+	configuration;
+	genres;
+	images;
+	movies;
+	people;
+	search;
+	trending;
+	tv;
+	#http;
+	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);
+	}
+	request(path, options) {
+		return this.#http.get(path, options);
+	}
+};
+function createTMDB(options) {
+	return new TMDBClient(options);
+}
+//#endregion
+exports.TMDBClient = TMDBClient;
+exports.TMDBError = TMDBError;
+exports.TMDBRequestError = TMDBRequestError;
+exports.TMDBResponseError = TMDBResponseError;
+exports.buildImageUrl = buildImageUrl;
+exports.createTMDB = createTMDB;
+
+//# sourceMappingURL=index.cjs.map