This is an SDK that wraps calls to the Discovery APIs. The SDK exposes an object with classes that represent API groups. Each class will have a number of name-spaced methods that return promises with data from APIs in that group. Each class will also expose some common methods for hateoas support, using the auth tools against additional endpoints, and affiliate login/logut functionality. See the documentation below for a complete list of methods.
SDK Development
Requirements:
node and npm
Getting started:
clone the repo
run $ npm install
see package.json for a list of npm scripts
Adding SDK to your project
Requirements:
node and npm
Getting started:
install with npm - npm install @discodigital/mercury-sdk-js --save
Developing Locally:
If you'd like to use this package locally to make changes and use in your project, you can create a link through npm from the root of your project:
npm link ../path/to/mercury-sdk-js @discodigital/mercury-sdk-js@0.<version>.0
Note: If you are linking the mercury-sdk-js package into a react project and that react project is using react-hot loader, then you will need to explicitly tell it to ignore the mercury-sdk-js package when it does its transformation. You can do this in the webpack.config.js where you have defined the loader for react-hot. You'll need to add mercury-sdk-js to the exclude:
All of the API group classes are built on top of a base class that provides the shared functionality. The primary differences between API group classes are defined by their config sections, thus most of the functionality resides in the base class.
Constructor
new SDKBase(options, child)
Create a base class instance.
Parameters:
Name
Type
Description
`options`
object
(required) the options passed from the child class constructor.
Name
Type
Description
`apiBase`
string
(required) the base url of the api group you want to consume.
`clientId`
string
(required) the clientId issued to your app by the services team.
`authentication`
'anonymous' | 'affiliate'
(optional) the authentication type you'll use for the class instance.
`anonymousProxy`
string
(optional) a local proxy for anonymous authentication, this lets the SDK avoid using iframes.
`affiliateProxy`
string
(optional) a local proxy for affiliate authentication, this lets the SDK avoid using iframes.
`loginStyle`
'window' | 'popup' | 'tab'
(optional) whether affiliate auth should happen in a the same window, a popup or a new tab default is window
`code`
string
(optional) the code that is passed back from oauth re-direct
`version`
string
(optional) the api version you want to use, defaults to v1
`networksCode`
string
(optional) the id of the network or network group, used to trim the affiliate list down
`child`
string
(required) the child class name, used to reference the right config data.
Properties:
Name
Type
Description
`config`
object
the configuration options passed in
`auth`
object
an object that will hold the sdk instances auth token and metadata
`isAuthenticated`
boolean
a flag that represents the current auth state
`hateoas`
object
an object that holds several methods for following hateoas links
Methods
destroy()
Used by client apps to remove any listeners or maps that may prevent the instance from being garbage collected Example
classInstance.destroy();
fetchWithAuth(url, options)→ {Promise}
This exposes the internal fetchWithAuth method for client apps using the SDKBase it allows for add hoc calls to apis with auth support and could be useful for APIs that aren't included in the SDK yet Parameters:
Name
Type
Description
`url`
string
(required) the url of the fetch request (same as in normal window.fetch)
`options`
object
(optional) the fetch options (same as in normal window.fetch)
Returns: a Promise resolving with the json data from the api called, parsed to add HATEOS link functions Example
classInstance.fetchWithAuth('https://my-dev-apis/v1/someendpoint', { method: 'GET' })
.then(resp => {
//your data is in resp.headers and resp.body
});
getAffiliates()→ {Promise}
Used by client apps to get a list of affiliates to choose from in affilate auth Returns: a Promise resolving with an array of affiliate objects Example
classInstance.getAffiliates()
.then(resp => {
// affiliates list is in resp.body
});
The hateoas.fetch function allows the client app to pass in a group of hateoas links and make a call to one of them by it's rel name Parameters:
Name
Type
Description
`linksArray`
array
the hateoas links to use
`targetRel`
string
the rel of the link the app wants to call
`parameters`
object
the parameters to fill out the url template with and to add additional params to the querystring (or body if "POST") of the fetch call
Returns: a call to the fetchWithAuth function provided Example
const linksArray = [
{
rel: 'next',
href: 'https://myapi.com/v1/something?offset=10&platform={platform}',
},
];
classInstance.hateoas.fetchLink(linksArray, 'next', { platform: 'desktop' })
.then(resp => {
//your hateoas link data is in resp.body, there maybe be hateoas links in resp.headers
});
The hateoas.namedResource function will get the configuration for the app defined in the first argument and call one of it's links Parameters:
Name
Type
Description
`configurationsParams`
object
the params used to call the configurations api
`resourceName`
string
the name of the link in the configuration you want to call
`resourceParams`
object
the object used in calling hateoas.fetch()
Returns: a call to hateoas.fetch() Example
classInstance.hateoas.namedResource({ id: 'dgo', key: 'test' }, 'featured', { platform: 'desktop' })
.then(resp => {
// your named resource data is in resp.body, there maybe be hateoas links in resp.headers
});
logOff()
Used by client apps to log out of affiliate auth Example
classInstance.logOff()
.then(() => {
// logoff is now complete
});
setAffiliate(affiliateObject)
Used by client apps to initialize affiliate auth once an affiliate is chosen by the user Parameters:
Name
Type
Description
`affiliateObject`
object
(required) the complete affiliate object that came from getAffiliates()
(optional) Resource fields returned in API resource response
`xfields`
string
(optional) Resource fields excluded from API resource response
`xid`
string
(optional) Resource models excluded from API resource response based on content id
`xslug`
string
(optional) Resource models excluded from API resource response based on content slug
`embed`
string
(optional) Ability to expand referenced/embedded collection item types(e.g. API Collections: networks, show, genres, subgenres, season)
Example
classInstance.Bios.find()
.then(resp => {
// your data is in resp.headers and resp.body
})
.catch(err => {
// error handling
});
Bios.find(parameters)→ {Promise}
Find one Bio
Parameters:
Name
Type
Description
`parameters`
object
Name
Type
Description
`id`
string
(required) Bio ID
`fields`
string
(optional) Resource fields returned in API resource response
`xfields`
string
(optional) Resource fields excluded from API resource response
`embed`
string
(optional) Ability to expand referenced/embedded collection item types(e.g. API Collections: networks, show, genres, subgenres, season)
Example
classInstance.Bios.find({id: 'string'})
.then(resp => {
// your data is in resp.headers and resp.body
})
.catch(err => {
// error handling
});
Collections.find(parameters)→ {Promise}
Find all Collections
Parameters:
Name
Type
Description
`parameters`
object
Name
Type
Description
`platform`
string
(required) Platform Name (e.g. desktop)
`type`
string
(required) Collection Type (all|network)
`slug`
string
(optional) Filter
`network.id`
string
(optional) Filter
`network.code`
string
(optional) Filter
`embed`
string
(optional) Ability to expand collection item types. Embedded Object Attributes of Video and Show API Collections(e.g. networks, show, genres, subgenres, season)
`limit`
integer
(optional) Max Resource Count. *Page size
`offset`
integer
(optional) Resource index. *Zero-based
`fields`
string
(optional) Resource fields returned in API resource response
`xfields`
string
(optional) Resource fields excluded from API resource response
`xid`
string
(optional) Resource models excluded from API resource response based on content id
`xslug`
string
(optional) Resource models excluded from API resource response based on content slug
Example
classInstance.Collections.find({platform: 'string', type: 'string'})
.then(resp => {
// your data is in resp.headers and resp.body
})
.catch(err => {
// error handling
});
Collections.find(parameters)→ {Promise}
Find one Collection
Parameters:
Name
Type
Description
`parameters`
object
Name
Type
Description
`id`
string
(required) Collection ID
`platform`
string
(optional) Platform Name (e.g. desktop) to filter resource Alternate Images, if applicable
`fields`
string
(optional) Resource fields returned in API resource response
`xfields`
string
(optional) Resource fields excluded from API resource response
`embed`
string
(optional) Ability to expand referenced/embedded collection item types(e.g. API Collections: networks, show, genres, subgenres, season)
Example
classInstance.Collections.find({id: 'string'})
.then(resp => {
// your data is in resp.headers and resp.body
})
.catch(err => {
// error handling
});
Configurations.find(parameters)→ {Promise}
Find all Configurations
Parameters:
Name
Type
Description
`parameters`
object
Name
Type
Description
`id`
string
(required) your apps ID
`key`
string
(required)
Example
classInstance.Configurations.find({ id: 'dgo', key: 'test' })
.then(resp => {
// use your data
})
.catch(err => {
// error handling
});
Curatedlists.find(parameters)→ {Promise}
Find all Curatedlists
Parameters:
Name
Type
Description
`parameters`
object
Name
Type
Description
`name`
string
(optional) Filter (regex)
`slug`
string
(optional) Filter
`sort`
string
(optional) Fields Supported: [name, slug]
`platform`
string
(optional) Platform Name (e.g. desktop) to filter resource Alternate Images, if applicable
`limit`
integer
(optional) Max Resource Count. *Page size
`offset`
integer
(optional) Resource index. *Zero-based
`fields`
string
(optional) Resource fields returned in API resource response
`xfields`
string
(optional) Resource fields excluded from API resource response
`xid`
string
(optional) Resource models excluded from API resource response based on content id
`xslug`
string
(optional) Resource models excluded from API resource response based on content slug
`embed`
string
(optional) Ability to expand referenced/embedded collection item types(e.g. API Collections: networks, show, genres, subgenres, season)
Example
classInstance.Curatedlists.find()
.then(resp => {
// your data is in resp.headers and resp.body
})
.catch(err => {
// error handling
});
Curatedlists.find(parameters)→ {Promise}
Find one Curatedlist
Parameters:
Name
Type
Description
`parameters`
object
Name
Type
Description
`id`
string
(required) Curatedlist ID
`platform`
string
(optional) Platform Name (e.g. desktop) to filter resource Alternate Images, if applicable
`fields`
string
(optional) Resource fields returned in API resource response
`xfields`
string
(optional) Resource fields excluded from API resource response
`embed`
string
(optional) Ability to expand referenced/embedded collection item types(e.g. API Collections: networks, show, genres, subgenres, season)
Example
classInstance.Curatedlists.find({id: 'string'})
.then(resp => {
// your data is in resp.headers and resp.body
})
.catch(err => {
// error handling
});
Featured.find(parameters)→ {Promise}
Find all Featured
Parameters:
Name
Type
Description
`parameters`
object
Name
Type
Description
`platform`
string
(required) Platform Name (e.g. desktop)
`type`
string
(required) Collection Type (all|network)
`network.id`
string
(optional) Filter
`network.code`
string
(optional) Filter
`embed`
string
(optional) Ability to expand collection item types. Embedded Object Attributes of Video and Show API Collections(e.g. networks, show, genres, subgenres, season)
`limit`
integer
(optional) Max Resource Count. *Page size
`offset`
integer
(optional) Resource index. *Zero-based
`fields`
string
(optional) Resource fields returned in API resource response
`xfields`
string
(optional) Resource fields excluded from API resource response
Example
classInstance.Featured.find({platform: 'string', type: 'string'})
.then(resp => {
// your data is in resp.headers and resp.body
})
.catch(err => {
// error handling
});
FeaturedPage.find(parameters)→ {Promise}
Find all FeaturedPage
Parameters:
Name
Type
Description
`parameters`
object
Name
Type
Description
`platform`
string
(required) Platform Name (e.g. desktop)
`type`
string
(required) Collection Type (all|network)
`network.id`
string
(optional) Filter
`network.code`
string
(optional) Filter
`embed`
string
(optional) Ability to expand collection item types. Embedded Object Attributes of Video and Show API Collections(e.g. networks, show, genres, subgenres, season)
`limit`
integer
(optional) Max Resource Count. *Page size
`offset`
integer
(optional) Resource index. *Zero-based
`fields`
string
(optional) Resource fields returned in API resource response
`xfields`
string
(optional) Resource fields excluded from API resource response
Example
classInstance.FeaturedPage.find({platform: 'string', type: 'string'})
.then(resp => {
// your data is in resp.headers and resp.body
})
.catch(err => {
// error handling
});
Genres.find(parameters)→ {Promise}
Find all Genres
Parameters:
Name
Type
Description
`parameters`
object
Name
Type
Description
`name`
string
(optional) Filter (regex)
`slug`
string
(optional) Filter
`networks.id`
string
(optional) Filter
`networks.code`
string
(optional) Filter
`sort`
string
(optional) Fields Supported: [name, slug]
`platform`
string
(optional) Platform Name (e.g. desktop) to filter resource Alternate Images, if applicable
`limit`
integer
(optional) Max Resource Count. *Page size
`offset`
integer
(optional) Resource index. *Zero-based
`fields`
string
(optional) Resource fields returned in API resource response
`xfields`
string
(optional) Resource fields excluded from API resource response
`xid`
string
(optional) Resource models excluded from API resource response based on content id
`xslug`
string
(optional) Resource models excluded from API resource response based on content slug
`embed`
string
(optional) Ability to expand referenced/embedded collection item types(e.g. API Collections: networks, show, genres, subgenres, season)
Example
classInstance.Genres.find()
.then(resp => {
// your data is in resp.headers and resp.body
})
.catch(err => {
// error handling
});
Genres.find(parameters)→ {Promise}
Find one Genre
Parameters:
Name
Type
Description
`parameters`
object
Name
Type
Description
`id`
string
(required) Genre ID
`platform`
string
(optional) Platform Name (e.g. desktop) to filter resource Alternate Images, if applicable
`fields`
string
(optional) Resource fields returned in API resource response
`xfields`
string
(optional) Resource fields excluded from API resource response
`embed`
string
(optional) Ability to expand referenced/embedded collection item types(e.g. API Collections: networks, show, genres, subgenres, season)
Example
classInstance.Genres.find({id: 'string'})
.then(resp => {
// your data is in resp.headers and resp.body
})
.catch(err => {
// error handling
});
(optional) Resource fields returned in API resource response
`xfields`
string
(optional) Resource fields excluded from API resource response
`embed`
string
(optional) Ability to expand referenced/embedded collection item types(e.g. API Collections: networks, show, genres, subgenres, season)
Example
classInstance.Layouts.find({platform: 'string'})
.then(resp => {
// your data is in resp.headers and resp.body
})
.catch(err => {
// error handling
});
Layouts.find(parameters)→ {Promise}
Find one Layout
Parameters:
Name
Type
Description
`parameters`
object
Name
Type
Description
`id`
string
(required) Layout ID
`platform`
string
(required) Platform Name (e.g. desktop)
`fields`
string
(optional) Resource fields returned in API resource response
`xfields`
string
(optional) Resource fields excluded from API resource response
`embed`
string
(optional) Ability to expand referenced/embedded collection item types(e.g. API Collections: networks, show, genres, subgenres, season)
Example
classInstance.Layouts.find({id: 'string', platform: 'string'})
.then(resp => {
// your data is in resp.headers and resp.body
})
.catch(err => {
// error handling
});
Livestreams.find(parameters)→ {Promise}
Find one Livestream
Parameters:
Name
Type
Description
`parameters`
object
Name
Type
Description
`id`
string
(required) Livestream ID
`fields`
string
(optional) Resource fields returned in API resource response
`xfields`
string
(optional) Resource fields excluded from API resource response
`embed`
string
(optional) Ability to expand referenced/embedded collection item types(e.g. API Collections: networks, show, genres, subgenres, season)
Example
classInstance.Livestreams.find({id: 'string'})
.then(resp => {
// your data is in resp.headers and resp.body
})
.catch(err => {
// error handling
});