Skip to content
Newer
Older
100644 187 lines (113 sloc) 8.67 KB
9fd1be1 @evnm Started README content.
authored Oct 16, 2010
1 # dropbox-node
2
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored Jan 8, 2011
3 An OAuth-enabled Node.js client for working with the Dropbox API.
aaae1c7 @evnm Added incomplete disclaimer to README.
authored Oct 16, 2010
4
621f796 Add deprecation disclaimer in README.
Evan Meagher authored Oct 11, 2012
5 ## DISCLAIMER
6
7 This project has been deprecated in favor of [Dropbox's official JavaScript library](https://github.com/dropbox/dropbox-js).
8
6232247 @evnm Added installation and todo blurbs.
authored Oct 17, 2010
9 ## Installation
10
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored Jan 9, 2011
11 dropbox-node depends on [node-oauth](http://github.com/ciaranj/node-oauth).
6232247 @evnm Added installation and todo blurbs.
authored Oct 17, 2010
12
993b35f @evnm Added instructions for installation via npm.
authored Oct 18, 2010
13 To install via npm
14
15 npm install dropbox
16
17 To install by hand, download the module and create a symlink in `~/.node_libraries`
6232247 @evnm Added installation and todo blurbs.
authored Oct 17, 2010
18
19 $ ln -s /path/to/dropbox-node/ ~/.node_libraries/dropbox-node
20
ae5b4af @evnm Wrote usage and testing sections.
authored Oct 17, 2010
21 ## Usage
22
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored Jan 9, 2011
23 To start, grab a consumer key and secret from [dropbox.com/developers](https://dropbox.com/developers).
ae5b4af @evnm Wrote usage and testing sections.
authored Oct 18, 2010
24
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored Jan 9, 2011
25 ### Object construction and access key pair retrieval
26 First construct a DropboxClient object, passing in the consumer key and secret.
ae5b4af @evnm Wrote usage and testing sections.
authored Oct 18, 2010
27
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored Jan 9, 2011
28 var dropbox = new DropboxClient(consumer_key, consumer_secret)
ae5b4af @evnm Wrote usage and testing sections.
authored Oct 18, 2010
29
5444ec6 @evnm Update README to reflect changes to ctor and addition of `createAccou…
authored Feb 25, 2011
30 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 Oct 18, 2010
31
5444ec6 @evnm Update README to reflect changes to ctor and addition of `createAccou…
authored Feb 26, 2011
32 1. If the access token and secret are known a priori, they can be passed directly into the DropboxClient constructor.
33
34 var dropbox = new DropboxClient(consumer_key, consumer_secret,
35 access_token, access_token_secret)
36
37 2. Otherwise, `getAccessToken` must be called in order to initialize the OAuth credentials.
38
39 dropbox.getAccessToken(dropbox_email, dropbox_password, callback)
ae5b4af @evnm Wrote usage and testing sections.
authored Oct 18, 2010
40
51d326e @evnm Add password-storage warning to README.
authored May 14, 2011
41 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 Oct 18, 2010
42
43 ### Calling API methods
44
5444ec6 @evnm Update README to reflect changes to ctor and addition of `createAccou…
authored Feb 26, 2011
45 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 Oct 18, 2010
46
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored Jan 9, 2011
47 dropbox.getAccountInfo(function (err, data) {
48 if (err) console.log('Error: ' + err)
49 else console.log(data.display_name + ', ' + data.email)
50 })
51
938a22a @evnm Update README.
authored May 14, 2011
52 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 Oct 18, 2010
53
81ba78e @evnm Add link in README to file browser walkthrough.
authored Nov 18, 2010
54 Here we upload a file and remotely move it around before deleting it.
ae5b4af @evnm Wrote usage and testing sections.
authored Oct 18, 2010
55
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored Jan 9, 2011
56 dropbox.getAccessToken(email, pwd, function (err, token, secret) {
57 // Upload foo.txt to the Dropbox root directory.
f7b843a @fent added API documentation
fent authored Apr 3, 2012
58 dropbox.putFile('foo.txt', 'foo.txt', function (err, data) {
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored Jan 9, 2011
59 if (err) return console.error(err)
60
5e24ff7 @evnm Fix broken control flow of example in README.
authored Nov 18, 2010
61 // Move it into the Public directory.
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored Jan 9, 2011
62 dropbox.move('foo.txt', 'Public/foo.txt', function (err, data) {
63 if (err) return console.error(err)
64
65 // Delete the file.
e0570bf @evnm s/function(/function (/
authored Jan 8, 2011
66 dropbox.deleteItem('Public/foo.txt', function (err, data) {
355a639 @evnm Remove semicolon in README.
authored Jan 19, 2011
67 if (err) console.error(err.stack)
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored Jan 9, 2011
68 })
69 })
70 })
71 })
ae5b4af @evnm Wrote usage and testing sections.
authored Oct 18, 2010
72
81ba78e @evnm Add link in README to file browser walkthrough.
authored Nov 18, 2010
73 For a more practical example, check out this [walkthrough of building a simple Dropbox file browser](http://evanmeagher.net/2010/10/dropbox-file-browser).
74
938a22a @evnm Update README.
authored May 14, 2011
75 ### Optional arguments
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored Jan 9, 2011
76
77 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.
78
79 For example, here we call `getAccountInfo` and direct the API to include the HTTP status code in the response.
80
81 dropbox.getAccountInfo({ status_in_response: true }, callback)
82
938a22a @evnm Update README.
authored May 14, 2011
83 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 Jan 9, 2011
84
85 For example, here we fetch the metadata about the Dropbox root directory, passing in an explicit key pair stored in variables.
86
87 dropbox.getMetadata('', { token: token, secret: secret }, callback)
88
f7b843a @fent added API documentation
fent authored Apr 3, 2012
89 ## API
90
91 ### new DropboxClient()
92
93 ### DropboxClient#getAccessToken(email, password, callback(err, access_token, access_token_secret))
94
95 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.
96
97 ### DropboxClient#getAccountInfo([optargs], callback(err, accountInfo))
98 https://www.dropbox.com/developers/reference/api#account-info
99
100 Gets account information from the client.
101
102 ### DropboxClient#createAccount(email, first_name, last_name, password, [optargs], callback(err, accountInfo))
103
104 Creates a new Dropbox account.
105
106 ### DropboxClient#getFile(path, [optargs], [callback(err, body)])
107 https://www.dropbox.com/developers/reference/api#files-GET
108
109 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.
110
111 ```js
112 dropboxClient('mybigfile.mpeg').pipe(fs.createWriteStream('localbigfile.mpeg');
113 ```
114
115 `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).
116
117 ```js
118 // download the first 1024 byte
119 dropboxClient('file.zip', { range: 'bytes=0-1024'}, function(err, data) {
120 console.log(data.length); // 1024. that is if the file is at least 1024 bytes
121 });
122 ```
123
124 ### DropboxClient#putFile(filepath, remotepath, [optargs], callback(err, metadata))
125 https://www.dropbox.com/developers/reference/api#files_put
126
127 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`.
128
129 ### DropboxClient#put(contents, remotepath, [optargs], callback(err, metadata))
130 o
131 Similar to `putFile()` but places `contents` into a created file at `remotepath`. `contents` can be a buffer or string.
132
133 ### DropboxClient#getMetadata(path, [optargs], callback(err, metadata))
134 https://www.dropbox.com/developers/reference/api#metadata
135
136 Gets metadata of file/folder specified by `path`. `optargs` can have fields `hash`, `list`, `include_deleted` and `rev`.
137
138 ### DropboxClient#delta([cursor], [optargs], callback(err, changes))
139 https://www.dropbox.com/developers/reference/api#delta
140
141 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.
142
143 ### DropboxClient#changesStream([startingCursor], [optargs])
144 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.
145
146 ### DropboxClient#search(folderpath, query, [optargs], callback(err, results))
147 https://www.dropbox.com/developers/reference/api#search
148
149 Searches `folderpath` for files matching `query`. `results` is an array of metadata. `optargs` can take `file_limit` and `include_deleted`.
150
151 ### DropboxClient#getThumbnail(filepath, [optargs], [callback(err, body, metadata)])
152 https://www.dropbox.com/developers/reference/api#thumbnails
153
154 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.
155
156 ### DropboxClient#copy(from_path, to_path, [optargs], callback)
157 https://www.dropbox.com/developers/reference/api#fileops-copy
158
159 Copies a file. `from_copy_ref` field can be given in `optargs` to use it instead of `from_path`.
160
161 ### DropboxClient#createFolder(path, [optargs], callback(err, metadata))
162 https://www.dropbox.com/developers/reference/api#fileops-create-folder
163
164 Creates a folder at the given path.
165
166 ### DropboxClient#deleteItem(path, [optargs], callback(err, metadata))
167 https://www.dropbox.com/developers/reference/api#fileops-delete
168
169 Deletes file or folder from path.
170
171 ### DropboxClient#move(from_path, to_path, [optargs], callback(err, metadata))
172 https://www.dropbox.com/developers/reference/api#fileops-move
173
174 Moves a file to another path.
175
176
ae5b4af @evnm Wrote usage and testing sections.
authored Oct 18, 2010
177 ## Testing
178
938a22a @evnm Update README.
authored May 14, 2011
179 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 Oct 18, 2010
180
181 Run specs with `node specs.js` from the root `dropbox-node` directory.
182
6232247 @evnm Added installation and todo blurbs.
authored Oct 17, 2010
183 ## TODO
184 * Improve test coverage.
a8ad6eb @evnm Add documentation todo item.
authored Nov 8, 2010
185 * Improve documentation.
ae5b4af @evnm Wrote usage and testing sections.
authored Oct 18, 2010
186 * Add ability to interact with application sandboxes.
Something went wrong with that request. Please try again.