contraktor v1.1.1

Contraktor

Warning

Written by an amateur, under heavy development, mostly untested, parts need refactoring and possibly full of bugs. You shouldn't use this yet.

About

Contraktor is a Trakt.tv API wrapper. It covers 100% of the API, performs reasonably extensive checks on the parameters to make sure garbage doesn't get out and implements a few convenience methods.

Contraktor uses Bluebird promises.

Usage

Require Contraktor and instantiate it:

var Contraktor = require('contraktor');

var trakt = new Contraktor({
    endpoint: 'staging',
    headers: {'User-Agent': 'Node.js/MyCoolApp/v1.0.0'}, // default user agent is "Node.js/Contraktor/vX.Y.Z"
    identity: {
        client_id: 'nonsense'
    }
});

endpoint lets you choose which endpoint, 'staging' or 'production', you want to use. Default is 'production'. See methods define_endpoint and switch_endpoint.

headers lets you add or override any of the headers that will be sent automatically to Trakt.tv. The default headers are:

{
    'User-Agent': 'Node.js/Contraktor/v0.6.0',
    'Content-Type': 'application/json',
    'trakt-api-version': 2
}

identity contains your credentials. Before calling any API method, you must set the client_id at the very least. You don't have to do so at construction time; you can use set_identity later.

You can now call any of the following methods.

Non-API methods

define_endpoint

Accepts two arguments, both Strings. The first is the name of the new endpoint, the other the URL. Make sure the URL doesn't have a final slash /.

Add a new endpoint for the API (or overwrite an existing one). staging and production are available out of the box.

trakt.define_endpoint('production', 'http://new-address.tv');
trakt.define_endpoint('homeproxy', 'http://my.home.net');

switch_endpoint

Accepts one argument, the name of the endpoint to switch to. By default Contraktor will hit production and can be switched to staging. Throws a ConfigurationError if you try to switch to a nonexistent endpoint.

trakt.switch_endpoint('staging');

set_headers

Accepts one argument, an object containing the header fields to set. The headers you provide will be merged with the default ones, overwriting anything.

trakt.set_headers({
    'User-Agent': 'Node.js/MyApp/v' + version
});

// You have just changed the user agent. Yayfications!

set_identity

Sets the identity Contraktor should use from now on. The object provided will overwrite whatever identity was being used until now. None of the current fields will be preserved.

At the very minimum you must provide a client_id:

trakt.set_identity({
    client_id: 'NNNOOONNNSEEEEENNNNSSSSEEEE'
});

// you have just lost any tokens, the secret and even the redirect URI.

Here's all the fields you can set:

trakt.set_identity({
    client_id: 'MYEEEEEEEYYYYYYEEEEESSSS',
    client_secret: 'MMMOOOORE NONSSSEEEEENNNSSE'
    access_token: 'OMGICANTREADTHISSTRING',
    refresh_token: 'RANDOMLETTERSANDNUMBERS',
    redirect_uri: 'urn:ietf:wg:oauth:2.0:oob', // or an actual URL, as set in your API app
    expires: 1480232313000  // epoch; set to when the access_token will expire
});

merge_identity

Accepts an object. Same as set_identity, but it won't remove fields that aren't in the object you pass. Fields that have already been set will be overwritten. It's literally just a simple merge. Use this to add new fields to your identity, such as access tokens and the like.

device_auth_step1 and device_auth_step2

These methods implement the device auth flow. Both return a promise.

When you call _step1, Contraktor will use post_oauth_device_code apiary↗ and resolve the promise with the response, so you can instruct the user. Refer to the official docs↗ to learn what the response will contain and how to use that data.

You must call _step2 with the unmodified data returned by _step1. When you do, Contraktor will poll Trakt.tv. If your user authorizes your app, the promise returned by this method will resolve with the full, updated identity (same data that get_identity would return).

If your user denies access to his account or something else goes wrong, the promise will instead reject with a hopefully useful error.

var credentials = {
    client_id: 'long garbage',
    client_secret: 'another one because why the hell not'
};

trakt.set_identity(credentials);

var auth = trakt
    .device_auth_step1()
    .then((res) => {
        console.log('Hello fellow user! On this fine day you are going to open the address ' + res.verification_url + ' and input the following code in the nice text box:');
        console.log(res.user_code);
        console.log('Toodle-loo!')
        return res;
    })
    .then((res) => trakt.device_auth_step2(res))
    .then(console.log)
    .catch(console.log);

The object res in this example looks like this:

{
  "device_code": "d9c126a7706328d808914cfd1e40274b6e009f684b1aca271b9b3f90b3630d64",
  "user_code": "5055CC52",
  "verification_url": "https://trakt.tv/activate",
  "expires_in": 600,
  "interval": 5
}

After a while it will either output the updated identity data on the console or it will reject an error.

refresh_tokens

Doesn't accept any argument. Your tokens will be refreshed, if you have all the required fields set; otherwise it's just a very complicated way of crashing. Whatever identity is currently set will be updated, if needed.

This function will be called automatically the first time you use any API methods after your credentials have expired, provided that your identity has the expires field set.

The returned promise will resolve with your now valid and updated identity.

Before quitting your app, use get_identity to get the tokens so you can store them somewhere. Or don't; nobody gives a damn about your tokens.

API methods

The following list is automatically generated from the API map. Please open an issue if you see anything wrong.

Oauth

oauth_authorize apiary↗

Currently undocumented.

post_oauth_device_code apiary↗

Generate new codes to start the device authentication process.

post_oauth_device_token apiary↗

Poll periodically to check if the user has authorized your app.

post_oauth_revoke apiary↗

🔒 OAuth required

An access_token can be revoked when a user signs out of their Trakt.tv account in your app. This is not required, but might improve the user experience so the user doesn't have an unused app connection hanging around.

post_oauth_token apiary↗

🔒 OAuth required

Currently undocumented.

Specify exactly one of the following fields: code, refresh_token

Calendars

calendars_all_movies apiary↗

✨ Extensible

Returns all movies with a release date during the time period specified.

calendars_all_shows apiary↗

✨ Extensible

Returns all shows airing during the time period specified.

calendars_all_shows_new apiary↗

✨ Extensible

Returns all new show premieres (season 1, episode 1) airing during the time period specified.

calendars_all_shows_premieres apiary↗

✨ Extensible

Returns all show premieres (any season, episode 1) airing during the time period specified.

calendars_my_movies apiary↗

🔒 OAuth required    ✨ Extensible

Returns all movies with a release date during the time period specified.

calendars_my_shows apiary↗

🔒 OAuth required    ✨ Extensible

Returns all shows airing during the time period specified.

calendars_my_shows_new apiary↗

🔒 OAuth required    ✨ Extensible

Returns all new show premieres (season 1, episode 1) airing during the time period specified.

calendars_my_shows_premieres apiary↗

🔒 OAuth required    ✨ Extensible

Returns all show premieres (any season, episode 1) airing during the time period specified.

Checkin

delete_checkin apiary↗

🔒 OAuth required

Removes any active checkins, no need to provide a specific item

post_checkin apiary↗

🔒 OAuth required

Check into a movie or episode. This should be tied to a user action to manually indicate they are watching something. The item will display as watching on the site, then automatically switch to watched status once the duration has elapsed.

Specify exactly one of the following fields: movie, episode

Comments

comments apiary↗

Returns a single comment and indicates how many replies it has.

comments_replies apiary↗

📄 Paginated

Returns all replies for a comment. It is possible these replies could have replies themselves, so in that case you would just call comments_replies again with the new comment id.

delete_comments apiary↗

🔒 OAuth required

Delete a single comment created within the last hour. This also effectively removes any replies this comment has. The OAuth user must match the author of the comment in order to delete it.

delete_comments_like apiary↗

🔒 OAuth required

Remove a like on a comment.

post_comments apiary↗

🔒 OAuth required

Add a new comment to a movie, show, season, episode, or list. Make sure to allow and encourage spoilers to be indicated in your app and follow the rules listed above.

Specify exactly one of the following fields: movie, show, season, episode, list

post_comments_like apiary↗

🔒 OAuth required

Votes help determine popular comments. Only one like is allowed per comment per user.

post_comments_replies apiary↗

🔒 OAuth required

Add a new reply to an existing comment. Make sure to allow and encourage spoilers to be indicated in your app.

put_comments apiary↗

🔒 OAuth required

Update a single comment created within the last hour. The OAuth user must match the author of the comment in order to update it.

Genres

genres apiary↗

Get a list of all genres, including names and slugs.

Movies

movies apiary↗

✨ Extensible

Returns a single movie's details.

movies_aliases apiary↗

Returns all title aliases for a movie. Includes country where name is different.

movies_anticipated apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most anticipated movies based on the number of lists a movie appears on.

movies_boxoffice apiary↗

✨ Extensible    📄 Paginated

Returns the top 10 grossing movies in the U.S. box office last weekend. Updated every Monday morning.

movies_collected apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most collected (unique users) movies in the specified time period, defaulting to weekly. All stats are relative to the specific time period.

movies_comments apiary↗

📄 Paginated

Returns all top level comments for a movie. Most recent comments returned first.

movies_people apiary↗

Returns all cast and crew for a movie. Each cast member will have a character and a standard person object.

movies_played apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most played (a single user can watch multiple times) movies in the specified time period, defaulting to weekly. All stats are relative to the specific time period.

movies_popular apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most popular movies. Popularity is calculated using the rating percentage and the number of ratings.

movies_ratings apiary↗

Returns rating (between 0 and 10) and distribution for a movie.

movies_related apiary↗

✨ Extensible

Returns related and similar movies.

movies_releases apiary↗

✨ Extensible

Returns all releases for a movie including country, certification, release date, release type, and note. The release type can be set to unknown, premiere, limited, theatrical, digital, physical, or tv. The note might have optional info such as the film festival name for a premiere release or Blu-ray specs for a physical release. We pull this info from TMDB.

movies_stats apiary↗

Returns lots of movie stats.

movies_translations apiary↗

Returns all translations for a movie, including language and translated values for title, tagline and overview.

movies_trending apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns all movies being watched right now. Movies with the most users are returned first.

movies_updates apiary↗

✨ Extensible    📄 Paginated

Returns all movies updated since the specified UTC date. We recommended storing the date so that you can be efficient using this method moving forward.

movies_watched apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most watched (unique users) movies in the specified time period, defaulting to weekly. All stats are relative to the specific time period.

movies_watching apiary↗

Returns all users watching this movie right now.

People

people apiary↗

Returns a single person's details.

people_movies apiary↗

Returns all movies where this person is in the cast or crew. Each cast object will have a character and a standard movie object.

people_shows apiary↗

Returns all movies where this person is in the cast or crew. Each cast object will have a character and a standard show object.

Recommendations

delete_recommendations_movies apiary↗

🔒 OAuth required

Hide a movie from getting recommended anymore.

delete_recommendations_shows apiary↗

🔒 OAuth required

Hide a show from getting recommended anymore.

recommendations_movies apiary↗

🔒 OAuth required    ✨ Extensible    📄 Paginated

Personalized movie recommendations for a user.

recommendations_shows apiary↗

🔒 OAuth required    ✨ Extensible    📄 Paginated

Personalized show recommendations for a user.

Scrobble

post_scrobble_pause apiary↗

🔒 OAuth required

Use this method when the video is paused. The playback progress will be saved and sync_playback can be used to resume the video from this exact position. Unpause a video by calling the post_scrobble_start method again.

Specify exactly one of the following fields: movie, episode

post_scrobble_start apiary↗

🔒 OAuth required

Use this method when the video intially starts playing or is unpaused. This will remove any playback progress if it exists.

Specify exactly one of the following fields: movie, episode

post_scrobble_stop apiary↗

🔒 OAuth required

Use this method when the video is stopped or finishes playing on its own. If the progress is above 80%, the video will be scrobbled and the action will be set to scrobble.

If the progress is less than 80%, it will be treated as a pause and the action will be set to pause. The playback progress will be saved and sync_playback can be used to resume the video from this exact position.

Specify exactly one of the following fields: movie, episode

Search

search apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Use this to perform a text query that searches titles, descriptions, translated titles, aliases, and people. Items searched include movies, shows, episodes, people, and lists. Results are ordered by the most relevant score.

Using this same method you can also perform a search by ID, either a Trakt.tv ID or an external one. You can for example learn the IMDB id using the Trakt.tv id.

Shows

shows apiary↗

✨ Extensible

Returns a single shows's details. If you get extended info, the airs object is relative to the show's country. You can use the day, time, and timezone to construct your own date then convert it to whatever timezone your user is in.

shows_aliases apiary↗

Returns all title aliases for a show. Includes country where name is different.

shows_anticipated apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most anticipated shows based on the number of lists a show appears on.

shows_collected apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most collected (unique users) shows in the specified time period, defaulting to weekly. All stats are relative to the specific time period.

shows_comments apiary↗

📄 Paginated

Returns all top level comments for a show. Most recent comments returned first.

shows_people apiary↗

Returns all cast and crew for a show. Each cast member will have a character and a standard person object.

The crew object will be broken up into production, art, crew, costume & make-up, directing, writing, sound, and camera (if there are people for those crew positions). Each of those members will have a job and a standard person object.

shows_played apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most played (a single user can watch multiple episodes multiple times) shows in the specified time period, defaulting to weekly. All stats are relative to the specific time period.

shows_popular apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most popular shows. Popularity is calculated using the rating percentage and the number of ratings.

shows_progress_collection apiary↗

🔒 OAuth required

Returns collection progress for show including details on all seasons and episodes. The next_episode will be the next episode the user should collect, if there are no upcoming episodes it will be set to null. By default, any hidden seasons will be removed from the response and stats. To include these and adjust the completion stats, set the hidden flag to true.

shows_ratings apiary↗

Returns rating (between 0 and 10) and distribution for a show

shows_related apiary↗

✨ Extensible    📄 Paginated

Returns related and similar shows.

shows_seasons apiary↗

✨ Extensible

Returns all seasons for a show including the number of episodes in each season. If you set extended to "episodes", it will return all episodes for all seasons. This is expensive, so evoid doing it unless you really need to. If you specify a season, you will get information on all episodes of that season only.

shows_seasons_comments apiary↗

📄 Paginated

Returns all top level comments for a season. Most recent comments returned first.

shows_seasons_episodes apiary↗

✨ Extensible

Returns a single episode's details. All date and times are in UTC and were calculated using the episode's air_date and show's country and air_time.

shows_seasons_episodes_comments apiary↗

📄 Paginated

Returns all top level comments for an episode. Most recent comments returned first.

shows_seasons_episodes_ratings apiary↗

Returns rating (between 0 and 10) and distribution for an episode.

shows_seasons_episodes_stats apiary↗

Returns lots of episode stats.

shows_seasons_episodes_watching apiary↗

Returns all users watching this episode right now.

shows_seasons_ratings apiary↗

Returns rating (between 0 and 10) and distribution for a season.

shows_seasons_stats apiary↗

Returns lots of season stats.

shows_seasons_watching apiary↗

Returns all users watching this season right now.

shows_stats apiary↗

Returns lots of show stats.

shows_translations apiary↗

Returns all translations for a show, including language and translated values for title and overview.

shows_trending apiary↗

📄 Paginated    🎚 Filterable

Returns all shows being watched right now. Shows with the most users are returned first.

shows_updates apiary↗

✨ Extensible    📄 Paginated

Returns all shows updated since the specified UTC date. We recommended storing the date you can be efficient using this method moving forward.

shows_watched apiary↗

✨ Extensible    📄 Paginated    🎚 Filterable

Returns the most watched (unique users) shows in the specified time period, defaulting to weekly. All stats are relative to the specific time period.

shows_watching apiary↗

Returns all users watching this show right now.

Sync

delete_sync_playback apiary↗

🔒 OAuth required

Remove a playback item from a user's playback progress list.

post_sync_collection apiary↗

🔒 OAuth required

Add items to a user's collection. Accepts shows, seasons, episodes and movies. If only a show is passed, all episodes for the show will be collected. If seasons are specified, all episodes in those seasons will be collected.

Send a collected_at UTC datetime to mark items as collected in the past. You can also send additional metadata about the media itself to have a very accurate collection. Showcase what is available to watch from your epic HD DVD collection down to your downloaded iTunes movies.

Specify exactly one of the following fields: movies, shows, episodes

post_sync_collection_remove apiary↗

🔒 OAuth required

Remove one or more items from a user's collection.

Specify exactly one of the following fields: movies, shows, episodes

post_sync_history apiary↗

🔒 OAuth required

Add items to a user's watch history. Accepts shows, seasons, episodes and movies. If only a show is passed, all episodes for the show will be added. If seasons are specified, only episodes in those seasons will be added.

Send a watched_at UTC datetime to mark items as watched in the past. This is useful for syncing past watches from a media center.

Specify exactly one of the following fields: movies, shows, episodes

post_sync_history_remove apiary↗

🔒 OAuth required

Remove items from a user's watch history including all watches, scrobbles, and checkins. Accepts shows, seasons, episodes and movies. If only a show is passed, all episodes for the show will be removed. If seasons are specified, only episodes in those seasons will be removed.

You can also send a list of raw history ids to delete single plays from the watched history. The sync_history method will return an individual id for each history item.

Specify exactly one of the following fields: movies, shows, episodes

post_sync_ratings apiary↗

Rate one or more items. Accepts shows, seasons, episodes and movies. If only a show is passed, only the show itself will be rated. If seasons are specified, all of those seasons will be rated.

Send a rated_at UTC datetime to mark items as rated in the past. This is useful for syncing ratings from a media center.

Specify exactly one of the following fields: movies, shows, episodes

post_sync_ratings_remove apiary↗

🔒 OAuth required

Remove ratings for one or more items.

Specify exactly one of the following fields: movies, shows, episodes

post_sync_watchlist apiary↗

🔒 OAuth required

Add one of more items to a user's watchlist. Accepts shows, seasons, episodes and movies. If only a show is passed, only the show itself will be added. If seasons are specified, all of those seasons will be added.

Specify exactly one of the following fields: movies, shows, episodes

post_sync_watchlist_remove apiary↗

🔒 OAuth required

Remove one or more items from a user's watchlist.

Specify exactly one of the following fields: movies, shows, episodes

sync_collection apiary↗

🔒 OAuth required    ✨ Extensible

Get all collected items in a user's collection. A collected item indicates availability to watch digitally or on physical media.

If you set extended to "metadata", it will return the additional media_type, resolution, audio, audio_channels and '3d' metadata. It will use null if the metadata isn't set for an item.

sync_history apiary↗

🔒 OAuth required    ✨ Extensible

Returns movies and episodes that a user has watched, sorted by most recent. You can optionally limit the type to movies or episodes. The id in each history item uniquely identifies the event and can be used to remove individual events by using the post_sync_history_remove method. The action will be set to scrobble, checkin, or watch.

Specify a type and trakt id to limit the history for just that item. If the id is valid, but there is no history, an empty array will be returned.

sync_last_activities apiary↗

🔒 OAuth required

This method is a useful first step in the syncing process. We recommended caching these dates locally, then you can compare to know exactly what data has changed recently. This can greatly optimize your syncs so you don't pull down a ton of data only to see nothing has actually changed.

sync_playback apiary↗

🔒 OAuth required

Whenever a scrobble is paused, the playback progress is saved. Use this progress to sync up playback across different media centers or apps. For example, you can start watching a movie in a media center, stop it, then resume on your tablet from the same spot. Each item will have the progress percentage between 0 and 100.

You can optionally specify a type to only get movies or episodes.

By default, all results will be returned. However, you can send a limit if you only need a few recent results for something like an "on deck" feature.

sync_ratings apiary↗

🔒 OAuth required    ✨ Extensible

Get a user's ratings filtered by type. You can optionally filter for a specific rating between 1 and 10.

sync_watched apiary↗

🔒 OAuth required    ✨ Extensible

Returns all movies or shows a user has watched.

sync_watchlist apiary↗

🔒 OAuth required    ✨ Extensible

Returns all items in a user's watchlist filtered by type. When an item is watched, it will be automatically removed from the watchlist.

Users

delete_users_follow apiary↗

🔓 OAuth optional

Unfollow someone you already follow.

delete_users_lists apiary↗

🔒 OAuth required

Remove a custom list and all items it contains.

delete_users_lists_like apiary↗

🔒 OAuth required

Remove a like on a list.

delete_users_requests apiary↗

🔒 OAuth required

Deny a follower using the id of the request.

post_users_follow apiary↗

🔓 OAuth optional

Follow a user. If the user has a private profile, the follow request will require approval (approved_at will be null). If a user is public, they will be followed immediately (approved_at will have a date).

post_users_lists apiary↗

🔓 OAuth optional

Create a new custom list. The name is the only required field, but the other info is recommended to ask for.

post_users_lists_items apiary↗

🔒 OAuth required

Add one or more items to a custom list. Items can be movies, shows, seasons, episodes, or people.

post_users_lists_items_remove apiary↗

🔒 OAuth required

Remove one or more items from a custom list.

post_users_lists_like apiary↗

🔒 OAuth required

Votes help determine popular lists. Only one like is allowed per list per user.

post_users_requests apiary↗

🔒 OAuth required

Approve a follower using the id of the request.

users apiary↗

🔓 OAuth optional

Get a user's profile information. If the user is private, info will only be returned if you send OAuth and are either that user or an approved follower.

users_collection apiary↗

🔓 OAuth optional    ✨ Extensible

Get all collected items in a user's collection. A collected item indicates availability to watch digitally or on physical media.

If you set extended to "metadata", it will return the additional media_type, resolution, audio, audio_channels and '3d' metadata. It will use null if the metadata isn't set for an item.

users_comments apiary↗

🔓 OAuth optional    📄 Paginated

Returns comments a user has posted sorted by most recent.

users_followers apiary↗

🔓 OAuth optional

Returns all followers including when the relationship began.

users_friends apiary↗

🔓 OAuth optional

Returns all friends for a user including when the relationship began. Friendship is a 2 way relationship where each user follows the other

users_hidden apiary↗

🔒 OAuth required    📄 Paginated

Get hidden items for a section. This will return an array of standard media objects. You can optionally limit the type of results to return.

users_history apiary↗

🔓 OAuth optional    📄 Paginated

Returns movies and episodes that a user has watched, sorted by most recent. You can optionally limit the type to movies or episodes.

users_likes apiary↗

🔒 OAuth required    📄 Paginated

Get items a user likes. This will return an array of standard media objects. You can optionally limit the type of results to return.

users_lists apiary↗

🔓 OAuth optional

Returns all custom lists for a user. Use users_lists_items to get the actual items a specific list contains. Specify an id to get a single custom list.

`users_lists_c