Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 198 lines (121 sloc) 9.547 kb
9fd1be1 @evnm Started README content.
authored
1 # dropbox-node
2
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
3 An OAuth-enabled Node.js client for working with the Dropbox API.
aaae1c7 @evnm Added incomplete disclaimer to README.
authored
4
6232247 @evnm Added installation and todo blurbs.
authored
5 ## Installation
6
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
7 dropbox-node depends on [node-oauth](http://github.com/ciaranj/node-oauth).
6232247 @evnm Added installation and todo blurbs.
authored
8
993b35f @evnm Added instructions for installation via npm.
authored
9 To install via npm
10
11 npm install dropbox
12
13 To install by hand, download the module and create a symlink in `~/.node_libraries`
6232247 @evnm Added installation and todo blurbs.
authored
14
15 $ ln -s /path/to/dropbox-node/ ~/.node_libraries/dropbox-node
16
ae5b4af @evnm Wrote usage and testing sections.
authored
17 ## Usage
18
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
19 To start, grab a consumer key and secret from [dropbox.com/developers](https://dropbox.com/developers).
ae5b4af @evnm Wrote usage and testing sections.
authored
20
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
21 ### Object construction and access key pair retrieval
22 First construct a DropboxClient object, passing in the consumer key and secret.
ae5b4af @evnm Wrote usage and testing sections.
authored
23
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
24 var dropbox = new DropboxClient(consumer_key, consumer_secret)
ae5b4af @evnm Wrote usage and testing sections.
authored
25
5444ec6 @evnm Update README to reflect changes to ctor and addition of `createAccount`...
authored
26 Before calling any Dropbox API methods, an access token pair must be obtained. This can be done one of two ways:
ae5b4af @evnm Wrote usage and testing sections.
authored
27
5444ec6 @evnm Update README to reflect changes to ctor and addition of `createAccount`...
authored
28 1. If the access token and secret are known a priori, they can be passed directly into the DropboxClient constructor.
29
30 var dropbox = new DropboxClient(consumer_key, consumer_secret,
31 access_token, access_token_secret)
32
33 2. Otherwise, `getAccessToken` must be called in order to initialize the OAuth credentials.
34
35 dropbox.getAccessToken(dropbox_email, dropbox_password, callback)
ae5b4af @evnm Wrote usage and testing sections.
authored
36
51d326e @evnm Add password-storage warning to README.
authored
37 The callback given to `getAccessToken` takes an error object, an access token, and an access token secret (see example below). **Please note that users' passwords should never be stored.** It is best to acquire a token once and then use it for all subsequent requests.
ae5b4af @evnm Wrote usage and testing sections.
authored
38
39 ### Calling API methods
40
5444ec6 @evnm Update README to reflect changes to ctor and addition of `createAccount`...
authored
41 dropbox-node provides methods covering [each of the Dropbox API methods](https://www.dropbox.com/developers/docs). For example, to fetch and print the display name and email address associated with your account:
ae5b4af @evnm Wrote usage and testing sections.
authored
42
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
43 dropbox.getAccountInfo(function (err, data) {
44 if (err) console.log('Error: ' + err)
45 else console.log(data.display_name + ', ' + data.email)
46 })
47
938a22a @evnm Update README.
authored
48 Note that (at least at the start of a user's session) a valid access token pair must be obtained prior to interacting with the rest of the Dropbox API. This means that the API methods must be invoked within the callback passed to `getAccessToken` unless it is guaranteed that `getAccessToken` was called previously. As an example of this latter case, if building a web app, one could call API methods directly in a route that can only be accessed after going through a sign-in phase in which a call to `getAccessToken` is made.
ae5b4af @evnm Wrote usage and testing sections.
authored
49
81ba78e @evnm Add link in README to file browser walkthrough.
authored
50 Here we upload a file and remotely move it around before deleting it.
ae5b4af @evnm Wrote usage and testing sections.
authored
51
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
52 dropbox.getAccessToken(email, pwd, function (err, token, secret) {
53 // Upload foo.txt to the Dropbox root directory.
f7b843a @fent added API documentation
fent authored
54 dropbox.putFile('foo.txt', 'foo.txt', function (err, data) {
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
55 if (err) return console.error(err)
56
5e24ff7 @evnm Fix broken control flow of example in README.
authored
57 // Move it into the Public directory.
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
58 dropbox.move('foo.txt', 'Public/foo.txt', function (err, data) {
59 if (err) return console.error(err)
60
61 // Delete the file.
e0570bf @evnm s/function(/function (/
authored
62 dropbox.deleteItem('Public/foo.txt', function (err, data) {
355a639 @evnm Remove semicolon in README.
authored
63 if (err) console.error(err.stack)
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
64 })
65 })
66 })
67 })
ae5b4af @evnm Wrote usage and testing sections.
authored
68
81ba78e @evnm Add link in README to file browser walkthrough.
authored
69 For a more practical example, check out this [walkthrough of building a simple Dropbox file browser](http://evanmeagher.net/2010/10/dropbox-file-browser).
70
938a22a @evnm Update README.
authored
71 ### Stream-based file-downloading
72
73 As of v0.3.1, dropbox-node exposes a method `getFileStream` that allows stream-based file-downloading. This is useful when downloading large files that wouldn't easily fit in memory and thus don't play nicely with `getFile`.
74
75 `getFileStream` returns an EventEmitter representing the request. The target file will be downloaded in chunks and dealt with according to the callbacks you register. Here we fetch a large file and write it to disk:
76
77 var request = dropbox.getFileStream("path/to/huge/file")
78 , write_stream = require('fs').createWriteStream("out")
79
80 request.on('response', function (response) {
31fab12 @evnm Fix erroneous variable name in example code.
authored
81 response.on('data', function (chunk) { write_stream.write(chunk) })
82 response.on('end', function () { write_stream.end() })
938a22a @evnm Update README.
authored
83 })
84 request.end()
85
86 ### Optional arguments
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
87
88 Optional arguments (as specified in the [Dropbox API documentation](https://www.dropbox.com/developers/docs)) can be given to API methods via an argument object.
89
90 For example, here we call `getAccountInfo` and direct the API to include the HTTP status code in the response.
91
92 dropbox.getAccountInfo({ status_in_response: true }, callback)
93
938a22a @evnm Update README.
authored
94 Each method (except `getAccessToken`) can optionally take an access token and an access token secret as strings. This is the one way to get around having to call `getAccessToken` in cases where a valid key pair is known.
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
95
96 For example, here we fetch the metadata about the Dropbox root directory, passing in an explicit key pair stored in variables.
97
98 dropbox.getMetadata('', { token: token, secret: secret }, callback)
99
f7b843a @fent added API documentation
fent authored
100 ## API
101
102 ### new DropboxClient()
103
104 ### DropboxClient#getAccessToken(email, password, callback(err, access_token, access_token_secret))
105
106 Fetches an access token and secret based on the email and password given. Stores the token and secret in the DropboxClient instance and calls the callback them.
107
108 ### DropboxClient#getAccountInfo([optargs], callback(err, accountInfo))
109 https://www.dropbox.com/developers/reference/api#account-info
110
111 Gets account information from the client.
112
113 ### DropboxClient#createAccount(email, first_name, last_name, password, [optargs], callback(err, accountInfo))
114
115 Creates a new Dropbox account.
116
117 ### DropboxClient#getFile(path, [optargs], [callback(err, body)])
118 https://www.dropbox.com/developers/reference/api#files-GET
119
120 Retrieves a file specified by the path. `callback` will be called with a possible error and the buffer of the contents of the file. This method also returns a readable stream that can be used to pipe the contents.
121
122 ```js
123 dropboxClient('mybigfile.mpeg').pipe(fs.createWriteStream('localbigfile.mpeg');
124 ```
125
126 `optargs` can also have a `rev` field to specify the revision of the file to download, and `range` for [HTTP Range Retrieval Requests](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.2).
127
128 ```js
129 // download the first 1024 byte
130 dropboxClient('file.zip', { range: 'bytes=0-1024'}, function(err, data) {
131 console.log(data.length); // 1024. that is if the file is at least 1024 bytes
132 });
133 ```
134
135 ### DropboxClient#putFile(filepath, remotepath, [optargs], callback(err, metadata))
136 https://www.dropbox.com/developers/reference/api#files_put
137
138 Uploads a file specified by `filepath` to `remotepath` on Dropbox. Dropbox currently does not support streaming uploads, and the max upload is 150 MB. `optargs` can also take additional fields `overwrite` and `parent_rev`.
139
140 ### DropboxClient#put(contents, remotepath, [optargs], callback(err, metadata))
141 o
142 Similar to `putFile()` but places `contents` into a created file at `remotepath`. `contents` can be a buffer or string.
143
144 ### DropboxClient#getMetadata(path, [optargs], callback(err, metadata))
145 https://www.dropbox.com/developers/reference/api#metadata
146
147 Gets metadata of file/folder specified by `path`. `optargs` can have fields `hash`, `list`, `include_deleted` and `rev`.
148
149 ### DropboxClient#delta([cursor], [optargs], callback(err, changes))
150 https://www.dropbox.com/developers/reference/api#delta
151
152 Keeps up with changes from a client's Dropbox. `changes` is an array of arrays with first element as the path and second as metadata.
153
154 ### DropboxClient#changesStream([startingCursor], [optargs])
155 Convenient method that provides a more friendly API to `delta()`. Returns an event emitter that emits `data` events with `path` and `metadata` parameters on changes to the client's Dropbox. Also can emit `reset` and `error` events. The returned event emitter also has a `pause()` and `resume()` methods.
156
157 ### DropboxClient#search(folderpath, query, [optargs], callback(err, results))
158 https://www.dropbox.com/developers/reference/api#search
159
160 Searches `folderpath` for files matching `query`. `results` is an array of metadata. `optargs` can take `file_limit` and `include_deleted`.
161
162 ### DropboxClient#getThumbnail(filepath, [optargs], [callback(err, body, metadata)])
163 https://www.dropbox.com/developers/reference/api#thumbnails
164
165 Downloads a thumbnail image located at `filepath`. Like `getFile()`, the `callback` can get buffered data or the returned readable stream can be piped. `optargs` can take `format` and `size` fields.
166
167 ### DropboxClient#copy(from_path, to_path, [optargs], callback)
168 https://www.dropbox.com/developers/reference/api#fileops-copy
169
170 Copies a file. `from_copy_ref` field can be given in `optargs` to use it instead of `from_path`.
171
172 ### DropboxClient#createFolder(path, [optargs], callback(err, metadata))
173 https://www.dropbox.com/developers/reference/api#fileops-create-folder
174
175 Creates a folder at the given path.
176
177 ### DropboxClient#deleteItem(path, [optargs], callback(err, metadata))
178 https://www.dropbox.com/developers/reference/api#fileops-delete
179
180 Deletes file or folder from path.
181
182 ### DropboxClient#move(from_path, to_path, [optargs], callback(err, metadata))
183 https://www.dropbox.com/developers/reference/api#fileops-move
184
185 Moves a file to another path.
186
187
ae5b4af @evnm Wrote usage and testing sections.
authored
188 ## Testing
189
938a22a @evnm Update README.
authored
190 dropbox-node depends on [jasmine-node](http://github.com/mhevery/jasmine-node) for testing. Note that the currently-implemented tests are trivial, due to a lack of a way to effectively mock the Dropbox API.
ae5b4af @evnm Wrote usage and testing sections.
authored
191
192 Run specs with `node specs.js` from the root `dropbox-node` directory.
193
6232247 @evnm Added installation and todo blurbs.
authored
194 ## TODO
195 * Improve test coverage.
a8ad6eb @evnm Add documentation todo item.
authored
196 * Improve documentation.
ae5b4af @evnm Wrote usage and testing sections.
authored
197 * Add ability to interact with application sandboxes.
Something went wrong with that request. Please try again.