box-sdk

Node Box SDK

Node.js client for the Box.com Content API.

This is an alpha release. Although the included integration tests do offer a good deal of assurance about its usability, it has not been adequately battle-tested yet.

Supported Features

• All File Ops
• All Folder Ops
• Events - Long Polling

The SDK aims to abstract away the intricacies of authentication, refreshing tokens, etc. as far as possible. Hence, you will not find explicit methods to perform low-level operations.

All legitimate public methods map to the high level functionality described in the Content API docs.

Getting Started

Install the module with: npm install box-sdk

Running Standalone

var box_sdk = require('box-sdk');

//Default host: localhost
var box = box_sdk.Box({
  client_id: 'client id',
  client_secret: 'client secret',
  port: 9999,
  host: 'somehost', //default localhost
  log-level: 'debug' //default info
});
var connection = box.getConnection('[e-mail]');

//Navigate user to the auth URL
console.log(connection.getAuthURL());

connection.ready(function () {
  connection.getFolderItems(0, {limit: 1}, function (err, result) {
    if (err) {
      console.error(JSON.stringify(err.context_info));
    }
    console.dir(result);
  });
});

Running with Passport authentication under Express

Note: For a complete express example, look under test/helpers/express.

var express = require('express'),
  passport = require('passport'),
  BoxStrategy = require('passport-box').Strategy,
  box_sdk = require('../../..');

...

var box = box_sdk.Box();

...

passport.use(new BoxStrategy({
  clientID: BOX_CLIENT_ID,
  clientSecret: BOX_CLIENT_SECRET,
  callbackURL: "http://127.0.0.1:" + PORT + "/auth/box/callback"
}, box.authenticate()));

...

var app = express();

...

app.get('/auth/box', passport.authenticate('box'), function (req, res) {});

app.get('/auth/box/callback',
  passport.authenticate('box', {
    failureRedirect: '/login'
  }),
  function (req, res) {
    res.redirect('/');
  });

Long Polling

var connection = box.getConnection('[e-mail]');

//Navigate user to the auth URL
console.log(connection.getAuthURL());

connection.ready(function () {
  connection.startLongPolling();

  //Monologue subscription filter to catch all polling events
  connection.on('polling.event.#', function (data) {
    console.log('Received event: %s', data.event_type);

    //Handle event
    ...
  });
  connection.on('polling.end', function() {
    //Continue with post-polling ops
    ...
  });
  connection.on('polling.error', function (err) {
    console.error(err);
  });

  //Conquer the universe, etc
  ...

  connection.stopLongPolling();
};

Testing

Before running your tests locally, copy test/env.json.example to test/env.json and fill in correct values for the environment variables to be imported during testing.

The casperjs and phantomjs executables must be available in the enviroment path. Usually it is enough to run:

$ (sudo) npm install -g phantomjs
$ (sudo) npm install -g casperjs

Run all tests with:

$ grunt mochaTest

The files under test/integration are completely self-contained, and hence can be run independently. For example:

$ grunt mochaTest --target=./test/integration/api/content/folders-test.js

Documentation

API documentation is generated by running:

$ grunt jsdoc

The generated documentation is available in the dist/docs folder. An up-to-date online version is hosted at http://adityamukho.github.io/node-box-sdk/ .

Examples

Complete tutorials will soon be added to the documentation. In the meantime, have a look at the included test cases to get an idea of how the SDK is used.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

• April 25, 2014 - v0.0.0-a1: Supports all file and folder operations, as well as event long-polling.

License

Copyright (c) 2014-2015 Aditya Mukhopadhyay Licensed under the MIT license.