box-view-api

Box View API, node.js client library

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.

  • Latest:

Release Notes, Issues & Roadmap: RELEASE_NOTES.md

From the command-line:

$ npm install box-view-api

package.json:

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

See Contributing section below

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.

var documentApi = new require('box-view-api').setToken('API_TOKEN').documentAPI;
/**
 * @param searchOptions (optional) an object containing the search options to pass to the Box View API
 */
documentApi.list(searchOptions, function(errorresponsebody) {
    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.

/**
 * @param url URL of file to upload to Box View
 * @param name the name of the file
 */
documentApi.uploadUrl(url, name, function(errorresponsebody) {
    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);
});
/**
 * @param docId the document ID returned in the body of an upload request
 */
documentApi.info(docId, function(errorresponsebody) {
    console.log('error should be falsey: ', error);
    console.log('response.statusCode should be 200: ', response.statusCode);
    console.log('body should be an object: ', body);
});
/**
 * @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(errorresponsebody) {
    console.log('error should be falsey: ', error);
    console.log('response.statusCode should be 200: ', response.statusCode);
});
/**
 * @param docId the document ID returned in the body of an upload request
 */
documentApi.remove(docId, function(errorresponsebody) {
    console.log('error should be falsey: ', error);
    console.log('response.statusCode should be 204: ', response.statusCode);
    console.log('body should be truthy', body);
});

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(errorresponsebody) {
    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.

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 (errorresponsebody) {
  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 (errorresponsebody) {
    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 (errorresponsebody) {
      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 (errorresponsebody) {
      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);
    });
 
  });
});
var sessionApi = new require('box-view-api').setToken('API_TOKEN').sessionAPI;
sessionApi.create(docId, function(errorresponsebody) {
    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.

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

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

All contributions and constructive suggestions are welcome.

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.

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.