@cinemacove/trakt-client

TypeScript client for the Trakt API, with automatic camelCase conversion, dual CJS/ESM output, and full type coverage.

Installation

npm install @cinemacove/trakt-client axios

axios is a peer dependency.

Usage

import { TraktClient } from '@cinemacove/trakt-client';

const trakt = new TraktClient({
    clientId: 'your_client_id',
    // accessToken: 'your_oauth_token', // optional, required for authenticated endpoints
});

Public endpoints (client ID only)

// Movies
const trending = await trakt.movies.getTrending({ limit: 10 });
const movie = await trakt.movies.getMovie('the-dark-knight-2008');
const ratings = await trakt.movies.getRatings('the-dark-knight-2008');

// Shows
const shows = await trakt.shows.getTrending({ limit: 10 });
const show = await trakt.shows.getShow('breaking-bad');

// Seasons & Episodes
const seasons = await trakt.seasons.getSeasons('breaking-bad');
const episode = await trakt.episodes.getEpisode('breaking-bad', 1, 1);

// People
const person = await trakt.people.getPerson('bryan-cranston');
const credits = await trakt.people.getMovieCredits('bryan-cranston');

// Search
const results = await trakt.search.textSearch('movie', 'batman begins', { limit: 5 });
const lookup = await trakt.search.idLookup('imdb', 'tt0372784');

// Calendars (public)
const airingShows = await trakt.calendars.getAllShows('2024-01-08', 7);
const releasingMovies = await trakt.calendars.getAllMovies('2024-01-08', 7);

// Comments, Lists, Countries, Languages, Networks, Genres, Certifications...
const genres = await trakt.genres.getMovieGenres();
const networks = await trakt.networks.getNetworks();
const countries = await trakt.countries.getMovieCountries();

Authenticated endpoints (OAuth access token)

const trakt = new TraktClient({
    clientId: 'your_client_id',
    accessToken: 'your_oauth_access_token',
});

// Sync — your watch data
const lastActivities = await trakt.sync.getLastActivities();
const watchedMovies = await trakt.sync.getWatchedMovies();
const history = await trakt.sync.getHistory('movies', undefined, { limit: 20 });
const ratings = await trakt.sync.getRatings('movies');
const watchlist = await trakt.sync.getWatchlist('movies');

// Users
const settings = await trakt.users.getSettings();
const profile = await trakt.users.getProfile('me');
const myLists = await trakt.users.getLists('me');

// Recommendations
const recommended = await trakt.recommendations.getMovies();

OAuth / Device authentication flow

// 1. Request a device code
const deviceCode = await trakt.authentication.getDeviceCode(clientId);
console.log(`Go to ${deviceCode.verificationUrl} and enter ${deviceCode.userCode}`);

// 2. Poll until the user authorises
const token = await trakt.authentication.pollDeviceToken({
    clientId,
    clientSecret,
    deviceCode: deviceCode.deviceCode,
});

// 3. Use the access token
const authedClient = new TraktClient({ clientId, accessToken: token.accessToken });

Extended info

Most endpoints accept an extended option:

const movie = await trakt.movies.getMovie('the-dark-knight-2008', { extended: 'full' });
// movie.overview, movie.runtime, movie.rating, etc.

const person = await trakt.people.getPerson('bryan-cranston', { extended: 'full' });
// person.biography, person.birthday, etc.

Filters

Movie/show list endpoints accept filter options:

const action = await trakt.movies.getTrending({
    genres: ['action', 'thriller'],
    years: '2020-2024',
    limit: 20,
});

Features

• 21 API groups — Movies, Shows, Seasons, Episodes, People, Search, Calendars, Comments, Lists, Sync, Users, Certifications, Genres, Languages, Countries, Networks, Notes, Recommendations, Scrobble, Checkin, Authentication
• Automatic camelCase conversion — Trakt's snake_case responses are transparently converted
• Dual CJS + ESM output with .d.ts declarations
• Strict TypeScript — all endpoints and response shapes are fully typed
• No magic — thin wrapper around axios with predictable behaviour

Development

# Install dependencies
npm install

# Typecheck
npm run typecheck

# Build (CJS + ESM)
npm run build

# Integration tests (requires a .env file — see .env.example)
npx vitest run

Running integration tests

Copy .env.example to .env and fill in your credentials:

TRAKT_CLIENT_ID=your_client_id_here
TRAKT_ACCESS_TOKEN=your_access_token_here   # optional, needed for sync/user tests

Get a client ID from trakt.tv/oauth/applications.

License

MIT