cimpress-client-request

cimpress-client-request

A module for handling generation of OAuth Bearer tokens issued by Auth0 by integrating credential management into request.js.

Installation

npm i cimpress-client-request --save

or

yarn add cimpress-client-request

Usage

This module exposes a single method:

module.exports.request = function(config, cb) {}

This works as a drop-in replacement for request. Adopting this flow is as simple as these two surgical incisions:

//var request = require('request');
var request = require('cimpress-client-request');

// Note the set of 6 possible new options that can be passed in the request.js options.auth object.
// Every other property in the request options object works as normal, and you can call all of the
// convenience methods exposed by request.js.
var options = {
    auth: {
        client_id: 'see below',
        client_secret: 'see below',
        refresh_token: 'see below',
        target_id: 'see below'
    },
    keyGen: function(method, url, accessToken){ return url + method + accessToken },
    retry_count: 2,
};
request(options);

Here's how you should use those 4 auth parameters + 2 new parameters:

Property	Description
client_id	The client id you wish to use to request client credential grants (https://auth0.com/docs/api-auth/grant/client-credentials).
client_secret	The client secret you wish to use to request client credential grants (https://auth0.com/docs/api-auth/grant/client-credentials).
refresh_token	A refresh token for use in delegation flows, retrieved from developer.cimpress.io. Defaults to the environment variable CIMPRESS_IO_REFRESH_TOKEN.
target_id	OPTIONAL The client id for which you are trying to retrieve a delegated token. Note, if you don't know this, you can rely on a 401 with a Www-Authenticate to provide the client id. If you don't provide this config, and the service doesn't provide that header, your call will fail with a 401.
authorization_server	OPTIONAL The server to call to request client credential grants (https://auth0.com/docs/api-auth/grant/client-credentials). This defaults to https://cimpress-dev.auth0.com/oauth/token.
audience	OPTIONAL The audience to send when requesting client credential grants (https://auth0.com/docs/api-auth/grant/client-credentials). This defaults to https://api.cimpress.io/
keyGen	OPTIONAL A function that returns a string to be used when caching responses. Takes in the url, method, and access token used. If not specified a default function is used
retry_count	OPTIONAL The number of times to retry when receiving a non-2XX response

You can specify your caching method by calling:

var request = require('cimpress-client-request');
var altCache = require('alternative-caching-library-here');

request.set_credentials_cache = altCache;

Note that the alternative caching method you use must support callbacks and have the following function definitions:

• get(key, callback)
• set(key, value, ttl)
• flushAll()

Tests

You might also want to look at our tests to see some examples of usage.

You can run tests via grunt or grunt test.

Development

Install Nodejs & Grunt

sudo apt-get install nodejs

If you are running Ubuntu you need to create a symlink for node. (There is a naming conflict with the node package).

sudo ln -s /usr/bin/nodejs /usr/bin/node

Install Grunt command line tool:

sudo npm -g grunt-cli

If you see an error about NPM not installed, run the following command to install:

sudo apt-get install npm

Getting Started from Source

cd src/
sudo npm install
grunt

Package & Install without pushing to a remote NPM registry

To package:

npm pack

This will generate a tarball gzipped following a file name convention of: <module>-<version>.tgz

To install:

npm install <path-to-tgz>

git - pre-commit hook

If you would like to run jslint and units tests before your commit then create a file in .git/hooks/pre-commit with execute permissions with the following content:

#!/bin/sh

grunt --gruntfile $(git rev-parse --show-toplevel)/src/Gruntfile.js