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.

| Code | Description | |-------------------------|-------------------------------------------------------------------------------------| | invalid_api_key | The API client was configured with an invalid or missing store API key. | | invalid_endpoint_type | The type option was invalid. | | invalid_shared_secret | The sharedSecret option was invalid or missing. | | invalid_url | The url was invalid or missing. Urls must use the http: or https: scheme. | | invalid_version | The version option was invalid or missing. |

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.

| Code | Description | |--------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | connection_error | The HTTP request could not be completed, perhaps due to the endpoint being unreachable, DNS resolution failing, or requests timing out. | | http_error | The HTTP request returned a status code other than 200 (success) or 400 (error). This usually indicates a misconfigured endpoint. |

Request Content Errors

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

| Code | Description | |------------------------|-------------------------------------------| | invalid_request_body | The request body was invalid in some way. |

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.

| Code | Description | |---------------------------------|-------------------------------------------------------------------------------------------------| | invalid_response_body | The content in the response body was invalid in some way, such as containing invalid JSON. | | invalid_response_content_type | The response included a body but did not include a Content-type: application/json header. | | invalid_response_signature | The response was either missing its X-PriceWaiter-Signature header or the header was invalid. |

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.