TMDB SDK

A complete, fully-typed TypeScript client for the TMDB API v3. All 25 namespaces, zero runtime dependencies beyond axios.

bun add @carlosnc/tmdb-sdk
Copy

Authentication

import { TMDBClient } from "@carlosnc/tmdb-sdk";

const client = new TMDBClient({
  accessToken: process.env.TMDB_TOKEN, // recommended
});

// or with an API key
const client2 = new TMDBClient({
  apiKey: process.env.TMDB_KEY,
});
Copy

Get credentials from your TMDB API settings.

Custom HTTP Adapters

The SDK uses an HttpClient interface for all requests. The default FetchAdapter uses native fetch(). Swap it out by implementing the interface:

import { type HttpClient, TMDBClient } from "@carlosnc/tmdb-sdk";

class AxiosAdapter implements HttpClient {
  async get<T>(url: string, config?: HttpRequestConfig) {
    const res = await axios.get<T>(url, { params: config?.params, headers: config?.headers, signal: config?.signal });
    return { data: res.data, status: res.status, statusText: res.statusText, headers: res.headers as Record<string, string> };
  }
  // post, put, delete similarly...
}

const client = new TMDBClient({
  accessToken: process.env.TMDB_TOKEN,
  httpClient: new AxiosAdapter(),
});
Copy

When passing a custom httpClient, auth headers/params and retry are not injected automatically — your adapter handles those itself.

Framework Adapters

Proxy TMDB API requests through your own server to keep your token server-side.

SvelteKit

// src/routes/api/tmdb/[...path]/+server.ts
import { createSvelteKitHandler } from "@carlosnc/tmdb-sdk/sveltekit";
import { TMDB_TOKEN } from "$env/static/private";

const tmdb = createSvelteKitHandler({ token: TMDB_TOKEN });

export const GET  = tmdb;
export const POST = tmdb;
export const PUT = tmdb;
export const PATCH = tmdb;
export const DELETE = tmdb;
Copy

curl http://localhost:5173/api/tmdb/movie/550
Copy

Next.js (App Router)

// app/api/tmdb/[...path]/route.ts
import { createNextJsHandler } from "@carlosnc/tmdb-sdk/nextjs";

const tmdb = createNextJsHandler({ token: process.env.TMDB_TOKEN! });

export const GET  = tmdb;
export const POST = tmdb;
export const PUT = tmdb;
export const PATCH = tmdb;
export const DELETE = tmdb;
Copy

curl http://localhost:3000/api/tmdb/movie/550
Copy

Both adapters forward query parameters, set the Authorization: Bearer header, and surface TMDB's Cache-Control on GET responses.

Quick Start

const client = new TMDBClient({ accessToken: process.env.TMDB_TOKEN });

// System config
const config = await client.configuration.getDetails();

// Account
const account = await client.account.getDetails();

// Movie details
const movie = await client.movie.getDetails(550);

// TV series with season
const season = await client.tv.getSeasonDetails(1399, 1);

// Search
const results = await client.search.getMovies({ query: "Matrix" });

// Watch providers
const regions = await client.watchProviders.getAvailableRegions();
Copy

Movie Example

const client = new TMDBClient({ accessToken: process.env.TMDB_TOKEN });

const movie = await client.movie.getDetails(550);

console.log("Title:", movie.title);
console.log("Tagline:", movie.tagline);
console.log("Release Date:", movie.release_date);
console.log("Runtime:", movie.runtime, "mins");
console.log("Genres:", movie.genres?.map((g) => g.name).join(", "));
console.log("Overview:", movie.overview);
Copy

Examples

Browse runnable examples in the examples/ directory:

File	Demonstrates
account.ts	Account details, favorites, watchlist
authentication.ts	API key validation, request tokens, guest sessions
certification.ts	Movie and TV certifications by country
collection.ts	Collection details, images, translations
company.ts	Production company details, logos, alternative names
configuration.ts	API config, image URL builder, countries, languages
credit.ts	Credit lookup by credit ID
discover.ts	Movie and TV discovery with filters
find.ts	External ID lookup (IMDb, TVDB, etc.)
genre.ts	Movie and TV genre lists
keyword.ts	Keyword details and associated movies
movie.ts	Movie details with append_to_response
pagination.ts	Page-by-page and auto-pagination
person.ts	Popular people, details, combined credits
review.ts	Review details by review ID
search.ts	Movie, multi, and person search
trending.ts	Trending movies, TV, and people
tv-series.ts	TV series and season details
watch-providers.ts	Available regions, streaming providers

bun --env-file=.env run examples/movie.ts
Copy

Namespaces

Client	Key Methods
client.account	favorites, watchlist, ratings, lists
client.accountV4	v4 favorites, watchlist, rated, lists
client.authV4	v4 request token, access token, logout
client.authentication	sessions, request tokens, guest sessions, key validation
client.certification	movie and TV certifications
client.changes	movie, TV, and person change log
client.collection	collection details, images, translations
client.credit	credit details by ID
client.company	company details, alternative names, images
client.configuration	API and image configuration
client.discover	movie and TV discovery with filters
client.find	find by external IDs
client.genre	movie and TV genre lists
client.guestSession	guest session rated movies/TV/episodes
client.keyword	keyword details and movies
client.list	create, read, update, delete lists
client.listV4	v4 list CRUD and item management
client.movie	details, credits, images, videos, ratings, watch providers, recommendations, similar, and more
client.network	network details and alternative names
client.person	details, credits, external IDs, images, tagged images, changes
client.review	review details
client.search	multi, movie, TV, person, collection, company, keyword
client.trending	trending movies, TV, people (day/week)
client.tv	series, season, and episode details, credits, images, videos, ratings, watch providers, episode groups, and more
client.watchProviders	available regions, movie providers, TV providers

Development

# Install dependencies
bun install

# Run tests (mocked by default; set TMDB_TOKEN for live API tests)
bun test

# Type-check
bun run typecheck

# Run examples (requires TMDB_TOKEN in .env or --env-file)
bun --env-file=.env run examples/movie.ts

# Generate API documentation
bun run docs
Copy

Project Structure

src/
├── client.ts            # TMDBClient — wires all sub-clients
├── index.ts             # Barrel exports
├── client/              # One directory per namespace
│   ├── account/
│   ├── account-v4/
│   ├── auth-v4/
│   ├── authentication/
│   ├── certification/
│   ├── changes/
│   ├── collection/
│   ├── company/
│   ├── configuration/
│   ├── credit/
│   ├── discover/
│   ├── find/
│   ├── genre/
│   ├── guest-session/
│   ├── keyword/
│   ├── list/
│   ├── list-v4/
│   ├── movie/
│   ├── network/
│   ├── person/
│   ├── review/
│   ├── search/
│   ├── trending/
│   ├── tv/
│   └── watch-providers/
└── types/               # TypeScript interfaces for every endpoint
Copy

Resources

• TMDB API Reference — Getting Started
• TMDB API Docs — Getting Started
• TMDB API v3 vs v4 Comparison

---

Carlos Costa @ 2026