node-box-view-api

Node.js client library for Box View API

This software is released under the MIT license. See LICENSE for more details.

Release Status

• Latest:

Release Notes, Issues & Roadmap: RELEASE_NOTES.md

Download and Installation

From the command-line:

$ npm install box-view-api

package.json:

...
dependencies: {
  ...
  "box-view-api": "*$version*",
  ...
}
...

For contributors

See Contributing section below

Example use

The examples below are not intended to replace a working knowledge of the Box View API, nor do they cover all possible uses and responses of the node-box-view-api client library.

They cover the main uses, assuming no errors.

More detailed descriptions of the client library behaviours, including errors, can be found in docs/tests/index.html. These files were generated from the mocha test suite with the spec reporter.

NOTE: The Box View API is currently in beta, and therefore subject to change by Box.net. The tests and the descriptions below are correct as of end Sept 2013.

DocumentAPI

var documentApi = new require('box-view-api').setToken('API_TOKEN').documentAPI;

Retrieving a list of documents previously uploaded to Box View

/**
 * @param searchOptions (optional) an object containing the search options to pass to the Box View API
 */
documentApi.list(searchOptions, function(error, response, body) {
	console.log('error should be falsey: ', error);
	console.log('response.statusCode should be 200: ', response.statusCode);
	console.log('body.id should be a non-empty string: ', body.id);
});

See the Box View API for details of supported search parameters.

Uploading a URL to Box View

/**
 * @param url URL of file to upload to Box View
 * @param name the name of the file
 */
documentApi.uploadUrl(url, name, function(error, response, body) {
	console.log('error should be falsey: ', error);
	console.log('response.statusCode should be 202: ', response.statusCode);
	console.log('body.id should be a non-empty string: ', body.id);
});

Getting information about an uploaded document

/**
 * @param docId the document ID returned in the body of an upload request
 */
documentApi.info(docId, function(error, response, body) {
	console.log('error should be falsey: ', error);
	console.log('response.statusCode should be 200: ', response.statusCode);
	console.log('body should be an object: ', body);
});

Downloading an uploaded document

/**
 * @param type either 'zip' or 'pdf'
 * @param writeStream a writeable stream; e.g. the return values of require('fs').createWriteSteam('/path/to/file');
 */
documentApi.download(docId, type, writeStream, function(error, response, body) {
	console.log('error should be falsey: ', error);
	console.log('response.statusCode should be 200: ', response.statusCode);
});

Deleting an uploaded document

/**
 * @param docId the document ID returned in the body of an upload request
 */
documentApi.remove(docId, function(error, response, body) {
	console.log('error should be falsey: ', error);
	console.log('response.statusCode should be 204: ', response.statusCode);
	console.log('body should be truthy', body);
});

Poll for completion

Note: This is additional to the Box View API, and is provided as a helper.

/**
 * @param docId the document ID returned in the body of an upload request
 */
documentApi.poll(docId, function(error, response, body) {
	console.log('error should be falsey: ', error);
	console.log('response.statusCode should be 200: ', response.statusCode);
	console.log('body should contain document info', body);
});

The callback will not be invoked until the document has finished converting (or the conversion has failed). The body contains the retrieved document status indicating conversion completion or failure.

Putting it all together

var fs = require('fs');
var documentApi = new require('./index').setToken('API_TOKEN').documentAPI;


var url = 'http://web.crocodoc.com/files/test-simple.pdf';
var docname = 'myTestDoc';

console.log('Uploading: ', url);
documentApi.uploadUrl(url, docname, function (error, response, body) {
  console.log('upload results: error should be falsey: ', error);
  console.log('upload results: response.statusCode should be 202: ', response.statusCode);
  console.log('upload results: body.id should be a non-empty string: ', body.id);
  documentApi.poll(body.id, function (error, response, body) {
    console.log('poll results: error should be falsey: ', error);
    console.log('poll results: response.statusCode should be 200: ', response.statusCode);
    console.log('poll results: body should contain document info', body);
    var zipWs = fs.createWriteStream(docname+'.zip');
    var pdfWs = fs.createWriteStream(docname+'.pdf');

    documentApi.download(body.id, 'zip', zipWs, function (error, response, body) {
      console.log('zip download results: error should be falsey: ', error);
      console.log('zip download results: response.statusCode should be 200: ', response.statusCode);
      console.log('zip download results: body should be truthy', body);
    });

    documentApi.download(body.id, 'pdf', pdfWs, function (error, response, body) {
      console.log('pdf download results: error should be falsey: ', error);
      console.log('pdf download results: response.statusCode should be 200: ', response.statusCode);
      console.log('pdf download results: body should be truthy', body);
    });

  });
});

SessionAPI

var sessionApi = new require('box-view-api').setToken('API_TOKEN').sessionAPI;

Creating a new session

sessionApi.create(docId, function(error, response, body) {
	console.log('error should be falsey: ', error);
	console.log('response.statusCode should be 200: ', response.statusCode);
	console.log('body.session should be a non-empty string', body.session);
});

Note: optionally this can take a second parameter (create(docId, {...}, cb)) with a hash of options to pass to the Box View API as part of the session request. See the Box View API for details of supported parameters.

Bug reports

https://github.com/NetDevLtd/node-box-view-api/issues

Contributing

Fork from: https://github.com/NetDevLtd/node-box-view-api

All contributions and constructive suggestions are welcome.

Set-up

Once you've cloned your fork to a local repo, to install all the dependencies, run:

$ make install

You can then run make lint and make test, to de-lint and run the tests, respectively.

In order to run the tests, you will need to configure the test framework with your Box View API token:

edit test/framework/boxViewDetails.js, and change the dummy token to your API token.

If you don't do this, many of the tests will fail!

To make git stop tracking changes to this file, so that your sensitive API token doesn't get accidentally committed:

$ git update-index --assume-unchanged test/framework/boxViewDetails.js

You can still explicitly git add it, or if you want to turn tracking on again:

$ git update-index --no-assume-unchanged test/framework/boxViewDetails.js

These instructions are duplicated in the file.

Pull requests

Please ensure that Pull Requests:

• are lint-free: make lint, with an unmodified .jshintrc
• include new / modified mocha tests: these should be in test/spec
• pass all tests: make test reports no errors.