@pricewaiter/integration-api-client v0.8.10

PriceWaiter Integration API Client

This package provides a function for making HTTP requests to endpoints that comply with the PriceWaiter Integration API Spec. It provides the following benefits:

1. Signs requests using a shared secret
2. Verifies response signatures using the same shared secret
3. Parses { error: { code: 'whatever' } }-style errors out of responses and throws them

Usage

// 1. Require the library.
const createApiClient = require('@pricewaiter/integration-api-client');

// 2. Generate a configured client function.
const makeApiRequest = createApiClient({
    type: 'ping',
    version: '2016-03-01',
    url: 'https://example.org/ping',
    apiKey: 'APIKEY',
    sharedSecret: 'SEEEEEECRETS',
});

// 3. Make requests, providing the request body and an (optional) request UUID.
makeApiRequest({ foo: 'bar' }, 'bac658f0-0a58-4eb8-b710-de62126e4032')
    .then(({request, response}) => {
        // request.headers is the request headers
        // request.id is the UUID assigned to the request (2nd arg above)
        // request.url is the URL the request was made to.
        // request.body is the parsed JSON request body (if available)
        // request.rawBody is the stringified JSON request body
        //
        // response.statusCode is the HTTP status copde
        // response.headers is the response headers
        // response.body is the parsed JSON response body (if available)
        // response.rawBody is the unparsed response body
    })
    .catch(err => {
        // err.code is i.e. 'invalid_response_body'
        // err.statusCode is the response's HTTP status code (if available)
        // err.request is the same as r.request above (if available)
        // err.response is the same as r.response above (if available)
    })

Errors

API calls made using this library can return a lot of potential errors. All errors include an unvarying code property that can be used to quickly identify them.

Client Configuration Errors

Calling createApiClient() with invalid options will throw errors right away (rather than returning a rejected Promise). You should not retry client creation without modifying the relevant option.

Once you have a configured API client function, calling it can return a rejected Promise with a number of other errors.

Network Errors

These errors indicate (potentially transient) network problems. You should be able to retry your requests without modifying them.

Request Content Errors

If there is a problem with your request's content, you should not resubmit your request without modifying it.

Response Content Errors

These errors indicate that a response was received from the endpoint, but its format was invalid in some way. Whether you retry these errors will depend on the endpoint.

Endpoint-Specific Errors

Each endpoint can return its own error codes under certain conditions (e.g. deal_not_found). See Endpoint Documentation for additional error codes.

Publishing New Versions

./publish.sh [--patch|--minor] [--dry-run] will cut a new version, push to git and publish to NPM.