boxsdk

#boxSDK for Node.js README The client can be used to make Oauth easier, do get,post,put and delete calls and handle file uploads.

##Authentication First make a client builder and pass the app ID and secret.

The client Builder should be outside of any requests, that way it's accessible from all requests; it's there so you don't have to give the client your appID and secret each time you need it. ###Setup Client Factory:

		var boxSDK = require('boxSDK')
		var appSettings = {
			appID: 'YOUR APP IDD',
			secret: 'YOUR APP SECRET',
			callBackURL : 'YOUR CALLBACK URL' // only if you need this
		}
		var clientBuilder = boxSDK.clientBuilder(appSettings)

In your first request get the authurl and redirect the user.

clientBuilder.create() can take a string or an object, if you supply a string it will automatically assign that as the 'ACCESS_TOKEN'. It can also take a user's ID for when you want to do something 'as-user' but it requires the person logged in to be an Admin but it is optional. An object requires it to be formated as :

 var tokens = {
 	access_token : 'ACCESS_TOKEN',
 	refresh_token : 'REFRESH_TOKEN',
 	user    :   'user_id'
 }

###Authentication URL:

		var client = clientBuilder.create()
		var path = client.authURL
		res.redirect(path)

Then pass the auth code to the client and handle with a callback function (i.e. store tokens in cookie like in example). ###Retrieve Access Tokens:

	var client = clientBuilder.create()
	callback = function(response, statusCode){
		res.cookie.('accessToken',response.access_token,{maxAge: 60000 * 59})
		res.cookie.('refreshToken',response.refresh_token,{maxAge: 60000 * 59})
		res.redirect('path to your website after authentication is finished')
	}
	var path = client.getToken('AUTH CODE',callback)

You can also revoke tokens, it will respond with 200 if logout was successful or 400 if it was not. ###Revoke Access Tokens

		var client = clientBuilder.create()
		callback = function(response,statuscode) {
			if(statuscode == 200){
				console.log(response)
			}else{
				console.log(response)
			}
		}
		client.revokeToken(('ACCESS TOKEN' or 'REFRESH TOKEN'),callback)

Lastly you can refresh your access token ###Refresh Tokens:

		var client = clientBuilder.create()
		callback = function(repsponse, statusCode){
			res.cookie.('accessToken',response.access_token,{maxAge: 60000 * 59})
			res.cookie.('refreshToken',response.refresh_token,{maxAge: 60000 * 59})
			res.redirect('some path')
		}
		var path = client.getRefreshToken('REFRESH TOKEN',callback) 

##URL Builder: There is also the url builder you can use to make url building easier and more semantically readable.

	var urlB = boxSDK.urlBuilder
	var path = urlB.host('auth').object('token')

There are three 'hosts' you can use:

1. 'auth' for oauth authentication (unneeded as the client has built in methods for this)
2. 'api' for api access
3. 'upload' for uploading files to box

##Making Requests You can use the client to make get or post requests like so.

###Get folders:

	var client = clientBuilder.create('Access_Token')
	var path = urlB.host('api').object('folders').action('items')
	callback = function(response, statusCode){
		console.log(JSON.stringify(response))
		console.log(statusCode)
	}
	client.get(path,callback)

###Create folders:

	var client = clientBuilder.create('Access_Token')
	var path = urlB.host('api').object('folders')
	var data = {"name":"New Folder", "parent": {"id": "11446498"}}
	callback = function(response, statusCode){
		console.log(JSON.stringify(response))
		console.log(statusCode)
	}
	client.post(path,data,callback)

##File uploading: Currently the client supports uploading files from the server to box, the best way to do this is to use the method Layer function 'uploadFile'.

It will open the file and handle filename and formating so box can understand it.

The file object requires specific formating:

• filename = The whole filepath (the file name itself is taken automatically)
• parent_id = The id of the folder you wish to upload to

The function requires a client, a file object and a callback, you can use it like so: ###File Upload with methodlayer function:

var fileObject = {
	filename: __dirname + '/b.docx',
	parent_id: id
}
boxSDK.files.upload (client, fileObject, 
	function(response,statCode){
	console.log(response)
})

You can also supply the file data directly to the object, it MUST however be in binary encoding otherwise the file won't upload correctly. Just place the data in the fileObject under fileObject.data and the client will pick it up when the object is passed to it.

If you aren't sure the file data isn't in binary you can convert it with:

	var fileObject.data = new Buffer(fileData).toString('binary')

###uploading with streams You can also pipe data to the method as well, however for the moment only streams that write ONLY file data are usable, streams that contain non file data(e.g. multipart forms) won't work correctly as there is no working parser, it will error if you try.

###File Upload with methodlayer function via streams

var file = {
	filename: __dirname + '/a.jpg',
	parent_id: id
}
f = fs.createReadStream(file.filename,{encoding: 'binary'})
f.pipe(boxSDK.files.upload(client,file,
	function (response, statcode){
		console.log(response)
}))

In case you do want to use the client directly you can still use it, but it can't streams, if you want to pass it file data you need to pass it filedata under fileObject.data

Client upload:

	var fileObject = {
		filename: __dirname + '/b.docx',
		parent_id: id,
		data : data
	}
	var path = urlB.host('upload').object('files').url

	client.upload(path, file, function(response,statCode){
		console.log(response)
	})

##Other functions

The purpose of the method layer is to make using the client easier, you don't need to use it to make use of the client but it makes using the box API easier and they contain helper functions so you don't have to do so much.

They're implemented one by one from top to bottom from in the same order as the function listing on the doc website, so when it says up to, it means all functions up to that one specified are implemented.

At the moment the only functions implemented are:

• Folder (all functions)
• Files (all functions)(upload is partially supported via file from server and fata in binary format, can't directly stream from form but from files and data only streams)
• Comments (all functions)
• Collaborations (all functions)
• Events (no functions)
• Search (all functions)
• Users (all functions)
• Groups (all functions)
• Tasks (all functions)