Home Reference Source Test Repository 
import Authorization from '@npr/npr-one-sdk/controller/authorization.js'
public class | source

Authorization

Encapsulates all of the logic for communication with the Authorization Service in the NPR One API.

Note that consumers should not be accessing this class directly but should instead use the provided pass-through functions in the main NprOneSDK class.

Example:

Rudimentary example of implementing the Device Code flow
const nprOneSDK = new NprOneSDK();
nprOneSDK.config = { ... };
const scopes = ['identity.readonly', 'identity.write', 'listening.readonly', 'listening.write'];
nprOneSDK.getDeviceCode(scopes)
    .then((deviceCodeModel) => {
        // display code to user on the screen
        nprOneSDK.pollDeviceCode()
            .then(() => {
                nprOneSDK.getRecommendation();
            });
     })
    .catch(() => {
        nprOneSDK.getDeviceCode(scopes).then(...); // repeat ad infinitum until `pollDeviceCode()` resolves successfully
        // In actual use, it may be preferable to refactor this into a recursive function
    ));

Test:

Static Method Summary

Static Public Methods
public static

Attempts to swap the existing access token for a new one using the refresh token endpoint in the OAuth proxy

Constructor Summary

Public Constructor
public

Initializes the controller class with private variables needed later on.

Method Summary

Public Methods
public

Uses the OAuth proxy to start a device_code grant flow.
public

Logs out the user, revoking their access token from the authorization server and removing the refresh token from the secure storage in the backend proxy (if a backend proxy is configured).
public

Uses the OAuth proxy to poll the access token endpoint as part of a device_code grant flow.

Static Public Methods

public static refreshExistingAccessToken(numRetries: number): Promise<AccessToken> source

Attempts to swap the existing access token for a new one using the refresh token endpoint in the OAuth proxy

Params:

NameTypeAttributeDescription
numRetries number
  • optional
  • default: 0

The number of times this function has been tried. Will retry up to 3 times.

Return:

Promise<AccessToken>

Throw:

TypeError

if an OAuth proxy is not configured or no access token is set

Test:

Public Constructors

public constructor source

Initializes the controller class with private variables needed later on.

Public Methods

public getDeviceCode(scopes: Array<string>): Promise<DeviceCode> source

Uses the OAuth proxy to start a device_code grant flow. This function just makes an API call that produces a device code/user code pair, and should be followed up with a call to pollDeviceCode in order to complete the process.

Note that device code/user code pairs do expire after a set time, so the consuming client may need to call these 2 functions multiple times before the user logs in. It is a good idea to encapsulate them in a function which can be called recursively on errors; see the example below for details.

Params:

NameTypeAttributeDescription
scopes Array<string>
  • optional
  • default: []

The scopes (as strings) that should be associated with the resulting access token

Return:

Promise<DeviceCode>

Throw:

TypeError

if an OAuth proxy is not configured

Example:

function logInViaDeviceCode(scopes) {
    nprOneSDK.getDeviceCode(scopes)
        .then((deviceCodeModel) => {
            displayCodeToUser(deviceCodeModel); // display code to user on the screen
            nprOneSDK.pollDeviceCode()
                .then(() => {
                    startPlayingAudio(); // you're now ready to call `nprOneSDK.getRecommendation()` elsewhere in your app
                }).catch(logInViaDeviceCode.bind(this, scopes)); // recursively call this function until the user logs in
        });
}

Test:

See:

public logout(): Promise source

Logs out the user, revoking their access token from the authorization server and removing the refresh token from the secure storage in the backend proxy (if a backend proxy is configured). Note that the consuming client is still responsible for removing the access token anywhere else it might be stored outside of this SDK (e.g. in localStorage or elsewhere in application memory).

Return:

Promise

Throw:

TypeError

if an OAuth proxy is not configured or no access token is currently set

Test:

public pollDeviceCode(): Promise<AccessToken> source

Uses the OAuth proxy to poll the access token endpoint as part of a device_code grant flow. This endpoint will continue to poll until the user successfully logs in, or the user goes to log in but then denies the request for access to their account by this client, or the device code/user code pair expires, whichever comes first. In the first case, it will automatically set NPROneSDK.accessToken to the newly-generated access token, and the consuming client can proceed to play recommendations immediately; in the other 2 cases, it will return a Promise that rejects with a debugging message, but the next course of action would generally be to call getDeviceCode again and start the whole process from the top.

Return:

Promise<AccessToken>

Throw:

TypeError

if an OAuth proxy is not configured or getDeviceCode() was not previously called

Example:

function logInViaDeviceCode(scopes) {
    nprOneSDK.getDeviceCode(scopes)
        .then((deviceCodeModel) => {
            displayCodeToUser(deviceCodeModel); // display code to user on the screen
            nprOneSDK.pollDeviceCode()
                .then(() => {
                    startPlayingAudio(); // you're now ready to call `nprOneSDK.getRecommendation()` elsewhere in your app
                }).catch(logInViaDeviceCode.bind(this, scopes)); // recursively call this function until the user logs in
        });
}

Test:

See: