Harbor ES6/Javascript Beacon Driver v2

Throttling Beacon driver in ES6 Javascript. This package is intended to be used for low-level communication
with Harbor as a part of your own Javascript Beacon projects.

This version will be written primarily for use in NodeJS apps, but the repo will include the ability to run Browserfy to
spit out a browser-usable version. The idea is to be generic and not dependant on Angular, React, etc. networking
libraries. We may write framework specific versions later.

Features

- Configurable, full-featured ES6 beacon driver
- Optional message retries
- Optional send rate-limiting

Usage in an Existing Node.js Project

To add the driver to your project: yarn add beacon-ratelimiting-driver. You can also use npm but we recommend yarn.

Initialize the driver with:

``$xslt
const Beacon = require('beacon-ratelimiting-driver');

...

Beacon.initialize({
apiKey: "[your-api-key]",
appVersionId: "io.somecompany.mycoolapp:1.0.0",
beaconVersionId: "[identifier for beacon version]",
beaconInstanceId: "[instance identifier such as a device UDID or server IP]"
});
`

All options are documented below.

Configuration Options

The Beacon.initialize method is passed all options as an object. The fields are shown in the table below.

| Field | Description | Default Value | Required? |
|:----------|:---------------------|:--------------:|:----------:|
| apiKey | Your Harbor API Key | n/a | X |
| appVersionId | The name and version of the app using this driver. Typically something like io.myco.myapp:2.1.3 | n/a | X |
| beaconVersionId | The name and version of the beacon driver. This driver can populate this automatically, or you can override it. | n/a | X |
| beaconInstanceId | An identifier for the host of this beacon. Typically this is a unique identifier for the individual device or system.|||
| verbose | Turn on/off logging messages. | false ||
| drainedCb | Callback when the buffer has been drained. Signature: ()=>{}. See throttle events below. |||
| txOptions | An object describing advanced Transmitter options |||
| txOptions.server | String indicating which server to use. Options are 'local', 'production', 'staging'. NOTE: This is unrelated your API key designations. Unless you are working at Harbor, you should not be using anything other than production. | production ||
| txOptions.rate | Integer indicating the maximum beacon send rate (beacons/sec). Currently capped at 40. | 40 ||
| txOptions.retries | Integer indicating number of times to retry sending a beacon before failing. NOTE: This is unrelated your API key designations. | 5 ||
| formatterOptions | An object describing data field modifications to be performed by the driver. |||
| formatterOptions.commonFields | Fields you want added to every data object transmitted. For example, if you want to add the fields { color: 'red', day: 'Sunday'} to every single message transmitted, pass that object here. |||
| formatterOptions.disableBestPractices | The driver will automatically attach fields that Harbor considers "best practices". (As of this version, there are no such fields.). | false ||

_Failure to provide the required apiKey, appVersionId, or beaconVersionId parameters to the Beacon.initialize method will result in a strongly worded Error and absolutely no soup for you._

Sending Data

Once the beacon driver is initialized, you can send a beacon with:

`
await Beacon.transmit({ beaconMessageType: 'TEST_MSG', data: {...});
Beacon.transmit({ beaconMessageType: 'TEST_MSG', dataTimestamp: 1546300800000, data: {...});
`

Where the async Beacon.transmit(options) method is passed all options as an object.

- beaconMessageType is application dependent
- data is also application dependent.
- If you do not specify dataTimestamp, the current system time Date().getTime() will be used.

_*Some foghorn and tug implementations may require specific message types and data schema, so check your documentation._

| Field | Description | Default Value | Required? |
|:----------|:---------------------|:--------------:|:----------:|
| beaconMessageType: | Field is application dependent, as is the data you send. Some foghorn and tug implementations may require specific message types and data schema, so check your documentation. | | |
| dataTimestamp: | If you include dataTimestamp then this value will be used instead of the current time. | Current time in milliseconds | |
| data: | Any JS Object that is JSON-encodable. Default value is an empty Object {} | {} | |

Other

- Beacon.isInitialized - return a Boolean indicating if the driver has been Beacon.initialized({...}
- Beacon.pendingTxCount - returns an Integer indicating the number of beacon messages in flight
- Beacon.txOn = false|true; # Transmission off/on - You can temporarily pause/restart transmission.

Events

Using the throttle you can attach event listeners.

Beacon.throttle - returns a Superagent Throttle

`
Beacon.throttle
.on('sent', (request) => { ... }) // sent a request
.on('received', (request) => { ... }) // received a response
.on('drained', () => { ... }) // received last response
`

Installation to Create Your Own Variant

- Install Node.js if it is not already installed.
- Node version must support ES6 features, especially closures/fat-arrow functions.
- This was developed using Node version 8.9.3, and tested to 10.x+. Stock Ubuntu installs the ancient 4.x version which DOES NOT work. Follow the directions for your platform to get a recent version.
- After cloning the repo, go into the root folder (with package.json in it) and yarn install

Running Beaconflood Test App

node beaconflood.js -r -k 1234-5678-8765-4321 -c 10 -l 5

-r = run remote
-k = api key
-c = how many beacons to send
-l` = inter-beacon loop delay in ms