Mercury Javascript SDK

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:

{
    test: /\.jsx?$/,
    loaders: ['react-hot', 'babel?cacheDirectory'], // support HMR
    exclude: [/node_modules/, /mercury-sdk-js/],
},

Base Class functionality

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)

Parameters:

Properties:

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:

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
    });

hateoas.fetch(linksArray, targetRel, parameters) → {Promise}

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:

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
    });

hateoas.namedResource(configurationsParams, resourceName, resourceParams) → {Promise}

The hateoas.namedResource function will get the configuration for the app defined in the first argument and call one of it's links
Parameters:

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:

Example

classInstance.setAffiliate({ authClientId:"thr030", links:[], etc });

setAuth(authObj, affiliateLink)

Used by the classes or client applications
Parameters:

Example

classInstance.setAuth({ access_token: '154345234523452345453425.452345243523.2345234' });

API Group: Discovery REST APIs