node-box-sdk

Node.js Box SDK

---

Deprecated

In July 2015 Box released their official node module. This has since been deprecated in favor of supporting development efforts there. https://www.npmjs.com/package/box-node-sdk https://github.com/box/box-node-sdk

---

Node.js module for both Box.com Content API & Box.com View API

The purpose of this module is to provide an efficient and intentional method of interacting with the Box APIs. This SDK wraps both the Box Content and View API Thus, it is important to understand the Box APIs at the REST endpoint level. You are strongly encouraged to read the Box documentation.

Examples of how to integrate this module into Express as middleware and into Hapi as a plugin are located in the examples folder. The examples provided show how to attach the node-box-sdk to the server object, set the returned encrypted token string as a cookie and how to use this encrypted token string with the node-box-sdk methods.

Contributors Welcome!

Status

#####Content API

• Authentication - Completed
• Folders - Completed
• Files - Completed
• Shared Items - Completed
• All Additional Methods - In Progress

#####View API

• Document - Partially Complete - In Progress
• Sessions - Partially Complete - In Progress
• All Additional Methods - In Progress

---

Install

npm install node-box-sdk

---

Configure

box.configure({
  client_id: 'content_api_client_id',             // REQUIRED
  client_secret: 'content_api_client_secret',     // REQUIRED
  api_key: 'view_api_client_secret',              // REQUIRED
  encrypt: { password: 'pick_a_password' }        // OPTIONAL
});

---

Content API

Authorization

Authorize

Returns the URL of Box’s authorization page in the response.redirect. This is the URL that your application should forward the user to in first leg of OAuth. After successful login it returns YOUR_REDIRECT_URI?code=THE_AUTHORIZATION_CODE.

  var state = 'abc-xyz'; // An arbitrary string of your choosing that will be included in the response to your application.
  box.authorize(state, function(err, res) { });

Generate Tokens

Returns the access tokens. If the box client was configured using encrypt with a password then the tokens will be returned as an encrypted string. Otherwise the tokens will be returned as an object. Either the encrypted token string or the token object will need to be persisted, because the box client will handle refreshing the authorization tokens as needed.

One option is to set the encrypted token string as cookie in a web application. Examples of this strategy are provided.

  box.generateToken({ authorization_code: code }, function(err, tokens) { });

---

###Folder Operations All methods have a 3rd argument in the callback function 'tokens'. Each time the node-box-sdk callsback with the access tokens as an encrypted string.

The reason for this is because - iIf the access token was expired, node-box-sdk will attempt to refresh this token and then returns the updated version of the access tokens as an encrypted string. If no refresh was needed then it returns the same access tokens as an encrypted string.

Create

Returns a full folder object in the response.body if the parent folder ID is valid.

var data = { name: 'BoxTest', parent: { id: 0 }};
box.content.folder.create(data, { tokens: tokens }, function(err, res, tokens) { });

Get

Returns a full folder object in the response.body.

box.content.folder.get(folderID, { tokens: tokens }, function(err, res, tokens) { });

Items

Returns the files and/or folders contained within this folder in the response.body.

box.content.folder.items(folderID, { tokens: tokens }, function(err, res, tokens) { });

Update

Returns a full folder object in the response.body.

var data = { name: 'BoxTestUpdate', description: 'A folder in Box.'};
box.content.folder.update(folderID, data, { tokens: tokens }, function(err, res, tokens) { });

Delete

Moves the folder to trash. Returns an empty response.body and a 204 if successful. *A recursive parameter must be included in order to delete folders that have items inside of them

var options = { tokens: tokens params: { recursive: true } };
box.content.folder.delete(folderID, options, function(err, res, tokens) { });

Permanently Delete

Permanently deletes an item that is in the trash. The item will no longer exist in Box. This action cannot be undone. Returns an empty response.body and a 204 if successful.

box.content.folder.destroy(folderID, { tokens: tokens }, function(err, res, tokens) { });

Copy

Returns a full folder object in the response.body if the parent folder ID is valid.

var data = { parent: { id : 0 }, name: "AnotherBoxTest" };
box.content.folder.copy(folderID, data, { tokens: tokens }, function(err, res, tokens) { });

Restore

Restores a full folder object that is in the trash.

box.content.folder.restore(folderID, {}, { tokens: tokens }, function(err, res, tokens) { });

Trash

View the files and/or folders that have been moved to the trash.

box.content.folder.trash(null, { tokens: tokens }, function(err, res, tokens) { });

View a specific folders that has been moved to the trash.

box.content.folder.trash(folderID, { tokens: tokens }, function(err, res, tokens) { });

Share

Creates a shared link for this folder, returns a full folder object in the response.body.

var data = { shared_link: { } }; // default access
box.content.folder.share(folderID, data, { tokens: tokens }, function(err, res, tokens) { });

Collaborations

Returns a list of all the collaborations on a folder.

box.content.folder.collaborations(folderID, { tokens: tokens }, function(err, res, tokens) { });

---

###File Operations All methods have a 3rd argument in the callback function 'tokens'. Each time the node-box-sdk callsback with the access tokens as an encrypted string.

The reason for this is because - iIf the access token was expired, node-box-sdk will attempt to refresh this token and then returns the updated version of the access tokens as an encrypted string. If no refresh was needed then it returns the same access tokens as an encrypted string.

// TODO update docs

---

###Shared Items Operations All methods have a 3rd argument in the callback function 'tokens'. Each time the node-box-sdk callsback with the access tokens as an encrypted string.

The reason for this is because - iIf the access token was expired, node-box-sdk will attempt to refresh this token and then returns the updated version of the access tokens as an encrypted string. If no refresh was needed then it returns the same access tokens as an encrypted string.

// TODO update docs

---

View API

// TODO update docs

---

Express Use Example

Using node-box-sdk inside Express

Hapi Use Example

Using node-box-sdk inside Hapi

---

Inspiration + References

API link mixins and dynamic REST API generator - Paypal SDK

Testing with Casper & PhantomJS - Node Box