asana

A node.js client for the Asana API

Asana

A JavaScript client (for both Node and browser) for the Asana API v1.0.

Install with npm:

npm install asana --save

Download the latest distribution in releases and serve it from your webserver. Require it in your client from a SCRIPT tag.

  • Thin Wrapper This client is a thin wrapper which means that the client makes little attempt to verify the validity of the arguments locally. All errors are reported by the server. We include custom Error types which will contain the response from the server.
  • Promises Promises with bluebird seem like the most neutral way to support node's various async paradigms. If you want promises, you get them by default. If you want callbacks, bluebird promises support nodeify which takes a callback as parameter. For generators and streams, co and highland also support promises respectively. Beyond that, other major libraries such as mongoose, mocha, and elastic search (which uses bluebird) also support promises.

To do anything, you'll need always an instance of an Asana.Client configured with your preferred authentication method (see the Authentication section below for more complex scenarios) and other options.

The most minimal example would be as follows:

var asana = require('asana');
var client = asana.Client.create().useBasicAuth('my_api_key');
client.workspaces.me().then(function(me) {
  console.log(me);
});

All resources are exposed as properties of the Asana.Client instance (e.g. client.workspaces). See the developer documentation for docs on each of them.

This module supports authenticating against the Asana API with either an API key or through OAuth2.

var client = Asana.Client.create().useBasicAuth('my_api_key');

Authenticating through OAuth2 is preferred. There are many ways you can do this.

In all cases, you should create a Client that contains your app information. The values in the below snippet should be substituted with the real properties from your application's settings.

var client =Asana.Client.create({
  clientId: 123,
  clientSecret: 'my_client_secret',
  redirectUri: 'my_redirect_uri'
});

If you have a plain bearer token obtained somewhere else and you don't mind not having your token auto-refresh, you can authenticate with it as follows:

client.useOauth({
  credentials: 'my_access_token'
});

If you obtained a refresh token (from a previos authorization), you can use it together with your client credentials to authenticate:

var credentials = {
  refresh_token: 'my_refresh_token'
};
client.useOauth({
  credentials: credentials
});

See examples/oauth/webserver for a working example of this.

Whenever you ask for a collection of resources, you can provide a number of results per page to fetch, between 1 and 100. If you don't provide any, it defaults to 50.

client.tasks.findByTag(tagId, { limit: 5 }).then(function(collection) {
  console.log(collection.data);
  // [ .. array of up to 5 task objects .. ] 
});

There are a few useful functions that can help you deal with paginated requests.

To get the next page of a collection, you do not have to manually construct the next request. The Client.nextPage method takes care of this for you:

client.tasks.findByTag(tagId).then(function(collection) {
  console.log(collection.data);
  client.nextPage(collection).then(...);
});

You can take the Promise returned by any collection response and "stream" it. This will transparently (and lazily) fetch the items in the underlying collection in pages as you iterate through them.

var stream = client.stream(tasks.findByTag(tagId));
stream.on('data', function(task) {
  console.log(task);
});

In any request against the Asana API, there a number of errors that could arise. Those are well documented in the Asana API Documentation, and are represented as exceptions under the namespace Asana.errors.

Various examples are in the repository under examples/, but some basic concepts are illustrated here.

var Asana = require('asana');
var util = require('util');
 
// Using the API key for basic authentication. This is reasonable to get 
// started with, but Oauth is more secure and provides more features. 
var client = Asana.Client.create().useBasicAuth(process.env.ASANA_API_KEY);
 
client.users.me()
  .then(function(user) {
    var userId = user.id;
    // The user's "default" workspace is the first one in the list, though 
    // any user can have multiple workspaces so you can't always assume this 
    // is the one you want to work with. 
    var workspaceId = user.workspaces[0].id;
    return client.tasks.findAll({
      assignee: userId,
      workspace: workspaceId,
      completed_since: 'now',
      opt_fields: 'id,name,assignee_status,completed'
    });
  })
  .then(function(response) {
    // There may be more pages of data, we could stream or return a promise 
    // to request those here - for now, let's just return the first page 
    // of items. 
    return response.data;
  })
  .filter(function(task) {
    return task.assignee_status === 'today' ||
      task.assignee_status === 'new';
  })
  .then(function(list) {
    console.log(util.inspect(list, {
      colors: true,
      depth: null
    }));
  });

The code is thoroughly documented with JsDoc tags. The [Official Asana Documentation][asana-doc] is a great resource since this is just a thin wrapper for the API.

Feel free to fork and submit pull requests for the code! Please follow the existing code as an example of style and make sure that all your code passes lint and tests. For a sanity check:

git clone git@github.com:Asana/node-asana.git
cd node-asana
npm install
npm test

The specific Asana resource classes (Tag, Workspace, Task, etc) are generated code, hence they shouldn't be modified by hand. See the asana-api-meta repo for details.