@kayako/apps-proxy

Apps Proxy

This package is used by Kayako apps server and the local development server to make proxy requests from the installed apps.

The job of the package is to take a packet and make a HTTP request by reading information from the packet. It doesn't store any information of it's own.

Installation

npm i https://github.com/kayako/apps-proxy.git

Usage

const { proxy } = require('apps-proxy')
await proxy.makeRequest(payload, options)

Payload

Here is the list of accepted values in payload

key	value	description
url	String	Url where to make the HTTP request.
method	String	HTTP request method
headers	Object	An object of headers to pass to the actual server
body	Object	Http request body, must be valid Javascript Object.
params	Object	Params to pass as URL query string.

Options

Here is the list of required options.

key	value	description
whiteListedDomains	Array	An array of whitelisted domains. Only urls from this array will be allowed, else if an exception will be raised.
tokens	Object	An object of values to replace the dynamic placeholders.

Allowed content-types

Only following content types are allowed in the content-type header. This service will transform the body itself based upon the content-type.

• application/x-www-form-urlencoded
• application/json

Response structure

The response structure is defined below.

{
  data: {
    status: 200,
    statusText: 'OK',
    headers: {},
    body: {}
  }
}

Terms

Below is the used terms and what they mean. These terms are not unique to the proxy service, but instead used in the apps space.

Placeholders

These are values, which are not known to the app developer, but developer does know the keys for these values.

For example: App needs the apiKey to make some HTTP request, so developer use a placeholder for that key and at runtime, that value is replaced by the server.

proxy.makeRequest({
  url: '{{ params.domain }}.salesforce.com'
}, {
  tokens: {
    params: {
      domain: 'kayako'
    }
  }
})

When making the request, params.domain will be replace with the defined value.

NOTE: An exception will be raised if placeholders are defined, but their values are missing.

Translations

Each exception raised from this package, will have a key called translation. You can use this key to define a human readable message for that exception.

try {
  await proxy.makeRequest(payload, options)
} catch (error) {
  const message = antl.formatMessage(error.translation.key, error.translation.values)
  response.send(message)
}