heap-api

Heap Server-Side API Client for Node.js

This is a node.js client for the Heap server-side API.

Prerequisites

This package is tested on node.js 0.10 and above.

Installation

Install using npm.

npm install heap-api@1.x --save

Usage

Create an API client.

var heap = require('heap-api')('YOUR_APP_ID');

Recommended Usage Patterns

Track a server-side event in a fire-and-forget fashion.

heap.track('event-name', 'user-identity');
heap.track('event-name', 'user-identity', { property: 'value' });

Add properties to a user. Take advantage of the returned ES6 Promise to do more work when the call completes.

heap.addUserProperties('user-identity', { plan: 'premium1' })
.then(function() {
  // Do more work.
});

Set up an event listener to log Heap API call failures.

heap.on('error', function(error) {
  console.error(error);
});

Callback-Based Usage

Track a server-side event.

heap.track('event-name', 'user-identity', function(error) {
  if (error)
    console.error(error);
});

Track a server-side event with properties.

heap.track('event-name', 'user-identity', { property: 'value' }, function(error) {
  if (error)
    console.error(error);
});

Add properties to a user.

heap.addUserProperties('user-identity', { plan: 'premium1' }, function(error) {
  if (error)
    console.error(error);
});

Promise-Based Usage

The methods described above return ES6 Promises. The promises can be safely ignored. track is a good candidate for fire-and-forget usage.

heap.track('event-name', 'user-identity');

Alternatively, the promises can be used to learn when an API call completes or fails.

heap.addUserProperties('user-identity', { plan: 'premium1' })
.then(function() {
  console.log("API call succeeded");
});
.catch(function(error) {
  console.error(error);
});

The Promises are created using any-promise, which can be configured to use your application's favorite Promise implementation. The v8 Javascript engine versions used by node.js 0.12 and above include a native Promise implementation that is used by default.

require('any-promise/register')('when');

On node.js 0.10 and below, you must either explicitly configure a Promise library, or install a polyfill such as es6-promises, as shown below.

require('es6-promises').polyfill();

Stubbing

In some testing environments, connecting to outside servers is undesirable. Set the stubbed property to true to have all API calls succeed without generating any network traffic.

beforeEach(function() {
  heap.stubbed = true;
});
afterEach(function() {
  heap.stubbed = false
});

Alternatively, pass the stubbed option when creating the API client.

var heap = require('heap-api')('YOUR_APP_ID', { stubbed: true });

Development

After cloning the repository, install the dependencies.

npm install

Make sure the tests pass after making a change.

npm test

When adding new functionality, make sure it has good test coverage.

npm run cov

When adding new functionality, also make sure that the documentation looks reasonable.

npm run doc

If you submit a pull request, Travis CI will run the test suite against your code on the node versions that we support. Please fix any errors that it reports.

Copyright

Copyright (c) 2016 Heap Inc., released under the MIT license.