### Controller Example with Async/Await, .env, and Error Handling

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

A comprehensive controller example demonstrating asynchronous operations with async/await. It includes reading API keys from a .env file, handling request parameters, and implementing robust error handling for API calls.

```javascript
import { MovieDb } from 'moviedb-promise'
import dotenv from 'dotenv'

dotenv.config()

const moviedb = new MovieDb(process.env.KEY)

const newError = (name) => {
  const e = new Error(name)
  e.name = name
  return Promise.reject(e)
}

export const searchMovie = async (req) => {
  const parameters = {
    query: req.query.name,
    page: req.query.page,
  }
  try {
    const res = await moviedb.searchMovie(parameters)
    return res.results
  } catch (error) {
    return newError(error)
  }
}

export const searchPerson = async (req) => {
  const parameters = {
    query: req.query.name,
    page: 1,
  }
  try {
    const res = await moviedb.searchPerson(parameters)
    return res.results
  } catch (error) {
    return newError(error)
  }
}

export const movieKeywords = async (req) => {
  try {
    const res = await moviedb.movieKeywords({ query: req.query.name })
    return res.results
  } catch (error) {
    return newError(error)
  }
}
```

--------------------------------

### Install moviedb-promise using npm

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

This command installs the moviedb-promise package as a dependency for your Node.js project.

```bash
npm install moviedb-promise --save
```

--------------------------------

### Search Movie with Promises and Async/Await

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Demonstrates how to search for a movie using the moviedb-promise library. It shows examples using both traditional Promises with .then/.catch and the more modern async/await syntax. Error handling is included for both approaches.

```javascript
moviedb
  .searchMovie({ query: 'Alien' })
  .then((res) => {
    console.log(res)
  })
  .catch(console.error)

// Using await
// You probably wouldn't ever use it this way...
;(async function () {
  try {
    const res = await moviedb.searchMovie({ query: 'alien' })
    console.log(res)
  } catch (e) {
    console.log(e)
  }
})()

// This is a more reasonable example
const findMovie = async (title) => {
  // Equivalant to { query: title }
  const res = await moviedb.searchMovie(title)

  return res
}

try {
  const results = findMovie('alien')
} catch (e) {
  // Do something
}
```

--------------------------------

### Get Movie Information by ID

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Shows how to retrieve detailed information about a specific movie using its ID. This example utilizes the Promise-based approach for handling the API response.

```javascript
moviedb
  .movieInfo({ id: 666 })
  .then((res) => {
    console.log(res)
  })
  .catch(console.error)
```

--------------------------------

### Using append_to_response with tvInfo

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Shows how to use the 'append_to_response' parameter with the tvInfo method to fetch season details and credits. Includes an example with multiple append requests.

```APIDOC
## GET /tv/{tv_id}

### Description
Retrieves detailed information about a specific TV show, with the option to append related data like seasons and their credits using the `append_to_response` parameter.

### Method
GET

### Endpoint
`/tv/{tv_id}`

### Query Parameters
- **append_to_response** (string) - Optional - A comma-separated list of additional data endpoints to include in the response (e.g., "season/1", "season/1/credits").

### Request Example
```js
const res = await api.tvInfo({
  id: 4629,
  append_to_response: 'season/1,season/1/credits',
})
```

### Response
#### Success Response (200)
- **tv_details** (object) - The primary TV show information.
- **season_1** (object) - Appended details for season 1 (if requested).
- **season_1_credits** (object) - Appended credits for season 1 (if requested).

#### Response Example
```json
{
  "id": 4629,
  "name": "Example TV Show",
  "seasons": [
    {
      "id": 12345,
      "name": "Season 1"
    }
  ],
  "season_1": {
    "id": 12345,
    "name": "Season 1",
    "episode_count": 10
  },
  "season_1_credits": {
    "cast": [
      {
        "name": "Actor Name"
      }
    ],
    "crew": []
  }
}
```
```

--------------------------------

### Using append_to_response with movieInfo

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Demonstrates how to use the 'append_to_response' parameter with the movieInfo method to include additional data like release dates. Includes a TypeScript example for casting the response.

```APIDOC
## GET /movie/{movie_id}

### Description
Retrieves detailed information about a specific movie, with the option to append related data using the `append_to_response` parameter.

### Method
GET

### Endpoint
`/movie/{movie_id}`

### Query Parameters
- **append_to_response** (string) - Optional - A comma-separated list of additional data endpoints to include in the response (e.g., "release_dates", "credits").

### Request Example
```ts
const response = await moviedb.movieInfo({ id: tmdbId, append_to_response: "release_dates" })
  as MovieResponse & { release_dates: MovieReleaseDatesResponse }
```

### Response
#### Success Response (200)
- **movie_details** (object) - The primary movie information.
- **release_dates** (object) - Appended release date information (if requested).

#### Response Example
```json
{
  "id": 123,
  "title": "Example Movie",
  "release_dates": {
    "results": [
      {
        "iso_3166_1": "US",
        "release_dates": [
          {
            "certification": "PG-13",
            "iso_639_1": "en",
            "release_date": "2023-10-27T00:00:00.000Z",
            "type": 3
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### Using Axios Request Config with tvInfo

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Illustrates how to pass an Axios request config object as the last parameter to endpoint functions, allowing for customization like setting timeouts. Shows examples for both single and combined options.

```APIDOC
## GET /tv/{tv_id} with Request Options

### Description
Allows for the customization of underlying Axios request configurations, such as setting timeouts, when calling TV show information endpoints.

### Method
GET

### Endpoint
`/tv/{tv_id}`

### Parameters
#### Path Parameters
- **tv_id** (integer) - Required - The ID of the TV show.

#### Query Parameters
- **append_to_response** (string) - Optional - A comma-separated list of additional data endpoints to include in the response.

#### Request Body
(Not applicable for GET requests)

### Request Example
```js
// Example with timeout
const res = await api.tvInfo(4629, { timeout: 10000 })

// Example combining append_to_response and timeout
const res = await api.tvInfo(
  {
    id: 4629,
    append_to_response: 'season/1,season/1/credits',
  },
  {
    timeout: 10000,
  },
)
```

### Response
#### Success Response (200)
- **tv_details** (object) - The primary TV show information.
- **appended_data** (object) - Any data appended via `append_to_response`.

#### Response Example
```json
{
  "id": 4629,
  "name": "Example TV Show",
  "backdrop_path": "/example.jpg",
  "vote_average": 8.5
}
```
```

--------------------------------

### Use append_to_response in JavaScript for TV Info

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Illustrates the usage of the 'append_to_response' parameter with the tvInfo method in JavaScript. This example shows how to request multiple related resources, like 'season/1' and 'season/1/credits', in a single API call.

```javascript
const res = await api.tvInfo({
  id: 4629,
  append_to_response: 'season/1,season/1/credits',
})
```

--------------------------------

### Combine append_to_response and Request Options

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Provides an example of how to use both the 'append_to_response' parameter and an Axios request configuration object simultaneously. This demonstrates flexibility in making complex, customized API requests, such as setting a timeout while also fetching additional data.

```javascript
const res = await api.tvInfo(
  {
    id: 4629,
    append_to_response: 'season/1,season/1/credits',
  },
  {
    timeout: 10000,
  },
)
```

--------------------------------

### Set Request Timeout using Axios Config

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Shows how to apply an Axios request configuration object as the last parameter to an endpoint function. This example specifically demonstrates setting a 'timeout' for the tvInfo request, overriding default settings for that particular call.

```javascript
// Add a timeout restriction to the request
const res = await api.tvInfo(4629, { timeout: 10000 })
```

--------------------------------

### Get Movie Videos

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Fetches trailers, teasers, and other video content for a specific movie. The response includes video details such as the YouTube ID, name, site, type, and whether it's official.

```javascript
const videos = await moviedb.movieVideos(27205)

// Response structure
// {
//   id: 27205,
//   results: [
//     {
//       id: '533ec654c3a36854480003eb',
//       key: 'YoHD9XEInc0',  // YouTube video ID
//       name: 'Inception - Official Trailer',
//       site: 'YouTube',
//       type: 'Trailer',
//       size: 1080,
//       official: true
//     }
//   ]
// }
```

--------------------------------

### Get TMDB Configuration

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieves the TMDB configuration, including image base URLs and poster/backdrop sizes. This is essential for constructing valid image URLs for movies and TV shows. No external dependencies are required beyond the moviedb-promise library itself.

```javascript
const config = await moviedb.configuration()

// Response structure
// {
//   images: {
//     base_url: 'http://image.tmdb.org/t/p/',
//     secure_base_url: 'https://image.tmdb.org/t/p/',
//     poster_sizes: ['w92', 'w154', 'w185', 'w342', 'w500', 'w780', 'original'],
//     backdrop_sizes: ['w300', 'w780', 'w1280', 'original']
//   },
//   change_keys: ['adult', 'air_date', 'budget', ...]
// }

// Build full image URL
const posterUrl = `${config.images.secure_base_url}w500${movie.poster_path}`
```

--------------------------------

### Get Similar Movies

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieves a list of movies that are similar to a specified movie ID. This is helpful for building features that suggest alternative or related films.

```javascript
const similar = await moviedb.movieSimilar(27205)
```

--------------------------------

### Get Person Information

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieves comprehensive details about a person, including their biography, birthday, birthplace, and profile path. It can also append related credits like movie and TV show appearances.

```javascript
const person = await moviedb.personInfo({
  id: 6193,
  append_to_response: 'movie_credits,tv_credits'
})

// Response structure
// {
//   id: 6193,
//   name: 'Leonardo DiCaprio',
//   biography: 'Leonardo Wilhelm DiCaprio is an American actor...', 
//   birthday: '1974-11-11',
//   place_of_birth: 'Los Angeles, California, USA',
//   profile_path: '/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg',
//   known_for_department: 'Acting',
//   imdb_id: 'nm0000138'
// }
```

--------------------------------

### Get Movie Images

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieves various images associated with a movie, including posters, backdrops, and logos. Allows specifying preferred image languages. Useful for displaying visual content for a movie.

```javascript
const images = await moviedb.movieImages({
  id: 27205,
  include_image_language: 'en,null'
})

// Response structure
// {
//   id: 27205,
//   backdrops: [
//     { file_path: '/s3TBrRGB1iav7gFOCNx3H31MoES.jpg', width: 1920, height: 1080 }
//   ],
//   posters: [
//     { file_path: '/9gk7adHYeDvHkCSEqAvQNLV5Ber.jpg', width: 500, height: 750 }
//   ],
//   logos: [...] 
// }
```

--------------------------------

### Get TV Episode Information

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Fetches detailed information for a specific TV episode using its ID, season number, and episode number. The response includes details like episode name, air date, overview, runtime, and ratings.

```javascript
const episode = await moviedb.episodeInfo({
  id: 1396,
  season_number: 1,
  episode_number: 1
})

// Response structure
// {
//   id: 62085,
//   name: 'Pilot',
//   episode_number: 1,
//   season_number: 1,
//   air_date: '2008-01-20',
//   overview: 'When an unassuming high school chemistry teacher...', 
//   runtime: 58,
//   vote_average: 8.2,
//   crew: [...],
//   guest_stars: [...] 
// }
```

--------------------------------

### Get Trending Media

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieves trending movies, TV shows, or people for a specified time window (day or week). Returns a paginated list of popular media items, including their ID, title, and vote average.

```javascript
const trending = await moviedb.trending({
  media_type: 'movie',  // 'all', 'movie', 'tv', 'person'
  time_window: 'week'   // 'day' or 'week'
})

// Response structure
// {
//   page: 1,
//   results: [
//     {
//       id: 603692,
//       title: 'John Wick: Chapter 4',
//       media_type: 'movie',
//       vote_average: 7.9
//     }
//   ]
// }
```

--------------------------------

### Calling TV Info with Placeholder Parameters

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Demonstrates two ways to call the `tvInfo` method, which requires an `id` parameter. It shows how to pass the parameter as an object with a named key or directly as a value if there's only one placeholder in the endpoint.

```javascript
// Two ways:
// The object key matches the placeholder name
Moviedb.tvInfo({ id: 61888 }).then(...)

// Or for simplicity, if it only has one placeholder
Moviedb.tvInfo(61888).then(...)
```

--------------------------------

### Initialize MovieDb with API Key (JavaScript)

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

This code snippet demonstrates how to require the 'moviedb-promise' module and instantiate the 'MovieDb' class with your themoviedb.org API key. This is the first step to using the library.

```javascript
const { MovieDb } = require('moviedb-promise')
const moviedb = new MovieDb('your api key')
```

--------------------------------

### Searching Movies with Query Parameters

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Explains how to search for movies when the API endpoint does not have any URL placeholders. It details how to use query parameters like `language`, `query`, and `page` by passing them as an object to the `searchMovie` method, referencing the official documentation for available options.

```javascript
const parameters = {
  query: 'Kindergarten Cop',
  language: 'fr' // ISO 639-1 code
}

Moviedb.searchMovie(parameters).then(...)
```

--------------------------------

### Get Movie Recommendations

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Provides movie recommendations based on a given movie ID. This endpoint is useful for suggesting similar content to users based on their viewing history or preferences.

```javascript
const recommendations = await moviedb.movieRecommendations({
  id: 27205,
  page: 1
})
```

--------------------------------

### Get Movie Genre List

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Fetches the official list of movie genres from TMDB. The response contains an array of genre objects, each with an 'id' and 'name'. This is useful for filtering or categorizing movies.

```javascript
const genres = await moviedb.genreMovieList()

// Response structure
// {
//   genres: [
//     { id: 28, name: 'Action' },
//     { id: 12, name: 'Adventure' },
//     { id: 16, name: 'Animation' }
//   ]
// }
```

--------------------------------

### Get Movie Credits

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Fetches the cast and crew information for a specific movie using its ID. The response includes details about actors, their characters, and the film's director and other crew members.

```javascript
const credits = await moviedb.movieCredits(27205)

// Response structure
// {
//   id: 27205,
//   cast: [
//     {
//       id: 6193,
//       name: 'Leonardo DiCaprio',
//       character: 'Dom Cobb',
//       order: 0,
//       profile_path: '/wo2hJpn04vbtmh0B9utCFdsQhxM.jpg'
//     }
//   ],
//   crew: [
//     {
//       id: 525,
//       name: 'Christopher Nolan',
//       job: 'Director',
//       department: 'Directing'
//     }
//   ]
// }
```

--------------------------------

### Get TV Season Information with moviedb-promise

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieve information about a specific TV season, including all its episodes, using the `seasonInfo` method. This requires both the TV show's ID and the season number.

```javascript
const season = await moviedb.seasonInfo({
  id: 1396,
  season_number: 1
})
```

--------------------------------

### Managing User Watchlist with Session ID

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Illustrates how to manage a user's movie watchlist. It shows how to set and use a cached session ID for authenticated requests and outlines the process of obtaining a session ID, including requesting an authentication token and retrieving the session.

```javascript
// This is the same as calling it as
// moviedb.accountMovieWatchlist({ id: '{account_id}' })
Moviedb.sessionId = 'my-cached-session-id'
Moviedb
  .accountMovieWatchlist()
  .then((res) => {
    // Your watchlist items
    console.log(res)
  })
  .catch(console.error)

// Creating a session id would look something like this
Moviedb
  .requestToken()
  .then((token) => {
    // Now you need to visit this url to authorize
    const tokenUrl = `https://www.themoviedb.org/authenticate/${token}`
  })
  .catch(console.error)

// After that has been authorized, you can get the session id
Moviedb
  .retrieveSession()
  .then((sessionId) => {
    // Probably cache this id somewhere to avoid this workflow
    console.log(sessionId)

    // After the sessionId is cached, the next time use instantiate the class,
    // set the sessionId by moviedb.sessionId = 'my-session-id'

    // This can be called now because sessionId is set
Moviedb
      .accountMovieWatchlist()
      .then((res) => {
        // Your watchlist items
        console.log(res)
      })
      .catch(console.error)
  })
  .catch(console.error)
```

--------------------------------

### Movie Search API

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Demonstrates how to search for movies using the `searchMovie` method. It can be used with Promises or async/await and accepts a query string or an object with parameters.

```APIDOC
## POST /search/movie

### Description
Searches for movies based on a query string or provided parameters.

### Method
POST

### Endpoint
/search/movie

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query for the movie title.
- **language** (string) - Optional - ISO 639-1 code for the language.
- **page** (integer) - Optional - The page number of search results.
- **include_adult** (boolean) - Optional - Whether to include adult movies.
- **region** (string) - Optional - The region to filter results.
- **year** (integer) - Optional - The release year to filter results.
- **primary_release_year** (integer) - Optional - The primary release year to filter results.

### Request Example
```javascript
// Using just the Promise
moviedb
  .searchMovie({ query: 'Alien' })
  .then((res) => {
    console.log(res)
  })
  .catch(console.error)

// Using await
const findMovie = async (title) => {
  const res = await moviedb.searchMovie(title)
  return res
}

// Example with specific parameters
const parameters = {
  query: 'Kindergarten Cop',
  language: 'fr'
}
movedb.searchMovie(parameters).then(...)
```

### Response
#### Success Response (200)
- **results** (array) - An array of movie objects matching the search criteria.

#### Response Example
```json
{
  "results": [
    {
      "adult": false,
      "backdrop_path": "/path/to/backdrop.jpg",
      "genre_ids": [28, 878, 35],
      "id": 12345,
      "original_language": "en",
      "original_title": "Kindergarten Cop",
      "overview": "A tough cop goes undercover as a kindergarten teacher.",
      "popularity": 10.5,
      "poster_path": "/path/to/poster.jpg",
      "release_date": "1990-12-21",
      "title": "Kindergarten Cop",
      "video": false,
      "vote_average": 6.5,
      "vote_count": 3000
    }
  ],
  "page": 1,
  "total_pages": 1,
  "total_results": 1
}
```
```

--------------------------------

### Initialize moviedb-promise Client

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Instantiate the MovieDb class with your TMDB API key to begin making requests. You can also specify a custom base URL and request limit.

```javascript
const { MovieDb } = require('moviedb-promise')
const moviedb = new MovieDb('your-api-key')
```

```javascript
// With custom base URL and request limit
const moviedb = new MovieDb('your-api-key', 'https://api.themoviedb.org/3/', 50)
```

--------------------------------

### Get TV Genre List

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Fetches the official list of TV genres from TMDB. Similar to movie genres, it returns an array of genre objects with 'id' and 'name'. This allows for categorization of TV shows.

```javascript
const genres = await moviedb.genreTvList()
```

--------------------------------

### Configuration API

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Fetches TMDB configuration details, including image base URLs and available sizes, which are essential for constructing image URLs.

```APIDOC
## GET /configuration

### Description
Get TMDB configuration including image base URLs and sizes.

### Method
GET

### Endpoint
/configuration

### Parameters
#### Query Parameters
None

### Request Example
```javascript
const config = await moviedb.configuration()
```

### Response
#### Success Response (200)
- **images** (object) - Contains image-related configuration like base URLs and sizes.
- **change_keys** (array) - A list of keys that can be changed.

#### Response Example
```json
{
  "images": {
    "base_url": "http://image.tmdb.org/t/p/",
    "secure_base_url": "https://image.tmdb.org/t/p/",
    "poster_sizes": ["w92", "w154", "w185", "w342", "w500", "w780", "original"],
    "backdrop_sizes": ["w300", "w780", "w1280", "original"]
  },
  "change_keys": ["adult", "air_date", "budget", ...]
}
```
```

--------------------------------

### Get Movie Information with moviedb-promise

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieve detailed information about a specific movie using its ID with the `movieInfo` method. You can also append related data such as credits, videos, and images by using the `append_to_response` parameter.

```javascript
// Simple request by ID
const movie = await moviedb.movieInfo(27205)
```

```javascript
// With append_to_response for additional data
const movie = await moviedb.movieInfo({
  id: 27205,
  append_to_response: 'credits,videos,images'
})
```

--------------------------------

### Get Movie Streaming Availability

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieves streaming availability information for a specific movie, including where it can be watched via flatrate, rent, or buy options across different regions. Requires a movie ID as input.

```javascript
const providers = await moviedb.movieWatchProviders(27205)

// Response structure
// {
//   id: 27205,
//   results: {
//     US: {
//       link: 'https://www.themoviedb.org/movie/27205/watch?locale=US',
//       flatrate: [{ provider_name: 'Netflix', logo_path: '/...' }],
//       rent: [{ provider_name: 'Amazon Video', logo_path: '/...' }],
//       buy: [{ provider_name: 'Apple TV', logo_path: '/...' }]
//     }
//   }
// }
```

--------------------------------

### movieVideos

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieves trailers, teasers, and other video content for a specific movie.

```APIDOC
## GET /movieVideos

### Description
Get trailers, teasers, and other videos for a movie.

### Method
GET

### Endpoint
/movieVideos

### Parameters
#### Query Parameters
- **id** (integer) - Required - The ID of the movie.

### Request Example
```javascript
const videos = await moviedb.movieVideos(27205)
```

### Response
#### Success Response (200)
- **id** (integer) - The movie ID.
- **results** (array) - A list of video results.
  - **id** (string) - The video ID.
  - **key** (string) - The video key (e.g., YouTube video ID).
  - **name** (string) - The name of the video.
  - **site** (string) - The site where the video is hosted (e.g., 'YouTube').
  - **type** (string) - The type of video (e.g., 'Trailer', 'Teaser').
  - **size** (integer) - The size of the video.
  - **official** (boolean) - Indicates if the video is official.

#### Response Example
```json
{
  "id": 27205,
  "results": [
    {
      "id": "533ec654c3a36854480003eb",
      "key": "YoHD9XEInc0",  // YouTube video ID
      "name": "Inception - Official Trailer",
      "site": "YouTube",
      "type": "Trailer",
      "size": 1080,
      "official": true
    }
  ]
}
```
```

--------------------------------

### Request Options

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Demonstrates how to customize requests using an optional Axios config object, including setting timeouts and headers.

```APIDOC
## Request Options

### Description
All methods accept an optional axios config object as the last parameter for customization.

### Examples

**Add timeout**
```javascript
// Add timeout
const movie = await moviedb.movieInfo(27205, { timeout: 10000 })
```

**With parameters and axios config**
```javascript
// With parameters and axios config
const movie = await moviedb.movieInfo(
  { id: 27205, append_to_response: 'credits' },
  { timeout: 10000, headers: { 'Accept-Language': 'es' } }
)
```
```

--------------------------------

### Use append_to_response in TypeScript for Movie Info

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Demonstrates how to use the 'append_to_response' parameter with the movieInfo method in TypeScript. It shows how to cast the response to include types for the appended data, such as 'release_dates'. This allows for more efficient data fetching by combining multiple requests.

```typescript
const response = await moviedb.movieInfo({ id: tmdbId, append_to_response: "release_dates" })
  as MovieResponse & { release_dates: MovieReleaseDatesResponse }
```

--------------------------------

### Get TV Show Information with moviedb-promise

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Fetch detailed information about a TV show using its ID with the `tvInfo` method. You can also append season-specific data, such as credits for a particular season, by utilizing the `append_to_response` parameter.

```javascript
// Simple request
const show = await moviedb.tvInfo(1396)
```

```javascript
// With appended season data
const show = await moviedb.tvInfo({
  id: 1396,
  append_to_response: 'season/1,season/1/credits'
})
```

--------------------------------

### Authentication - Request Token API

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Requests a token that can be used to authenticate users.

```APIDOC
## GET /authentication/token/new

### Description
Requests a new authentication token. This token is the first step in the authentication process and is used to generate a session ID.

### Method
GET

### Endpoint
/authentication/token/new

### Parameters
None

### Request Example
```javascript
movedb
  .requestToken()
  .then((token) => {
    console.log('Request Token:', token)
    // Now you need to visit this url to authorize
    const tokenUrl = `https://www.themoviedb.org/authenticate/${token}`
    console.log('Authorization URL:', tokenUrl)
  })
  .catch(console.error)
```

### Response
#### Success Response (200)
- **request_token** (string) - The generated request token.
- **expires_at** (string) - The expiration date and time of the token.
- **success** (boolean) - Indicates if the request was successful.

#### Response Example
```json
{
  "success": true,
  "expires_at": "2023-12-31T10:00:00.000Z",
  "request_token": "your_generated_request_token"
}
```
```

--------------------------------

### Get Movie Collection Information

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieves detailed information about a movie collection, often representing a franchise. The response includes the collection's ID, name, overview, and a list of its constituent movie parts, each with an ID and title.

```javascript
const collection = await moviedb.collectionInfo(10)  // Star Wars Collection

// Response structure
// {
//   id: 10,
//   name: 'Star Wars Collection',
//   overview: '...',
//   parts: [
//     { id: 11, title: 'Star Wars' },
//     { id: 1891, title: 'The Empire Strikes Back' }
//   ]
// }
```

--------------------------------

### movieRecommendations

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Fetches movie recommendations based on a specified movie.

```APIDOC
## GET /movieRecommendations

### Description
Get movie recommendations based on a specific movie.

### Method
GET

### Endpoint
/movieRecommendations

### Parameters
#### Query Parameters
- **id** (integer) - Required - The ID of the movie to base recommendations on.
- **page** (integer) - Optional - The page number of recommendations.

### Request Example
```javascript
const recommendations = await moviedb.movieRecommendations({
  id: 27205,
  page: 1
})
```

### Response
#### Success Response (200)
- **page** (integer) - The current page of recommendations.
- **results** (array) - A list of recommended movies.
  - **id** (integer) - The movie ID.
  - **title** (string) - The movie title.
  - **vote_average** (float) - The average vote for the movie.
  - **release_date** (string) - The release date of the movie.

#### Response Example
```json
{
  "page": 1,
  "results": [
    {
      "id": 157336,
      "title": "Interstellar",
      "vote_average": 8.1,
      "release_date": "2014-11-05"
    }
  ]
}
```
```

--------------------------------

### Customize API Request Options

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Demonstrates how to customize individual API requests using an optional Axios config object. This allows for setting timeouts, headers (like language preference), or other Axios-specific configurations for fine-grained control over requests.

```javascript
// Add timeout
const movie = await moviedb.movieInfo(27205, { timeout: 10000 })

// With parameters and axios config
const movie = await moviedb.movieInfo(
  { id: 27205, append_to_response: 'credits' },
  { timeout: 10000, headers: { 'Accept-Language': 'es' } }
)
```

--------------------------------

### Movie Keywords API

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Retrieves keywords associated with a movie.

```APIDOC
## GET /movie/{id}/keywords

### Description
Retrieves keywords associated with a specific movie.

### Method
GET

### Endpoint
/movie/{id}/keywords

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier for the movie.

### Request Example
```javascript
// Assuming req.query.name contains the movie title to search for keywords
moviedb.movieKeywords({ query: req.query.name }).then(...)
```

### Response
#### Success Response (200)
- **keywords** (array) - An array of keyword objects associated with the movie.

#### Response Example
```json
{
  "id": 12345,
  "keywords": [
    {
      "id": 1001,
      "name": "based on novel"
    },
    {
      "id": 1002,
      "name": "time travel"
    }
  ]
}
```
```

--------------------------------

### Get Person Combined Credits

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieves a combined list of all movie and TV show credits for a given person. This endpoint simplifies fetching a person's entire acting and crew history across both media types.

```javascript
const credits = await moviedb.personCombinedCredits(6193)
```

--------------------------------

### movieSimilar

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieves a list of movies that are similar to a specified movie.

```APIDOC
## GET /movieSimilar

### Description
Get movies similar to a specific movie.

### Method
GET

### Endpoint
/movieSimilar

### Parameters
#### Query Parameters
- **id** (integer) - Required - The ID of the movie to find similar movies for.

### Request Example
```javascript
const similar = await moviedb.movieSimilar(27205)
```

### Response
#### Success Response (200)
- **page** (integer) - The current page of similar movies.
- **results** (array) - A list of similar movies.
  - **id** (integer) - The movie ID.
  - **title** (string) - The movie title.
  - **vote_average** (float) - The average vote for the movie.
  - **release_date** (string) - The release date of the movie.

#### Response Example
```json
{
  "page": 1,
  "results": [
    {
      "id": 49026,
      "title": "The Dark Knight Rises",
      "vote_average": 7.8,
      "release_date": "2012-07-20"
    }
  ]
}
```
```

--------------------------------

### Movie Information API

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Retrieves detailed information about a specific movie using its ID.

```APIDOC
## GET /movie/{id}

### Description
Retrieves detailed information for a specific movie using its unique ID.

### Method
GET

### Endpoint
/movie/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier for the movie.

### Request Example
```javascript
moviedb
  .movieInfo({ id: 666 })
  .then((res) => {
    console.log(res)
  })
  .catch(console.error)
```

### Response
#### Success Response (200)
- **id** (integer) - The movie's ID.
- **title** (string) - The title of the movie.
- **overview** (string) - A synopsis of the movie.
- **release_date** (string) - The release date of the movie.
- **vote_average** (number) - The average vote for the movie.

#### Response Example
```json
{
  "adult": false,
  "backdrop_path": "/path/to/backdrop.jpg",
  "belongs_to_collection": null,
  "budget": 10000000,
  "genres": [
    {
      "id": 28,
      "name": "Action"
    }
  ],
  "homepage": "http://example.com",
  "id": 666,
  "imdb_id": "tt0000001",
  "original_language": "en",
  "original_title": "Example Movie",
  "overview": "This is an example movie.",
  "popularity": 15.5,
  "poster_path": "/path/to/poster.jpg",
  "production_companies": [],
  "production_countries": [],
  "release_date": "2023-01-01",
  "revenue": 50000000,
  "runtime": 120,
  "spoken_languages": [],
  "status": "Released",
  "tagline": "An epic adventure.",
  "title": "Example Movie",
  "video": false,
  "vote_average": 7.5,
  "vote_count": 1500
}
```
```

--------------------------------

### Get Person Movie Credits

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Fetches all movie credits for a specific person, including both acting roles ('cast') and crew contributions ('crew'). Each credit entry contains details like the movie ID, title, character name (for cast), and job title (for crew).

```javascript
const credits = await moviedb.personMovieCredits(6193)

// Response structure
// {
//   id: 6193,
//   cast: [
//     { id: 27205, title: 'Inception', character: 'Dom Cobb', release_date: '2010-07-16' }
//   ],
//   crew: [
//     { id: 818647, title: 'Killers of the Flower Moon', job: 'Producer' }
//   ]
// }
```

--------------------------------

### Genre List APIs

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieves lists of official movie and TV genres.

```APIDOC
## GET /genre/movie/list

### Description
Get the list of official movie genres.

### Method
GET

### Endpoint
/genre/movie/list

### Parameters
#### Query Parameters
None

### Request Example
```javascript
const genres = await moviedb.genreMovieList()
```

### Response
#### Success Response (200)
- **genres** (array) - An array of genre objects, each with an `id` and `name`.

#### Response Example
```json
{
  "genres": [
    { "id": 28, "name": "Action" },
    { "id": 12, "name": "Adventure" },
    { "id": 16, "name": "Animation" }
  ]
}
```

## GET /genre/tv/list

### Description
Get the list of official TV genres.

### Method
GET

### Endpoint
/genre/tv/list

### Parameters
#### Query Parameters
None

### Request Example
```javascript
const genres = await moviedb.genreTvList()
```

### Response
#### Success Response (200)
- **genres** (array) - An array of genre objects, each with an `id` and `name`.
```

--------------------------------

### Session Authentication Flow

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Demonstrates the multi-step process for authenticating a user session. This involves obtaining a request token, directing the user to authorize it, and then retrieving a session ID. The session ID is crucial for performing user-specific actions.

```javascript
// Step 1: Get request token
const token = await moviedb.requestToken()
console.log(`Authorize at: https://www.themoviedb.org/authenticate/${token.request_token}`)

// Step 2: After user authorization, create session
const sessionId = await moviedb.retrieveSession()

// Step 3: Set session for future requests
moviedb.sessionId = sessionId

// Now you can access user-specific endpoints
const watchlist = await moviedb.accountMovieWatchlist()
const favorites = await moviedb.accountFavoriteMovies()
```

--------------------------------

### episodeInfo

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Retrieves detailed information for a specific TV episode, including its title, air date, overview, and cast.

```APIDOC
## GET /episodeInfo

### Description
Get details about a specific TV episode.

### Method
GET

### Endpoint
/episodeInfo

### Parameters
#### Query Parameters
- **id** (integer) - Required - The ID of the TV show.
- **season_number** (integer) - Required - The season number of the episode.
- **episode_number** (integer) - Required - The episode number.

### Request Example
```javascript
const episode = await moviedb.episodeInfo({
  id: 1396,
  season_number: 1,
  episode_number: 1
})
```

### Response
#### Success Response (200)
- **id** (integer) - The episode ID.
- **name** (string) - The episode title.
- **episode_number** (integer) - The episode number.
- **season_number** (integer) - The season number.
- **air_date** (string) - The air date of the episode.
- **overview** (string) - A summary of the episode.
- **runtime** (integer) - The duration of the episode in minutes.
- **vote_average** (float) - The average vote for the episode.
- **crew** (array) - A list of crew members involved in the episode.
- **guest_stars** (array) - A list of guest stars in the episode.

#### Response Example
```json
{
  "id": 62085,
  "name": "Pilot",
  "episode_number": 1,
  "season_number": 1,
  "air_date": "2008-01-20",
  "overview": "When an unassuming high school chemistry teacher...",
  "runtime": 58,
  "vote_average": 8.2,
  "crew": [...],
  "guest_stars": [...] 
}
```
```

--------------------------------

### TV Show Information API

Source: https://github.com/grantholle/moviedb-promise/blob/main/README.md

Retrieves detailed information about a specific TV show using its ID.

```APIDOC
## GET /tv/{id}

### Description
Retrieves detailed information for a specific TV show using its unique ID.

### Method
GET

### Endpoint
/tv/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier for the TV show.

### Request Example
```javascript
moviedb.tvInfo({ id: 61888 }).then(...)

// Or for simplicity, if it only has one placeholder
movedb.tvInfo(61888).then(...)
```

### Response
#### Success Response (200)
- **id** (integer) - The TV show's ID.
- **name** (string) - The name of the TV show.
- **overview** (string) - A synopsis of the TV show.
- **first_air_date** (string) - The first air date of the TV show.
- **vote_average** (number) - The average vote for the TV show.

#### Response Example
```json
{
  "adult": false,
  "backdrop_path": "/path/to/backdrop.jpg",
  "created_by": [],
  "episode_run_time": [50],
  "first_air_date": "2011-04-17",
  "genres": [
    {
      "id": 10759,
      "name": "Action & Adventure"
    }
  ],
  "homepage": "http://example.com",
  "id": 61888,
  "in_production": true,
  "languages": ["en"],
  "last_air_date": "2019-05-19",
  "last_episode_to_air": {
    "air_date": "2019-05-19",
    "episode_number": 6,
    "id": 1700000,
    "name": "The Iron Throne",
    "overview": "",
    "production_code": "",
    "season_number": 8,
    "still_path": "/path/to/still.jpg",
    "vote_average": 8.0,
    "vote_count": 100
  },
  "name": "Game of Thrones",
  "next_episode_to_air": null,
  "networks": [],
  "number_of_episodes": 73,
  "number_of_seasons": 8,
  "origin_country": ["US"],
  "original_language": "en",
  "original_name": "Game of Thrones",
  "overview": "Seven noble families fight for control of the mythical land of Westeros and the Iron Throne. As old rivalries<bos> wars ignite, an ancient enemy returns.",
  "popularity": 100.5,
  "poster_path": "/path/to/poster.jpg",
  "production_companies": [],
  "production_countries": [],
  "seasons": [],
  "spoken_languages": [],
  "status": "Ended",
  "tagline": "",
  "type": "Scripted",
  "vote_average": 8.5,
  "vote_count": 20000
}
```
```

--------------------------------

### Search TV Shows with moviedb-promise

Source: https://context7.com/grantholle/moviedb-promise/llms.txt

Search for TV shows by name using the `searchTv` method. This method allows filtering by language, page number, and the year of the first air date. The response provides pagination information and a list of matching TV shows.

```javascript
const results = await moviedb.searchTv({
  query: 'Breaking Bad',
  language: 'en-US',
  page: 1,
  first_air_date_year: 2008
})
```