Home Reference Source Test Repository
import {NprOneSDK} from '@npr/npr-one-sdk/index.js'
public class | source

NprOneSDK

This SDK attempts to abstract away most of the interaction with the NPR One API. In general, a consumer of this API should be primarily concerned with asking for recommendations and recording user actions against those recommendations.

Test:

Static Member Summary

Static Public Members
public static get

Exposes the Action class for clients to record actions

public static get

Exposes the Logger class for clients to adjust logging if desired

public static get
public static set
public static get
public static set

Updates private _config member attributes but does not overwrite entire _config object

public static set

Sets a callback to be triggered whenever the SDK rotates the access token for a new one, usually when the old token expires and a refresh_token is used to generate a fresh token.

Static Method Summary

Static Public Methods
public static

Returns the foundational path for a given service

public static

Constructor Summary

Public Constructor
public

Instantiates the NPR One SDK.

Method Summary

Public Methods
public

See Identity#createTemporaryUser for description.

public

followShow(aggregationId: number | string): Promise<User>

See Identity#followShow for description.

public

See Authorization#getDeviceCode for description.

public

See Listening#getHistory for description.

public

See Listening#getRecommendation for description.

public
public

See StationFinder#getStationDetails for description.

public
this method is experimental.
public

See Identity#getUser for description.

public

See Authorization#logout for description.

public

See Authorization#pollDeviceCode for description.

public
public

See Listening#resetFlow for description.

public
public

See StationFinder#searchStations for description.

public
public
public
public
public

See Identity#setUserStation for description.

public

unfollowShow(aggregationId: number | string): Promise<User>

See Identity#unfollowShow for description.

Static Public Members

public static get Action: Action source

Exposes the Action class for clients to record actions

Test:

public static get Logger: Logger source

Exposes the Logger class for clients to adjust logging if desired

Test:

public static get accessToken: string source

Test:

public static set accessToken: string source

public static get config: Config source

Test:

public static set config: Config source

Updates private _config member attributes but does not overwrite entire _config object

public static set onAccessTokenChanged: Function source

Sets a callback to be triggered whenever the SDK rotates the access token for a new one, usually when the old token expires and a refresh_token is used to generate a fresh token. Clients who wish to persist access tokens across sessions are urged to use this callback to be notified whenever a token change has occurred; the only other alternative is to call get accessToken() after every API call.

Throw:

TypeError

if the passed-in value isn't a function

Test:

Static Public Methods

public static getServiceUrl(service: string): string source

Returns the foundational path for a given service

Params:

NameTypeAttributeDescription
service string

Return:

string

Throw:

TypeError

if the passed-in service name is missing or invalid

Test:

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

See Authorization.refreshExistingAccessToken for description.

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

Instantiates the NPR One SDK.

Public Methods

public createTemporaryUser(): Promise<User> source

See Identity#createTemporaryUser for description.

Return:

Promise<User>

Throw:

TypeError

if an OAuth proxy is not configured or no client ID is set

Test:

public followShow(aggregationId: number | string): Promise<User> source

See Identity#followShow for description.

Params:

NameTypeAttributeDescription
aggregationId number | string

The aggregation (show) ID, which is either an integer or a numeric string (e.g. 123 or '123')

Return:

Promise<User>

Throw:

TypeError

if the passed-in aggregation (show) ID is not either a number or a numeric string

Test:

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

See Authorization#getDeviceCode for description.

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

Test:

public getHistory(): Promise<Array<Recommendation>> source

See Listening#getHistory for description.

Test:

public getRecommendation(uid: string, channel: string): Promise<Recommendation> source

See Listening#getRecommendation for description.

Params:

NameTypeAttributeDescription
uid string
  • optional
  • default: ''

Optional; a UID for a specific recommendation to play. In 99% of use cases, this is not needed.

channel string
  • optional
  • default: 'npr'

Optional; a channel to pull the recommendation from; the main flow channel of npr is used as the default. In 99% of use cases, this does not need to be changed.

Test:

public getRecommendationsFromChannel(channel: string): Promise<Array<Recommendation>> source

See Listening#getRecommendationsFromChannel for description.

Params:

NameTypeAttributeDescription
channel string
  • optional
  • default: 'recommended'

A non-flow (i.e. non-npr) channel to retrieve a list of recommendations from

Test:

public getStationDetails(stationId: number | string): Promise<Station> source

See StationFinder#getStationDetails for description.

Params:

NameTypeAttributeDescription
stationId number | string

The station's ID, which is either an integer or a numeric string (e.g. 123 or '123')

Return:

Promise<Station>

Test:

public getUpcomingFlowRecommendations(channel: string): Promise<Array<Recommendation>> source

this method is experimental.

See Listening#getUpcomingFlowRecommendations for description.

Params:

NameTypeAttributeDescription
channel string
  • optional
  • default: 'npr'

A channel to pull the next recommendation from

Test:

public getUser(): Promise<User> source

See Identity#getUser for description.

Return:

Promise<User>

Test:

public logout(): Promise source

See Authorization#logout for description.

Return:

Promise

Throw:

TypeError

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

Test:

public pollDeviceCode(): Promise<AccessToken> source

See Authorization#pollDeviceCode for description.

Return:

Promise<AccessToken>

Throw:

TypeError

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

Test:

public queueRecommendationFromChannel(channel: string, uid: string): Recommendation source

See Listening#queueRecommendationFromChannel for description.

Params:

NameTypeAttributeDescription
channel string

The channel used in the original call to getRecommendationsFromChannel()

uid string

The unique ID of the item to queue up for the user

Return:

Recommendation

Throw:

TypeError

If no valid channel or UID is passed in

Error

If no recommendations for this channel were previously cached, or if the UID was not found in that cached list

Test:

public resetFlow(): Promise source

See Listening#resetFlow for description.

Return:

Promise

Test:

public resumeFlowFromRecommendation(json: Object): Recommendation source

See Listening#resumeFlowFromRecommendation for description.

Params:

NameTypeAttributeDescription
json Object

JSON object representation of a recommendation

Return:

Recommendation

Test:

public searchStations(query: null | string): Promise<Array<Station>> source

See StationFinder#searchStations for description.

Params:

NameTypeAttributeDescription
query null | string
  • optional

An optional query, which can be a station name, network name, or zip code

Return:

Promise<Array<Station>>

Test:

public searchStationsByCity(city: string): Promise<Array<Station>> source

See StationFinder#searchStationsByCity for description.

Params:

NameTypeAttributeDescription
city string

A full city name (e.g. "New York", "San Francisco", "Phoenix")

Return:

Promise<Array<Station>>

Test:

public searchStationsByCityAndState(city: string, state: string): Promise<Array<Station>> source

See StationFinder#searchStationsByCityAndState for description.

Params:

NameTypeAttributeDescription
city string

A full city name (e.g. "New York", "San Francisco", "Phoenix")

state string

A state name (e.g. "Maryland") or abbreviation (e.g. "MD")

Return:

Promise<Array<Station>>

Test:

public searchStationsByLatLongCoordinates(lat: number, long: number): Promise<Array<Station>> source

See StationFinder#searchStationsByLatLongCoordinates for description.

Params:

NameTypeAttributeDescription
lat number

A float representing the latitude value of the geographic coordinates

long number

A float representing the longitude value of the geographic coordinates

Return:

Promise<Array<Station>>

Test:

public searchStationsByState(state: string): Promise<Array<Station>> source

See StationFinder#searchStationsByState for description.

Params:

NameTypeAttributeDescription
state string

A state name (e.g. "Maryland") or abbreviation (e.g. "MD")

Return:

Promise<Array<Station>>

Test:

public setUserStation(stationId: number | string): Promise<User> source

See Identity#setUserStation for description.

Params:

NameTypeAttributeDescription
stationId number | string

The station's ID, which is either an integer or a numeric string (e.g. 123 or '123')

Return:

Promise<User>

Test:

public unfollowShow(aggregationId: number | string): Promise<User> source

See Identity#unfollowShow for description.

Params:

NameTypeAttributeDescription
aggregationId number | string

The aggregation (show) ID, which is either an integer or a numeric string (e.g. 123 or '123')

Return:

Promise<User>

Throw:

TypeError

if the passed-in aggregation (show) ID is not either a number or a numeric string

Test: