traktdeviceauth

README

Go Trakt Device Auth Library

A Go library to allow an end user to authorize a third-party Trakt application access to their account using the device method.

Conventions

Client ID and Client Secret

Throughout the library, the Client ID and Client Secret are used to tell Trakt which app is requesting access. These values are found in the dashboard for the app on Trakt's website, as shown in the image below.

Context Functions

Many functions in this library have context counterparts which allow a custom context.Context to be used. If you don't know what all this means, you'll probably be fine sticking with the non-context versions.

Installation

As a Go library: go get -u github.com/BrenekH/go-traktdeviceauth

As an executable: go install github.com/BrenekH/go-traktdeviceauth/cmd@latest or download from the latest release.

Usage

As suggested by the official API docs, a device and user code pair must be generated as the first step using GenerateNewCode. Next, the user needs to directed to the returned verification url and instructed to enter the user code into the website. Finally, PollForAuthToken is used to wait for the user to complete authentication or the code to expire.

If the returned access token expires, a new one can be generated with asking the user to re-authenticate by using RefreshAccessToken

Trakt recommends that the AccessToken and RefreshToken be saved in permanent storage so that the user doesn't need to log in every time your program starts.

License

This project is licensed under the Apache 2.0 license, a copy of which can be found in LICENSE.

Documentation

Index

• Variables
• type CodeResponse
  • func GenerateNewCode(clientID string) (CodeResponse, error)
  • func GenerateNewCodeContext(ctx context.Context, clientID string) (CodeResponse, error)
• type TokenResponse
  • func PollForAuthToken(codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)
  • func PollForAuthTokenContext(ctx context.Context, codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)
  • func RefreshAccessToken(refreshToken, clientID, clientSecret string) (TokenResponse, error)
  • func RefreshAccessTokenContext(ctx context.Context, refreshToken, clientID, clientSecret string) (TokenResponse, error)
  • func RequestToken(codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)
  • func RequestTokenContext(ctx context.Context, codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)

Variables

var (
	ErrDeviceCodeUnclaimed       error = errors.New("the user has not yet claimed the device code")                            // 400
	ErrInvalidGrant              error = errors.New(invalidGrantText)                                                          // 401
	ErrInvalidDeviceCode         error = errors.New("invalid device code")                                                     // 404
	ErrForbidden                 error = errors.New("invalid API key or unapproved application")                               // 403
	ErrDeviceCodeAlreadyApproved error = errors.New("device code has already been approved")                                   // 409
	ErrDeviceCodeExpired         error = errors.New("the device code has expired, please regenerate a new one")                // 410
	ErrDeviceCodeDenied          error = errors.New("the device code was denied by the user")                                  // 418
	ErrPollRateTooFast           error = errors.New("the API is being polled too quickly")                                     // 429
	ErrServerError               error = errors.New("the Trakt API is reporting an internal problem, please check back later") // 500
	ErrServiceOverloaded         error = errors.New("the servers are overloaded, please try again in 30 seconds")              // 503, 504
	ErrCloudflareError           error = errors.New("there is an issue with Cloudflare")                                       // 520, 521, 522
)

var TraktAPIBaseUrl string = "https://api.trakt.tv"

TraktAPIBaseUrl is the base url for all API requests. This shouldn't need to be modified unless targetting a different server, for instance the staging server (https://api-staging.trakt.tv)

Types

type CodeResponse

type CodeResponse struct {
	DeviceCode      string `json:"device_code"`
	UserCode        string `json:"user_code"`
	VerificationURL string `json:"verification_url"`
	ExpiresIn       int    `json:"expires_in"` // How long the code will last in seconds
	Interval        int    `json:"interval"`   // The interval in seconds that the application is allowed to poll at
}

CodeResponse is used to contain the results of GenerateNewCode. The user should be directed to VerificationURL and instructed to enter UserCode into the box presented. None of this data needs to persist between restarts.

func GenerateNewCode

func GenerateNewCode(clientID string) (CodeResponse, error)

GenerateNewCode wraps GenerateNewCodeContext using context.Background().

func GenerateNewCodeContext

func GenerateNewCodeContext(ctx context.Context, clientID string) (CodeResponse, error)

GenerateNewCodeContext reaches out to the Trakt API to acquire a claimable code.

type TokenResponse

type TokenResponse struct {
	AccessToken  string
	TokenType    string
	ExpiresAt    time.Time
	RefreshToken string
	Scope        string
	CreatedAt    time.Time
}

TokenResponse contains the results of RequestToken. This data should persist between restarts unless you want to prompt the user to authorize your app on every launch.

func PollForAuthToken

func PollForAuthToken(codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)

PollForAuthToken wraps PollForAuthTokenContext using context.Background().

func PollForAuthTokenContext

func PollForAuthTokenContext(ctx context.Context, codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)

PollForAuthTokenContext continuously polls for the access token from a CodeResponse. The passed context is truncated using context.WithDeadline to match the CodeResponse.ExpiresIn value.

func RefreshAccessToken

func RefreshAccessToken(refreshToken, clientID, clientSecret string) (TokenResponse, error)

RefreshAccessToken wraps RefreshAccessTokenContext with a context.Background() struct. Please refer to RefreshAccessTokenContext for documentation.

func RefreshAccessTokenContext

func RefreshAccessTokenContext(ctx context.Context, refreshToken, clientID, clientSecret string) (TokenResponse, error)

RefreshAccessTokenContext takes the refresh token from a previous TokenResponse and creates a new one. This should only be used when an AccessToken expires (after about 3 months according to Trakt).

func RequestToken

func RequestToken(codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)

RequestToken wraps RequestTokenContext using context.Background().

func RequestTokenContext

func RequestTokenContext(ctx context.Context, codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)

RequestTokenContext determines returns a TokenResponse if the provided code has been claimed by the user. If it has not, or there is another error, it will RequestTokenContext returns a customized error value which details the issue.

This function is provided as a convenience, but it is recommended to use PollForAuthToken unless you have a very specific use case for this function.