@lorenzopant/tmdb 0.0.2

package/.env

@@ -0,0 +1 @@
+TMDB_ACCESS_TOKEN=eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJlYWQ5ZGI4NTUwYmNlM2RmYmNmZTQ3YjRjNWU2ZGI3OSIsIm5iZiI6MTYxMjE5OTAwOC4xMDcsInN1YiI6IjYwMTgzNDYwYmIxMDU3MDAzZjk1ZThlZCIsInNjb3BlcyI6WyJhcGlfcmVhZCJdLCJ2ZXJzaW9uIjoxfQ.-hv_iM_NKC9UWl3XgD8W-E6jzVo5bw8yUcW_rCCpJbU

package/.prettierrc

@@ -0,0 +1,5 @@
+{
+    "printWidth": 140,
+    "tabWidth": 4,
+    "useTabs": true
+}

package/.release-it.json

@@ -0,0 +1,8 @@
+{
+  "plugins": {
+    "release-it-pnpm": {}
+  },
+  "git": {
+    "commitMessage": "chore: release v${version}"
+  }
+}

package/README.md

@@ -0,0 +1,153 @@
+# TMDB API TS
+
+A **TypeScript-first** lightweight client for [The Movie Database (TMDB)](https://developer.themoviedb.org/docs/getting-started) API.
+
+🚧🚧🚧🚧🚧🚧 **WIP** This package is still cookin. It will be updated regularly with new features.
+Feel free to open pull requests on the project repository here:
+[tmdb-api-ts](https://github.com/lorenzopantano/tmdb-api-ts)
+
+- 📦 Full TypeScript support
+- 🔥 Simple and tiny wrapper
+- 🚀 Designed for server-side and frontend use (React, Vue, etc.)
+- 🛡️ Proper error handling with `TMDBError`
+
+---
+
+## Installation
+
+```bash
+npm install tmdb-api-ts
+```
+
+or
+
+```bash
+yarn add tmdb-api-ts
+```
+
+---
+
+## Usage
+
+```typescript
+import { TMDB } from 'tmdb-api-ts';
+
+const tmdb = new TMDB('your_access_token');
+
+async function searchMovies() {
+  try {
+    const movies = await tmdb.search.movies({ query: 'Fight Club' });
+    console.log(movies);
+  } catch (error) {
+    if (error instanceof TMDBError) {
+      console.error('TMDB Error:', error.message);
+      console.error('HTTP Status:', error.http_status_code);
+      console.error('TMDB Status Code:', error.tmdb_status_code);
+    } else {
+      console.error('Unknown error:', error);
+    }
+  }
+}
+
+searchMovies();
+```
+
+---
+
+## API
+
+### `TMDB`
+
+The main client class. **Each API method supports all the parameters supported by TMDB API**, for example the search method supports: query, language, region, year, primary_release_year and so on...
+
+#### Constructor
+
+```typescript
+const tmdb = new TMDB(accessToken: string);
+```
+
+- `accessToken`: **required**. Your TMDB API v4 access token.
+
+---
+
+### `Search`
+
+Search for movies:
+
+```typescript
+tmdb.search.movies("Fight Club");
+```
+
+Returns a **typed response** containing movies.
+
+---
+
+### `Movie Lists`
+
+Now Playing, Popular, Top Rated and Upcoming movies:
+
+```typescript
+tmdb.movie_lists.now_playing();
+tmdb.movie_lists.top_rated();
+tmdb.movie_lists.popular();
+tmdb.movie_lists.upcoming();
+```
+
+Returns a **typed response** containing movies.
+
+---
+
+### `Movie`
+
+Now Playing, Popular, Top Rated and Upcoming movies:
+
+```typescript
+tmdb.movie.details(550);
+tmdb.movie.alternative_titles(550);
+tmdb.movie.changes(550);
+tmdb.movie.credits(550);
+tmdb.movie.external_ids(550);
+
+...
+```
+
+Returns a **typed response** containing movies.
+
+---
+
+## Error Handling
+
+All errors thrown from the TMDB API are wrapped in a `TMDBError` class.
+
+You can catch them:
+
+```typescript
+catch (error) {
+  if (error instanceof TMDBError) {
+    console.log(error.message);
+    console.log(error.http_status_code);
+    console.log(error.tmdb_status_code);
+  }
+}
+```
+
+Properties available:
+
+- `message`
+- `http_status_code`
+- `tmdb_status_code`
+
+If the TMDB service is unreachable or returns unexpected errors, `tmdb_status_code` is set to `-1`.
+
+---
+
+## Requirements
+
+- Node.js 18+ recommended
+- Works on frontend (React, Vue) but **don't expose sensitive access tokens** to users!
+
+---
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,7 @@
+export declare class ApiClient {
+    private accessToken;
+    private baseUrl;
+    constructor(accessToken: string);
+    request<T>(endpoint: string, params?: Record<string, any | undefined>): Promise<T>;
+    private handleError;
+}

package/dist/client.js

@@ -0,0 +1,42 @@
+import { TMDBError } from "./errors/tmdb";
+export class ApiClient {
+    accessToken;
+    baseUrl = "https://api.themoviedb.org/3";
+    constructor(accessToken) {
+        this.accessToken = accessToken;
+    }
+    async request(endpoint, params = {}) {
+        const url = new URL(`${this.baseUrl}${endpoint}`);
+        for (const [key, value] of Object.entries(params)) {
+            if (value === undefined)
+                continue;
+            url.searchParams.append(key, String(value));
+        }
+        const res = await fetch(url.toString(), {
+            headers: {
+                Authorization: `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json;charset=utf-8",
+            },
+        });
+        if (!res.ok)
+            await this.handleError(res);
+        return res.json();
+    }
+    async handleError(res) {
+        let errorMessage = res.statusText;
+        let tmdbStatusCode = -1;
+        try {
+            const errorBody = await res.json();
+            if (errorBody && typeof errorBody === "object") {
+                const err = errorBody;
+                errorMessage = err.status_message || errorMessage;
+                tmdbStatusCode = err.status_code || -1;
+            }
+        }
+        catch (_) {
+            // If response is not JSON, fallback to HTTP status text
+        }
+        const error = new TMDBError(errorMessage, res.status, tmdbStatusCode);
+        throw error;
+    }
+}

package/dist/endpoints/movie_lists.d.ts

@@ -0,0 +1,56 @@
+import { ApiClient } from "../client";
+import { MovieResultItem } from "../types/movies";
+import { PaginatedResponse } from "../types/params";
+export declare class MovieListsAPI {
+    private client;
+    constructor(client: ApiClient);
+    /**
+     * Fetch Movie List Wrapper
+     * @param endpoint Endpoint to call
+     * @param language Language (Defaults to en-US)
+     * @param page Page (Defaults to 1)
+     * @param region ISO-3166-1 code
+     * @returns Specific to endpoint (MovieListResult)
+     */
+    private fetch_movie_list;
+    /**
+     * Now Playing
+     * GET - https://api.themoviedb.org/3/movie/now_playing
+     *
+     * Get a list of movies that are currently in theatres.
+     * @param language Language (Defaults to en-US)
+     * @param page Page (Defaults to 1)
+     * @param region ISO-3166-1 code
+     */
+    now_playing(language?: string, page?: number, region?: string): Promise<PaginatedResponse<MovieResultItem>>;
+    /**
+     * Popular
+     * GET - https://api.themoviedb.org/3/movie/popular
+     *
+     * Get a list of movies ordered by popularity.
+     * @param language Language (Defaults to en-US)
+     * @param page Page (Defaults to 1)
+     * @param region ISO-3166-1 code
+     */
+    popular(language?: string, page?: number, region?: string): Promise<PaginatedResponse<MovieResultItem>>;
+    /**
+     * Top Rated
+     * GET - https://api.themoviedb.org/3/movie/top_rated
+     *
+     * Get a list of movies ordered by rating.
+     * @param language Language (Defaults to en-US)
+     * @param page Page (Defaults to 1)
+     * @param region ISO-3166-1 code
+     */
+    top_rated(language?: string, page?: number, region?: string): Promise<PaginatedResponse<MovieResultItem>>;
+    /**
+     * Upcoming
+     * GET - https://api.themoviedb.org/3/movie/upcoming
+     *
+     * Get a list of movies that are being released soon.
+     * @param language Language (Defaults to en-US)
+     * @param page Page (Defaults to 1)
+     * @param region ISO-3166-1 code
+     */
+    upcoming(language?: string, page?: number, region?: string): Promise<PaginatedResponse<MovieResultItem>>;
+}

package/dist/endpoints/movie_lists.js

@@ -0,0 +1,73 @@
+import { MOVIE_ENDPOINTS } from "./movies";
+const MOVIE_LISTS_ENDPOINTS = {
+    NOW_PLAYING: "/now_playing",
+    POPULAR: "/popular",
+    TOP_RATED: "/top_rated",
+    UPCOMING: "/upcoming",
+};
+export class MovieListsAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Fetch Movie List Wrapper
+     * @param endpoint Endpoint to call
+     * @param language Language (Defaults to en-US)
+     * @param page Page (Defaults to 1)
+     * @param region ISO-3166-1 code
+     * @returns Specific to endpoint (MovieListResult)
+     */
+    fetch_movie_list(endpoint, language, page, region) {
+        const params = { page, language, region };
+        return this.client.request(MOVIE_ENDPOINTS.MOVIE + endpoint, params);
+    }
+    /**
+     * Now Playing
+     * GET - https://api.themoviedb.org/3/movie/now_playing
+     *
+     * Get a list of movies that are currently in theatres.
+     * @param language Language (Defaults to en-US)
+     * @param page Page (Defaults to 1)
+     * @param region ISO-3166-1 code
+     */
+    async now_playing(language = "en-US", page = 1, region) {
+        return this.fetch_movie_list(MOVIE_LISTS_ENDPOINTS.NOW_PLAYING, language, page, region);
+    }
+    /**
+     * Popular
+     * GET - https://api.themoviedb.org/3/movie/popular
+     *
+     * Get a list of movies ordered by popularity.
+     * @param language Language (Defaults to en-US)
+     * @param page Page (Defaults to 1)
+     * @param region ISO-3166-1 code
+     */
+    async popular(language = "en-US", page = 1, region) {
+        return this.fetch_movie_list(MOVIE_LISTS_ENDPOINTS.POPULAR, language, page, region);
+    }
+    /**
+     * Top Rated
+     * GET - https://api.themoviedb.org/3/movie/top_rated
+     *
+     * Get a list of movies ordered by rating.
+     * @param language Language (Defaults to en-US)
+     * @param page Page (Defaults to 1)
+     * @param region ISO-3166-1 code
+     */
+    async top_rated(language = "en-US", page = 1, region) {
+        return this.fetch_movie_list(MOVIE_LISTS_ENDPOINTS.TOP_RATED, language, page, region);
+    }
+    /**
+     * Upcoming
+     * GET - https://api.themoviedb.org/3/movie/upcoming
+     *
+     * Get a list of movies that are being released soon.
+     * @param language Language (Defaults to en-US)
+     * @param page Page (Defaults to 1)
+     * @param region ISO-3166-1 code
+     */
+    async upcoming(language = "en-US", page = 1, region) {
+        return this.fetch_movie_list(MOVIE_LISTS_ENDPOINTS.UPCOMING, language, page, region);
+    }
+}

package/dist/endpoints/movies.d.ts

@@ -0,0 +1,202 @@
+import { ApiClient } from "../client";
+import { Changes } from "../types/common";
+import { MovieAlternativeTitles, MovieCredits, MovieDetails, MovieExternalIDs, MovieImages, MovieKeywords, MovieReleaseDates, MovieResultItem, MovieTranslations, MovieVideos, MovieWatchProvider } from "../types/movies";
+import { PaginatedResponse } from "../types/params";
+export declare const MOVIE_ENDPOINTS: {
+    MOVIE: string;
+    ALTERNATIVE_TITLES: string;
+    CREDITS: string;
+    EXTERNAL_IDS: string;
+    KEYWORDS: string;
+    CHANGES: string;
+    IMAGES: string;
+    LATEST: string;
+    RECOMMENDATIONS: string;
+    RELEASE_DATES: string;
+    SIMILAR: string;
+    TRANSLATIONS: string;
+    VIDEOS: string;
+    WATCH_PROVIDERS: string;
+};
+export declare class MoviesAPI {
+    private client;
+    constructor(client: ApiClient);
+    /**
+     * Details
+     * GET - https://api.themoviedb.org/3/movie/{movie_id}
+     *
+     * Get the top level details of a movie by ID.
+     * @param movie_id The ID of the movie.
+     * @param append_to_response A comma-separated list of the fields to include in the response.
+     * @param language The language to use for the response.
+     * @returns A promise that resolves to the movie details.
+     * @reference https://developer.themoviedb.org/reference/movie-details
+     */
+    details(movie_id: number, append_to_response?: string[], language?: string): Promise<MovieDetails>;
+    /**
+     * Alternative Titles
+     * GET - https://api.themoviedb.org/3/movie/{movie_id}/alternative_titles
+     *
+     * Get the alternative titles for a movie (ex. Russian name, Indian names etc..).
+     * @param movie_id The ID of the movie.
+     * @param country The ISO 3166-1 code of the country to get alternative titles for.
+     * @returns A promise that resolves to the movie alternative titles.
+     * @reference https://developer.themoviedb.org/reference/movie-alternative-titles
+     */
+    alternative_titles(movie_id: number, country?: string): Promise<MovieAlternativeTitles>;
+    /**
+     * Credits
+     * GET - https://api.themoviedb.org/3/movie/{movie_id}/credits
+     *
+     * Get the cast and crew members details for a movie.
+     * @param movie_id The ID of the movie.
+     * @param language The ISO 639-1 code of the language to use for the response. Default is "en-US".
+     * @returns A promise that resolves to the movie credits.
+     * @reference https://developer.themoviedb.org/reference/movie-credits
+     */
+    credits(movie_id: number, language?: string): Promise<MovieCredits>;
+    /**
+     * External IDs
+     * GET - https://api.themoviedb.org/3/movie/{movie_id}/external_ids
+     *
+     * Get the external IDs for a movie (ex. IMDB, Facebook, Instagram etc..).
+     * Supported external IDs are: IMDB, Facebook, Instagram, Twitter, and Wikidata.
+     *
+     * @param movie_id The ID of the movie.
+     * @returns A promise that resolves to the movie external IDs.
+     * @reference https://developer.themoviedb.org/reference/movie-external-ids
+     */
+    external_ids(movie_id: number): Promise<MovieExternalIDs>;
+    /**
+     * Keywords
+     * GET - https://api.themoviedb.org/3/movie/{movie_id}/keywords
+     *
+     * Get the keywords that have been added to a movie.
+     * This is a list of keywords that have been added to the movie.
+     * @param movie_id The ID of the movie.
+     * @returns A promise that resolves to the movie keywords.
+     * @reference https://developer.themoviedb.org/reference/movie-keywords
+     */
+    keywords(movie_id: number): Promise<MovieKeywords>;
+    /**
+     * Changes
+     * GET - https://api.themoviedb.org/3/movie/{movie_id}/changes
+     *
+     * Get the changes for a movie. This is a list of all the changes that have been made to a movie.
+     * By default, only the last 24 hours are returned.
+     * You can query up to 14 days in a single query by using the start_date and end_date query parameters.
+     * @param movie_id The ID of the movie.
+     * @param page Page number of the results to return. Defaults to 1.
+     * @param start_date Optional start date for the changes. Format: YYYY-MM-DD.
+     * @param end_date Optional end date for the changes. Format: YYYY-MM-DD.
+     * @returns A promise that resolves to the changes made to the movie.
+     * @reference https://developer.themoviedb.org/reference/movie-changes
+     */
+    changes(movie_id: number, page?: number, start_date?: string, end_date?: string): Promise<Changes>;
+    /**
+     * Images
+     * GET - https://api.themoviedb.org/3/movie/{movie_id}/images
+     *
+     * Fetches images related to a specific movie, such as posters and backdrops.
+     * The images are returned in various sizes and formats.
+     * @param movie_id - The unique identifier of the movie.
+     * @param language - (Optional) The language code to filter the images by language.
+     * @param include_image_language - (Optional) A comma-separated list of language codes to include images for.
+     * @returns A promise that resolves to a `MovieImages` object containing the movie's images.
+     * @reference https://developer.themoviedb.org/reference/movie-images
+     */
+    images(movie_id: number, language?: string, include_image_language?: string): Promise<MovieImages>;
+    /**
+     * Latest
+     * GET - https://api.themoviedb.org/3/movie/latest
+     *
+     * Get the newest movie ID.
+     * This is the most recent movie that has been added to TMDB. This is a live response will continuously change as new movies are added.
+     * @returns A promise that resolves to the latest movie details.
+     * @reference https://developer.themoviedb.org/reference/movie-latest-id
+     */
+    latest(): Promise<MovieDetails>;
+    /**
+     * Recommendations
+     * GET - https://api.themoviedb.org/3/movie/{movie_id}/recommendations
+     *
+     * Get a list of recommended movies for a specific movie.
+     * This is based on the movie's popularity and user ratings.
+     * @param movie_id The ID of the movie.
+     * @param page Page number of the results to return. Defaults to 1.
+     * @param language Language code to filter the results. Default is "en-US".
+     * @returns A promise that resolves to a paginated response of similar movies.
+     * @reference https://developer.themoviedb.org/reference/movie-recommendations
+     */
+    recommendations(movie_id: number, page?: number, language?: string): Promise<PaginatedResponse<MovieResultItem>>;
+    /**
+     * Release Dates
+     * GET - https://api.themoviedb.org/3/movie/{movie_id}/release_dates
+     *
+     * Get the release dates and certifications for a movie. For different countries and release types.
+     * The release types and statuses used on TMDB are the following:
+     * - 1: Premiere
+     * - 2: Theatrical (Limited)
+     * - 3: Theatrical
+     * - 4: Digital
+     * - 5: Physical
+     * - 6: TV
+     * @param movie_id The ID of the movie.
+     * @returns A promise that resolves to the release dates for the movie.
+     * @reference https://developer.themoviedb.org/reference/movie-release-dates
+     */
+    release_dates(movie_id: number): Promise<MovieReleaseDates>;
+    /**
+     * Similar
+     * GET -https://api.themoviedb.org/3/movie/{movie_id}/similar
+     *
+     * Get the similar movies based on genres and keywords.
+     * This method only looks for other items based on genres and plot keywords.
+     * As such, the results found here are not always going to be 💯. Use it with that in mind.
+     * @param movie_id The ID of the movie
+     * @param page Page number of the results to return. Defaults to 1.
+     * @param language Language code to filter the results. Default is "en-US".
+     * @returns A promise that resolves to a paginated response of similar movies.
+     * @reference https://developer.themoviedb.org/reference/movie-similar
+     */
+    similar(movie_id: number, language?: string, page?: number): Promise<PaginatedResponse<MovieResultItem>>;
+    /**
+     * Translations
+     * GET - https://api.themoviedb.org/3/movie/{movie_id}/translations
+     *
+     * Get the translations for a movie.
+     * Take a read through our language documentation for more information about languages on TMDB.
+     * https://developer.themoviedb.org/docs/languages
+     * @param movie_id The ID of the movie
+     * @returns A promise that resolves to the translations of the movie.
+     * @reference https://developer.themoviedb.org/reference/movie-translations
+     */
+    translations(movie_id: number): Promise<MovieTranslations>;
+    /**
+     * Videos
+     * GET - https://api.themoviedb.org/3/movie/{movie_id}/videos
+     *
+     * Get the available videos for a movie.
+     * @param movie_id The ID of the movie
+     * @returns A promise that resolves to a list of videos for the movie.
+     * @reference https://developer.themoviedb.org/reference/movie-videos
+     */
+    videos(movie_id: number, language?: string): Promise<MovieVideos>;
+    /**
+     * Watch Providers
+     * GET - https://api.themoviedb.org/3/movie/{movie_id}/watch/providers
+     *
+     * Get the list of streaming providers we have for a movie.
+     * Powered by our partnership with JustWatch, you can query this method to get a list of the streaming/rental/purchase availabilities per country by provider.
+     * This is not going to return full deep links, but rather, it's just enough information to display what's available where.
+     * You can link to the provided TMDB URL to help support TMDB and provide the actual deep links to the content.
+     *
+     * JustWatch ATTRIBUTION REQUIRED
+     * In order to use this data you must attribute the source of the data as JustWatch.
+     * If we find any usage not complying with these terms we will revoke access to the API.
+     * @param movie_id The ID of the movie
+     * @returns A promise that resolves to a list of videos for the movie.
+     * @reference https://developer.themoviedb.org/reference/movie-videos
+     */
+    watch_providers(movie_id: number): Promise<MovieWatchProvider>;
+}