Have ideas to improve npm?Join in the discussion! »

    moviedb-promise
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.8 • Public • Published

    moviedb-promise

    npm

    A Node library that makes the interaction with themoviedb.org V3 API easy... Now in TypeScript!

    This was originally a pull request that went stale, so it's its own package now. The original package developed by Dan Zajdband uses callbacks to handle the asynchronous nature of Node, while this package uses native Promises.

    The main credit goes to the original moviedb package by Dan Zajdband.

    Changelog for v3

    • Each tmdb function has the correct parameter and response types based on the documentation
    • append_to_response should be added to the request parameter of the appropriate functions and not on the options
    • The last parameter to each function can be an axios config object and will overwrite anything on the underlying request.
    • Several functions have been renamed.
    • Search functions accept a string and will be used for the query property.

    Changelog for v2

    • Source has been ported to TypeScript.
    • Rate limiting was removed by tmdb. The functionality had remained, but has since been removed in v2. If you wish to add it back, you're welcome to open a PR to discuss its need.
    • The MovieDb class has been moved to be a property of the package export. You will need to reference the MovieDb property of the export in order to instantiate the class. See usage below for an example.
    • The constructor has been changed to accept only two parameters: an api key and the base url for tmdb.
    • The session() function has been renamed to retrieveSession()
    • Requests were previously made using superagent as it was used by the original moviedb package. It has been replaced with axios now.

    Integrations

    Installation

    npm install moviedb-promise --save

    Usage

    Require the module and instantiate the class with your themoviedb.org api key.

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

    async/await reminder

    All functions return a Promise, which means that you can also use async/await. The caveat of using await when making function calls is that the await has to be within a function that has been declared async. Keep that in mind if you plan to use await.

    Examples

    // Using just the Promise
    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
    }

    or

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

    Some endpoints, such as watchlist endpoints, have an optional account id parameter. If you have a session id, you don't need to provide that parameter.

    // 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)

    Available methods

    The Function column lists all the available functions in the class. The Endpoint column lists possible request parameters (placeholders prefixed with :) needed for the call. If the endpoint doesn't have any placeholders, check out the documentation for the query parameters you can use.

    Examples

    Function Endpoint
    tvInfo tv/:id
    // 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(...)
    Function Endpoint
    searchMovie search/movie

    There aren't any placeholders, but the documentation shows there are language, query, page, include_adult, region, year, and primary_release_year available to use. Each expects a certain data type or format, so check out the docs for the details.

    const parameters = {
      query: 'Kindergarten Cop',
      language: 'fr' // ISO 639-1 code
    }
    
    moviedb.searchMovie(parameters).then(...)

    Complete function list

    Function
    configuration
    countries
    jobs
    languages
    primaryTranslations
    timezones
    find
    searchCompany
    searchCollection
    searchKeyword
    searchMovie
    searchMulti
    searchPerson
    searchTv
    searchList
    collectionInfo
    collectionImages
    collectionTranslations
    discoverMovie
    discoverTv
    trending
    movieInfo
    movieAccountStates
    movieAlternativeTitles
    movieChanges
    movieCredits
    movieExternalIds
    movieImages
    movieKeywords
    movieReleaseDates
    movieVideos
    movieWatchProviders
    movieTranslations
    movieRecommendations
    movieSimilar
    movieReviews
    movieLists
    movieRatingUpdate
    movieRatingDelete
    movieLatest
    movieNowPlaying
    moviePopular
    movieTopRated
    upcomingMovies
    tvInfo
    tvAccountStates
    tvAlternativeTitles
    tvChanges
    tvContentRatings
    tvCredits
    episodeGroups
    tvExternalIds
    tvImages
    tvKeywords
    tvRecommendations
    tvReviews
    tvScreenedTheatrically
    tvSimilar
    tvTranslations
    tvVideos
    tvWatchProviders
    tvRatingUpdate
    tvRatingDelete
    tvLatest
    tvAiringToday
    tvOnTheAir
    tvPopular
    tvTopRated
    seasonInfo
    seasonChanges
    seasonAccountStates
    seasonCredits
    seasonExternalIds
    seasonImages
    seasonVideos
    episodeInfo
    episodeChanges
    episodeAccountStates
    episodeCredits
    episodeExternalIds
    episodeImages
    episodeTranslations
    episodeRatingUpdate
    episodeRatingDelete
    episodeVideos
    personInfo
    personChanges
    personMovieCredits
    personTvCredits
    personCombinedCredits
    personExternalIds
    personImages
    personTaggedImages
    personTranslations
    personLatest
    personPopular
    creditInfo
    listInfo
    listStatus
    createList
    createListItem
    removeListItem
    clearList
    deleteList
    genreMovieList
    genreTvList
    keywordInfo
    keywordMovies
    companyInfo
    companyAlternativeNames
    companyImages
    accountInfo
    accountLists
    accountFavoriteMovies
    accountFavoriteTv
    accountFavoriteUpdate
    accountRatedMovies
    accountRatedTv
    accountRatedTvEpisodes
    accountMovieWatchlist
    accountTvWatchlist
    accountWatchlistUpdate
    changedMovies
    changedTvs
    changedPeople
    movieCertifications
    tvCertifications
    networkInfo
    networkAlternativeNames
    networkImages
    review
    episodeGroup

    Support for append_to_response

    The movieInfo, tvInfo, tvSeasonInfo, tvEpisodeInfo and personInfo methods support an option to specify the TMDB API's append_to_response query parameter. This makes it possible to make sub requests within the same namespace in a single HTTP request. Each request will get appended to the response as a new JSON object.

    In order to receive type support for the items returned with an append_to_response request, you'll need to cast the attributes as their appropriate type. Note this requires you to be using TypeScript.

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

    In this case, response.release_dates will be cast as MovieReleaseDatesResponse since it's not in the default MovieResponse that gets returned with movieInfo().

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

    Request Options

    The last parameter of the endpoint function calls is an axios request config object. Those settings will overwrite anything on the underlying request.

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

    or when combining multiple options append_to_response is desired:

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

    Contributing

    First, thanks for taking the time!

    Second, before submitting a pull request, make sure to run npm run test to make sure the tests pass and if you add any features be sure to add the appropriate tests.

    License

    MIT

    Install

    npm i moviedb-promise

    DownloadsWeekly Downloads

    237

    Version

    3.1.8

    License

    MIT

    Unpacked Size

    149 kB

    Total Files

    15

    Last publish

    Collaborators

    • avatar