Heap Server-Side API Client

Downloads in past


2331.0.18 years ago8 years agoMinified + gzip package size for heap-api in KB


Heap Server-Side API Client for Node.js
Build Status Coverage Status Dependency Status NPM Version
This is a node.js client for the Heap server-side API.


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


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


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) {

Callback-Based Usage

Track a server-side event.
heap.track('event-name', 'user-identity', function(error) {
  if (error)

Track a server-side event with properties.
heap.track('event-name', 'user-identity', { property: 'value' }, function(error) {
  if (error)

Add properties to a user.
heap.addUserProperties('user-identity', { plan: 'premium1' }, function(error) {
  if (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) {

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.

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.


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 });


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 (c) 2016 Heap Inc., released under the MIT license.