@idavide94/trakt.tv-userscript

forked from trakt.tv

Trakt.tv API wrapper for userscripts, featuring:

• All Trakt.tv API v2 methods
• Plugin extension[^wip]

For more information about the trakt.tv API, read http://docs.trakt.apiary.io/

Example usage

Setup

Add to a userscript via @require:

// @require   https://cdn.jsdelivr.net/npm/@idavide94/trakt.tv-userscript/dist/index.min.js
// @grant     GM.xmlHttpRequest

attention: for the proper working of the library the use of GM.xmlHttpRequest via @grant is required!

Initialize

const options = {
  client_id: '<the_client_id>',
  client_secret: '<the_client_secret>',
  redirect_uri: null, // defaults to 'urn:ietf:wg:oauth:2.0:oob'
  api_url: null, // defaults to 'https://api.trakt.tv'
  useragent: null, // defaults to 'trakt.tv/<version>'
  pagination: true // defaults to false, global pagination (see below)
}
const trakt = new Trakt(options)

note: add debug: true to the options object to get debug logs of the requests executed in your console

OAUTH

1. Generate Auth URL

const traktAuthUrl = trakt.get_url()

2. Authentication is done at that URL, it redirects to the provided uri with a code and a state

3. Verify code (and optionally state for better security) from returned auth, and get a token in exchange

trakt.exchange_code('code', 'csrf token (state)').then((result) => {
  // contains tokens & session information
  // API can now be used with authorized requests
})

Alternate OAUTH "device" method

trakt
  .get_codes()
  .then((poll) => {
    // poll.verification_url: url to visit in a browser
    // poll.user_code: the code the user needs to enter on trakt

    // verify if app was authorized
    return trakt.poll_access(poll)
  })
  .catch((error) => {
    // error.message == 'Expired' will be thrown if timeout is reached
  })

Refresh token

trakt.refresh_token().then((results) => {
  // results are auto-injected in the main module cache
})

Storing token over sessions

// get token, store it safely.
const token = trakt.export_token()

// injects back stored token on new session.
trakt.import_token(token).then((newTokens) => {
  // Contains token, refreshed if needed (store it back)
})

Revoke token

trakt.revoke_token()

Actual API requests

See methods in methods.json or the docs.

trakt.calendars.all
  .shows({
    start_date: '2015-11-13',
    days: '7',
    extended: 'full'
  })
  .then((shows) => {
    // Contains Object{} response from API (show data)
  })

trakt.search
  .text({
    query: 'tron',
    type: 'movie,person'
  })
  .then((response) => {
    // Contains Array[] response from API (search data)
  })

trakt.search
  .id({
    id_type: 'imdb',
    id: 'tt0084827'
  })
  .then((response) => {
    // Contains Array[] response from API (imdb data)
  })

Using pagination

You can extend your calls with pagination: true to get the extra pagination info from headers.

trakt.movies
  .popular({
    pagination: true
  })
  .then((movies) => {
    /**
    movies = Object {
      data: [<actual data from API>],
        pagination: {
          item-count: "80349",
            limit: "10",
            page: "1",
            page-count: "8035"
        }
    }
    **/
  })

note: this will contain data and pagination for all calls, even if no pagination is available (result.pagination will be false). it's typically for advanced use only

Load plugins[^wip]

When calling new Trakt(), include desired plugins in an object (must be installed from npm):

const trakt = new Trakt({
  client_id: '<the_client_id>',
    client_secret: '<the_client_secret>',
    plugins: {  // load plugins
        images: require('trakt.tv-images')
    }
    options: {  // pass options to plugins
        images: {
          smallerImages: true
        }
    }
});

The plugin can be accessed with the key you specify. For example trakt.images.get().

Write plugins[^wip]

See the documentation.

Notes

• You can use 'me' as username if the user is authenticated.
• Timestamps (such as token expires property) are Epoch in milliseconds.

[^wip]: plugins, and related docs, are currently a work in progress for this fork