npm package: @pricewaiter/integration-api-client
Description: Client for making requests to PriceWaiter integration endpoints.
Author: Matt Hinz
Latest version: 0.8.10

# PriceWaiter Integration API Client

![](https://codeship.com/projects/11764580-d9c5-0133-13a0-424a9136fddd/status?branch=master)

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



```javascript

// 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](../docs/index.md) 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.