Changelog

🚀 1.21.1 - 18 April 2026

• 🤖 LLMS - added new llms.txt and llms-full.txt files for better AI integration

🚀 1.21.0 - 15 April 2026

✨ New

• Pagination helpers — four new exported utilities simplify working with any paginated TMDB endpoint: paginate() for lazy async iteration, fetchAllPages() for collecting every page into a flat array, hasNextPage() / hasPreviousPage() for UI navigation, and getPageInfo() for structured pagination metadata. fetchAllPages() also supports maxPages and deduplicateBy for safer bulk fetches on popularity-sorted endpoints where TMDB can return cross-page duplicates.

import { fetchAllPages, getPageInfo, paginate } from "@lorenzopant/tmdb";

for await (const page of paginate((p) => tmdb.search.movies({ query: "batman", page: p }))) {
	console.log(getPageInfo(page));
}

const movies = await fetchAllPages((p) => tmdb.movie_lists.now_playing({ page: p }), {
	maxPages: 3,
	deduplicateBy: (movie) => movie.id,
});

• Opt-in automatic retry with backoff — new retry option automatically retries transient failures with full-jitter exponential backoff. Pass true for defaults (max_retries: 3, base_delay_ms: 500, max_delay_ms: 30_000) or provide a RetryOptions object with a custom shouldRetry predicate. By default, the client retries HTTP 5xx responses and network/fetch failures, applies to both reads and mutations, and respects any configured rate limit budget.

import { TMDB, TMDBError } from "@lorenzopant/tmdb";

const tmdb = new TMDB(token, { retry: true });

const custom = new TMDB(token, {
	retry: {
		max_retries: 5,
		base_delay_ms: 200,
		shouldRetry: (error, attempt) => {
			if (error instanceof TMDBError) return error.http_status_code >= 500 || error.http_status_code === 429;
			return attempt <= 2;
		},
	},
});

📦 Package

• Node.js 20+ is now required — the repo and docs now target Node >=20, with engines updated in the workspace and a new root .nvmrc set to 20.

📖 Docs

• New Pagination guide covering lazy iteration, full-page collection, deduplication, and page metadata helpers.
• New Retry guide covering defaults, custom predicates, backoff behaviour, and interaction with rate limiting.
• Options page updated with the new retry option reference.

🚀 1.20.2 - 13 April 2026

✨ New

• Image language priority — new image_language_priority option inside images config lets consumers define a per-collection language fallback order when autocomplete_paths is enabled. TMDB image arrays (e.g. posters, backdrops) are reordered so the best match according to the priority list appears first. No items are dropped — only their order changes.

const tmdb = new TMDB(token, {
	images: {
		autocomplete_paths: true,
		image_language_priority: {
			// 1. textless posters  2. English  3. any remaining
			posters: ["null", "en", "*"],
		},
	},
});

Special values: "null" matches untagged images (iso_639_1 == null), "*" is a catch-all that consumes all remaining items.

• auto_include_image_language — companion boolean option that derives include_image_language from the language codes in image_language_priority and automatically injects it into every .images() request. This ensures TMDB returns the language variants the priority config needs to sort — no manual include_image_language calls required. An explicit include_image_language at the call site always takes precedence.

const tmdb = new TMDB(token, {
	images: {
		autocomplete_paths: true,
		image_language_priority: { posters: ["null", "en", "*"] },
		auto_include_image_language: true,
		// → automatically sends include_image_language: ["null", "en"] on every .images() call
	},
});

Applies to movies.images(), tv_series.images(), tv_seasons.images(), tv_episodes.images(), collections.images(), and companies.images().

📖 Docs

• Images Configuration page updated with new image_language_priority and auto_include_image_language sections.

🚀 1.20.1 - 7 April 2026

✨ New

• Opt-in in-memory response cache — new cache option caches GET responses in memory with a configurable TTL. Pass true for defaults (5-minute TTL, no size limit) or a CacheOptions object for a custom budget. Mutations are never cached. Disabled by default — no behaviour change for existing consumers.

// Default TTL (5 minutes)
const tmdb = new TMDB(token, { cache: true });

// Custom TTL, bounded memory, and per-endpoint exclusions
const tmdb = new TMDB(token, {
	cache: {
		ttl: 60_000,
		max_size: 500,
		excluded_endpoints: ["/trending", /\/discover\//],
	},
});

• tmdb.cache controls — invalidate a single cache entry after a mutation, wipe everything on sign-out, or inspect the current size at runtime:

tmdb.cache?.invalidate("/movie/now_playing", { language: "en-US" });
tmdb.cache?.clear();
console.log(tmdb.cache?.size);

📦 NPM Package

• Added minification option to reduce package size (no changes to the public API)
• Updated README for NPM package

📖 Docs

• New Response Caching guide covering: enabling with true, CacheOptions reference, how cache keys work, lazy TTL eviction, max_size FIFO eviction, excluded_endpoints, the tmdb.cache invalidation API, interaction with deduplication, and typical use cases.
• Features and Options pages updated with response caching sections.

🚀 1.20.0 - 7 April 2026

✨ New

• Lists API (v3) — full CRUD for TMDB v3 lists via tmdb.lists: create, details, update, clear, delete, add items, remove items, and list item details endpoints all supported with full typings and pagination where applicable. Note that v3 lists are distinct from v4 lists (managed via tmdb.v4.lists) and have different features and limitations — refer to the Lists API documentation for details on each version.
• Lists API (v4) — full CRUD for TMDB v4 lists via tmdb.v4.lists:
• Guest Sessions API — read rated content for a guest session via tmdb.guest_sessions:
• Opt-in auto rate limiting — new rate_limit option automatically queues requests to stay within TMDB's API budget using a sliding-window algorithm. Pass true for defaults (~40 req / s) or a RateLimitOptions object for a custom budget. Applies to both read and mutation requests. Disabled by default — no behaviour change for existing consumers.

// Default limits (~40 req / s)
const tmdb = new TMDB(token, { rate_limit: true });

// Custom budget
const tmdb = new TMDB(token, { rate_limit: { max_requests: 20, per_ms: 1_000 } });

Requests exceeding the budget are held in a FIFO queue and dispatched as a smooth drip — as soon as any slot frees up, the next caller proceeds. No manual batching or sleep() calls needed.

📖 Docs

• New Rate Limiting guide covering: enabling with true, custom budgets, how the sliding-window and pacing work, interaction with deduplication, and a bulk-fetch use-case example.
• New v4 Lists types page.
• Features and Options pages updated with rate limiting sections.

🚀 1.19.0 - 5 April 2026

✨ New

• v4 Auth API — tmdb.v4.auth now exposes the full TMDB v4 authentication flow:
  • create_request_token() — generate a request token for the user to approve (step 1).
  • create_access_token() — exchange an approved request token for a permanent user access token (step 3).
  • delete_access_token() — revoke an access token to log a user out.

const { request_token } = await tmdb.v4.auth.create_request_token({
	redirect_to: "https://yourapp.com/callback",
});
// redirect user → https://www.themoviedb.org/auth/access?request_token={request_token}
const { access_token, account_id } = await tmdb.v4.auth.create_access_token({ request_token });

🚀 1.18.1 - 4 April 2026

✨ New

• Image path autocompletion — new opt-in images.autocomplete_paths option automatically rewrites relative TMDB image paths in API responses to full URLs. Affects poster_path, backdrop_path, profile_path, logo_path, still_path, and image collection file_path fields. Disabled by default to preserve original response semantics.

const tmdb = new TMDB(token, {
	images: {
		autocomplete_paths: true,
		default_image_sizes: { posters: "original" },
	},
});

const movie = await tmdb.movies.details({ movie_id: 550 });
console.log(movie.poster_path);
// → "https://image.tmdb.org/t/p/original/e1mjopzAS2KNsvpbpahQ1a6SkSn.jpg"

🚀 1.18.0 - 1 April 2026

✨ New

• Authentication API — access TMDB authentication endpoints via tmdb.authentication
• Account API — manage account details, favourites, watchlists, and rated items via tmdb.account

🐞 Bug Fixes

• Standalone classes now work as documented — MoviesAPI, SearchAPI, GenresAPI, and all other endpoint classes can now be instantiated directly with an access token (e.g. new MoviesAPI("your_token")). Previously the constructor required an internal ApiClient instance, causing a runtime error. All endpoint classes are also now correctly exported from the package root.

🧪 Tests

• Improved test coverage across the SDK

🚀 1.17.6 - 31 March 2026

🔧 Internal

• Migrated build tooling from tsup to tsdown. tsup is no longer actively maintained — its README now explicitly recommends tsdown as the successor. No changes to the SDK.

🚀 1.17.5 - 31 March 2026

🔧 Internal

• Internal refactoring/updates of tooling — no changes to the SDK.

🚀 1.17.4 - 30 March 2026

✨ New

• Request interceptors — hook into the request lifecycle before any TMDB API call is made. Pass a single RequestInterceptor or an array; each interceptor receives a RequestInterceptorContext (endpoint, params, method) and may return a modified context to override the endpoint or params, or void to leave the request unchanged. Async interceptors are fully supported and awaited in order.
• Response interceptors — two new hooks under interceptors.response:
  • onSuccess — called after every successful response, before data is returned to the caller. Designed for side effects such as logging, caching, or image URL enrichment. Must not change the shape of the returned data.
  • onError — called after a TMDBError is created. Receives a fully-typed TMDBError for side effects (Sentry, toast notifications, etc.). The error is always re-thrown after the interceptor runs.

const tmdb = new TMDB(token, {
	interceptors: {
		request: [
			(ctx) => console.log(`→ ${ctx.method} ${ctx.endpoint}`),
			(ctx) => ({ ...ctx, params: { ...ctx.params, include_adult: false } }),
		],
		response: {
			onSuccess: (data) => myCache.set(data),
			onError: (error) => Sentry.captureException(error),
		},
	},
});

📖 Docs

• New Interceptors guide covering request and response hooks with full examples.
• New Interceptors types page documenting RequestInterceptorContext, RequestInterceptor, ResponseSuccessInterceptor, and ResponseErrorInterceptor.

🚀 1.17.3 - 29 March 2026

🐞 Bug Fixes

• Path params leaking into query strings - path parameters (e.g. movie_id, season_number, etc.) were mistakenly being included in the query string of requests instead of being injected into the URL path. This has been fixed by centralizing all parameter serialization logic in the ApiClient, ensuring that path params are correctly placed in the URL and not duplicated in the query string.
• Malformed route in tv_episodes.changes() — the generated path contained double slashes (/tv//episode/{id}//changes). Now correctly builds /tv/episode/{episode_id}/changes.
• | null removed from image path types — poster_path, backdrop_path, still_path, logo_path, profile_path, and runtime fields no longer include | null in their types. The client's sanitizeNulls already converts null → undefined at runtime, so the static types now match the actual runtime behaviour.

✨ New

• Image path type guards — five new exported helpers for narrowing image-path fields on unknown objects: hasPosterPath, hasBackdropPath, hasProfilePath, hasStillPath, hasLogoPath.
• New Utility types page documenting the type guards and other utility types exported by the package.

🧪 Tests

• Closed remaining coverage gaps across the SDK; added regression tests for array-valued params to guard deduplication key stability and query serialization alignment.

🚀 1.17.2 - 28 March 2026

📦 Package

• Switched build tooling from tsc to tsup — the published package now ships 2 files instead of 142, with full tree-shaking eliminating dead runtime code.

🚀 1.17.1 - 28 March 2026

⚡ Performance

• Request deduplication — concurrent identical requests (same endpoint + parameters) now share a single in-flight fetch. All callers resolve from the same Promise with zero extra network round-trips. Opt out globally with deduplication: false in TMDBOptions.

📖 Docs

• New Features page — one-stop overview of all built-in client capabilities: authentication, request deduplication, null sanitisation, default options, image URL builder, error handling, and logging.

🚀 1.17.0 - 27 March 2026

✨ New

• People API — full first-class support for TMDB person-specific endpoints via tmdb.people (details, credits, images, translations, external IDs, and more)
• Authentication guide — new documentation covering Bearer token vs v3 API key usage, detection logic, and environment variable setup

🔐 Auth

• The client now supports both Bearer tokens (JWT Read Access Tokens) and v3 API keys — the correct auth method is detected automatically based on the token structure
• JWT tokens continue to be sent as Authorization: Bearer <token>
• Plain v3 API keys are now correctly appended as ?api_key=<key> query parameter instead of being sent (incorrectly) as a Bearer header

🐞 Bug Fixes

• Fixed broken links in TV Series Lists API docs and related type pages (404s caused by incorrect route paths)
• Fixed isJwt() incorrectly returning false for expired tokens, which would have caused a valid JWT to be silently sent as an api_key query parameter (leaking it in URLs) instead of as a Bearer header
• Unit tests no longer throw at startup when TMDB_BEARER_TOKEN is not set in the environment — they use a hardcoded mock JWT since fetch is fully mocked

🚀 1.16.0 - 23 March 2026

✨ New

• People Lists API — get a paginated list of people ordered by TMDB popularity
• Reviews API — fetch full details of a single TMDB review by its review ID

🧪 Tests

• Split tests into unit and integration tests for easier contributions
• Added more unit tests

🐞 Bug Fixes

• include_image_language now accepts an array of languages (e.g. ["en", "null"]) instead of a comma-separated string
• series_id was incorrectly destructured and being passed into query params
• withDefaults() returning undefined when passed undefined as value

🚀 1.15.1 - 21 March 2026

• 🧪 Improved test coverage
• 📦 Attempt to reduce npm package size

🚀 1.15.0 - 21 March 2026

• Trending API — get trending movies, TV shows, and people for a given time window ("day" or "week")
• AI SKILL.md file for better ai development of this package.

🚀 1.14.1 - 20 March 2026

• search.tv_series() — search for TV shows by their original, translated, and also known as names
• search.multi() — search across movies, TV shows, and people in a single request, with results discriminated by media_type

🚀 1.14.0 - 20 March 2026

• Logging support — enable the built-in console logger with logger: true or pass a custom TMDBLoggerFn for full control over request, response, and error logging
• TVSeasons API — access detailed information about TV show seasons, including episodes, air dates, and more

🚀 1.13.1 - 14 March 2026

• Introducing in-documentation changelog
• Refactored types internally for better code organization

🚀 1.13.0 - 13 March 2026

• TV Episode Groups API