Skip to content

f785bub0.md

Latest commit

 

History

History
46 lines (41 loc) · 4.84 KB

f785bub0.md

File metadata and controls

46 lines (41 loc) · 4.84 KB

Trakt.tv | Trakt API Wrapper

Exposes an authenticated Trakt API Wrapper. Intended to run alongside other userscripts which require (authenticated) access to the Trakt API.

install standard install minified version lines of code

Info

Based on iDavide94/iFelix18's Trakt API wrapper for userscripts which in turn was based on vankasteelj's Trakt.tv API wrapper for Node.js.

General

  • If you're not interested in the technical details, then the rest of the documentation here will probably be of little interest to you. This script will mostly speed up some of my other userscripts which would otherwise scrape the respective data instead of pulling it from the api (the api responses are cached for 8 hours).
  • This wrapper is entirely self sufficient and requires no prior configuration or user input. It creates its own api application, fetches the respective client credentials and authenticates the user on the fly when a method is called. You can change the name and description of that api application to whatever you like, however please keep in mind that the name (in addition to the id) is used for checking for an existing application before creating a new one (useful after script reinstall). If you delete it a new one will be created in its place when the wrapper is used again.
  • Only works if a user is logged in.
  • The methods were last updated in Jan. 2026.

Usage

  • The wrapper is exposed through window.userscriptTraktApiWrapper and can be used like:
    const { data, meta } = await userscriptTraktApiWrapper.search.id({ id_type: 'trakt', id: 1234, type: 'episode', extended: 'full', _auth: true, _meta: true, _revalidate: true });
    There are two types of props you can pass to a method, parameters corresponding to those listed in the Trakt API docs and options (denoted by a leading _) for the wrapper itself.
  • Parameters
    There are three categories: path parameters, search parameters, and the props for the request's body. First the mandatory and optional parameters for the path are filled in, then for GET/DELETE requests the remaining parameters are appended as search parameters, whereas for POST/PUT requests they are added to the body.
  • Options
    • _method - The type of HTTP request to make, normally supplied by the method config, but as with all options you can override it.
    • _path - The path template to use, normally supplied by the method config. Override it in case it's outdated.
    • _auth - Whether to authenticate the request. Normally supplied by the method config for methods with mandatory authentication. Override it to enable optional authentication (which also has a separate rate limit).
    • _meta - Whether to wrap the response's data in an object with the supplied trakt header metadata like: { data: returned_data, meta: { pagination_page: 3 } }. meta includes all the trakt x--prefixed headers and a couple select others in a normalized form to allow for dot-syntax access. Type coercion is done for numbers and booleans. It's also included as parsedTraktHeaders with the raw response object which get's thrown in case of a failed request.
    • _revalidate - Whether to revalidate the data instead of directly pulling it from the disk cache when possible.
    • _retry - Configuration for a basic exponential backoff based retry mechanism. By default only activated for authed POST/PUT/DELETE requests. Doesn't use the ratelimit and retry_after trakt headers. Takes a config object like { limit: 5, req_delay: 1000, resp_delay: 0 }, with each retry limit gets decremented (= 5 retries) and req_delay doubled. If you want to turn it off you can just override it with _retry: null.
  • In the userscript storage tab you can change the apiUrl to https://api-staging.trakt.tv for a sandbox environment and you can activate console logging of all api requests with logApiRequests.
  • There's built-in rate-limiting for authed POST/PUT/DELETE requests (1/sec), which is complemented by the default _retry config, so you can just make a bunch of requests at once and they'll be queued up and executed one by one in the same order in which you made them (retries will block the queue).