@vo1x/tmdb

---

Features

- Type-Safe: Automatically generated types from the TMDb OpenAPI spec ensure your code is correct.
- Modern: Uses modern JavaScript (ES2022) and works in Node.js 18+ and browsers with native fetch.
- Lightweight: Minimal dependencies and tree-shakeable to keep your project lean.
- Comprehensive: Covers all major endpoints: movies, TV, search, trending, and configuration.
- Clean Errors: Provides structured, useful errors for easier debugging.

Installation

``bash


npm

`typescript
import { TMDB } from "@vo1x/tmdb";

const tmdb = new TMDB({
apiKey: process.env.TMDB_API_KEY!, // Get a key at https://www.themoviedb.org/settings/api
});

// Get movie details
const movie = await tmdb.movies.get(550); // Fight Club
console.log(${movie.title} (${movie.releaseDate}) - ${movie.voteAverage}/10);

// Search for movies
const searchResults = await tmdb.search.movies("inception");
console.log(Found ${searchResults.totalResults} movies.);
`

API Reference

$3

`typescript
// Get movie details
const movie = await tmdb.movies.get(550, { language: "en-US" });

// Get credits
const credits = await tmdb.movies.credits(550);

// Get images
const images = await tmdb.movies.images(550);

// Get recommendations and similar movies
const recommendations = await tmdb.movies.recommendations(550);
const similar = await tmdb.movies.similar(550);
`

$3

`typescript
// Get TV show details
const show = await tmdb.tv.get(1399); // Game of Thrones

// Get credits, images, recommendations, etc.
const credits = await tmdb.tv.credits(1399);
const images = await tmdb.tv.images(1399);
`

$3

`typescript
// Search for movies, TV shows, or people
const movies = await tmdb.search.movies("batman", { page: 1, includeAdult: false });
const tvShows = await tmdb.search.tv("breaking bad");
const people = await tmdb.search.people("leonardo dicaprio");

// Search across all types
const results = await tmdb.search.multi("marvel");
`

$3

`typescript
// Get daily or weekly trending content
const dailyTrending = await tmdb.trending.daily();
const weeklyTrending = await tmdb.trending.weekly();
`

$3

`typescript
// Get API configuration, countries, languages, etc.
const config = await tmdb.configuration.get();
const countries = await tmdb.configuration.countries();
`


$3

`typescript
// Get person details
const person = await tmdb.person.get(287); // Christian Bale

// Get images and combined credits
const images = await tmdb.person.images(287);
const credits = await tmdb.person.combinedCredits(287);
`

Error Handling

The SDK throws a TMDBError for API or network issues.

`typescript
import { TMDB, TMDBError } from "@vo1x/tmdb";

try {
await tmdb.movies.get(999999999); // Invalid ID
} catch (error) {
if (error instanceof TMDBError) {
console.error(Error ${error.status}: ${error.message});
// error.code contains the TMDb-specific error code
}
}
`

Examples

The examples/ directory contains more detailed examples for each module.

$3

`bash


Run a specific example

`typescript
const tmdb = new TMDB({
apiKey: "your_api_key", // Required
baseUrl?: "custom_url", // Optional
language?: "en-US", // Optional
});
``

Contributing

Contributions are welcome. Feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License.