1.0.1 • Public • Published

    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.


    npm i heap-api

    DownloadsWeekly Downloads






    Last publish


    • avatar
    • avatar
    • avatar