nicholasanthony / dropbox-js

Javascript implementation of Dropbox APIv2 using Dropbox HTTP API

dropbox-js

Javascript implementation of Dropbox APIv2 using Dropbox HTTP API.

This implementation directly follows the official Dropbox API documentation found at: https://www.dropbox.com/developers/documentation/http/documentation.
It is simply a wrapper around XMLHttpRequest that adjusts the request and response handling to account for variances in the Dropbox API (like different API endpoint URLs, expected requeset headers, etc.) and exposes a consistent javascript API to make the requests.

Though the entire Dropbox API is accessible, only a subset has been exercised through this tool. Please report any bugs and I will do what I can to resolve them quickly.

Usage

dropbox(apiFunction, apiArguments, handlers);

// ex:
dropbox('files/list_folder', {path: '/some/path'}, function(result){ console.log(result.entries); });
// or
dropbox('files/list_folder', {path: '/some/path'}, {
  onComplete: function(result){ console.log(result.entries); },
  onDownloadProgress: function(result){ console.log(result.entries); }
);

The values for apiFunction and apiArguments are exactly as documented in the official Dropbox API documentation.

handlers can either be a single function (assumed to be onComplete equivalent), or an object of functions. Currently supported: onComplete, onError, onDownloadProgress and onUploadProgress(for browsers which support it)
onComplete receives the JSON API response, the response payload, and a reference to the XMLHttpRequest object.
onError recieves a reference to the XMLHttpRequest object.
onDownloadProgress and onUploadProgress are directly attached to the XMLHttpRequest object. see: https://developer.mozilla.org/en-US/docs/Web/Events/progress

Returns a Promise if supported by the runtime environment, otherwise undefined. See Promises below.

Global Reference

When including this script in the browser, by default it will attach itself to window.dropbox. To change this behavior, set window.__dropbox_export to the name you prefer it to export as.

<script>
  window.__dropbox_export = 'dropbox_v2';
</script>
<script src="..../dropbox.js"></script>
<script>
  // this library will now be accessible via window.dropbox_v2
</script>

Authentication

dropbox.authenticate('client_id', handlers);
//or
dropbox.authenticate( { client_id: 'client_id', redirect_uri: 'http....' }, function(){ /* successfully authenticated */ } );

Currently, only token authentication is supported by this library. The authentication code currently assumes it is executing in a browser and uses the state parameter to implement the CSRF token. I intend to expose state to the dropbox.authenticate method for use by the consumer eventually.

handlers can either be a single function (assumed to be onComplete equivalent), or an object of functions. Currently suppoorted: onComplete, onError.
onComplete receives no parameters.
onError receives an object with the deserialized URL hash params which should include error and error_description from Dropbox.

Returns a Promise if supported by the runtime environment, otherwise undefined. See Promises below.

Global Error Handling

Rather than handling errors at every API call, you can register a global error handler.

dropbox.setGlobalErrorHandler(handler);

The global error handler, if specified, is called after the call-specific error handler is called. It is passed the same parameter(s) as the call-specific error handler, plus the return value of the call-specific error handler. For example, you can shortcut global error handling for a specific API call like this:

dropbox.setGlobalErrorHandler( function(http, alreadyHandled){ if(alreadyHandled){ return; } } );

dropbox('files/list_folder', { path: '' }, { onError: function(){ return true; }});

Token Storage

By default, the CSRF token and the user_access token returned by Dropbox after successful authentication are stored in localStorage. You can override this by injecting a custom token store. A token store is simply a function that takes one or two arguments (i.e. key and value) and gets or sets the value for the key as appropriate. If called with only one parameter, the value should be returned and when called with two parameters, the value should be set.

dropbox.setTokenStore( customStore )

// ex:
var localStorageTokenStore = function(key,val){
  return ( arguments.length > 1 ) ? (localStorage[key] = val) : localStorage[key];
}
dropbox.setTokenStore( localStorageTokenStore );

Promises

If Promise is defined globally, calls to dropbox() and authenticate() will return a new Promise which will be resolved & rejected following the same rules as onComplete and onError handlers above. The only difference is that the global Error handler (if any) cannot receive return values from Error handlers attached via the returned Promise.

You can use https://github.com/stefanpenner/es6-promise as a polyfill for environments which don't support ES6 Promises: http://caniuse.com/#search=Promise