Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 197 lines (119 sloc) 9.253 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
621f796 @evnm Add deprecation disclaimer in README.
authored
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
9 ## Installation
10
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
11 dropbox-node depends on [node-oauth](http://github.com/ciaranj/node-oauth).
6232247 @evnm Added installation and todo blurbs.
authored
12
993b35f @evnm Added instructions for installation via npm.
authored
13 To install via npm
14
2984b48 @seven1m Update README.md
seven1m authored
15 npm install dropbox-node
993b35f @evnm Added instructions for installation via npm.
authored
16
17 To install by hand, download the module and create a symlink in `~/.node_libraries`
6232247 @evnm Added installation and todo blurbs.
authored
18
19 $ ln -s /path/to/dropbox-node/ ~/.node_libraries/dropbox-node
20
ae5b4af @evnm Wrote usage and testing sections.
authored
21 ## Usage
22
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
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
24
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
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
27
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
28 var dropbox = new DropboxClient(consumer_key, consumer_secret)
ae5b4af @evnm Wrote usage and testing sections.
authored
29
5444ec6 @evnm Update README to reflect changes to ctor and addition of `createAccount`...
authored
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
31
5444ec6 @evnm Update README to reflect changes to ctor and addition of `createAccount`...
authored
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
40
51d326e @evnm Add password-storage warning to README.
authored
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
42
43 ### Calling API methods
44
5444ec6 @evnm Update README to reflect changes to ctor and addition of `createAccount`...
authored
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
46
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
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
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
53
81ba78e @evnm Add link in README to file browser walkthrough.
authored
54 Here we upload a file and remotely move it around before deleting it.
ae5b4af @evnm Wrote usage and testing sections.
authored
55
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
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
58 dropbox.putFile('foo.txt', 'foo.txt', function (err, data) {
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
59 if (err) return console.error(err)
60
5e24ff7 @evnm Fix broken control flow of example in README.
authored
61 // Move it into the Public directory.
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
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
66 dropbox.deleteItem('Public/foo.txt', function (err, data) {
355a639 @evnm Remove semicolon in README.
authored
67 if (err) console.error(err.stack)
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
68 })
69 })
70 })
71 })
ae5b4af @evnm Wrote usage and testing sections.
authored
72
81ba78e @evnm Add link in README to file browser walkthrough.
authored
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
75 ### Optional arguments
e9bf3ab @evnm Update README to reflect changes to API semantics.
authored
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
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
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
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
cea354f @snakamura Added DropboxClient#shares and media.
snakamura authored
156 ### DropboxClient#shares(path, [optargs], [callback(err, link)])
157 https://www.dropbox.com/developers/reference/api#shares
158
159 Creates and gets a link to file/folder specified by `path`.
160
161 ### DropboxClient#media(filepath, [optargs], [callback(err, link)])
162 https://www.dropbox.com/developers/reference/api#media
163
164 Creates and gets a direct link to file specified by `filepath`.
165
f7b843a @fent added API documentation
fent authored
166 ### DropboxClient#copy(from_path, to_path, [optargs], callback)
167 https://www.dropbox.com/developers/reference/api#fileops-copy
168
169 Copies a file. `from_copy_ref` field can be given in `optargs` to use it instead of `from_path`.
170
171 ### DropboxClient#createFolder(path, [optargs], callback(err, metadata))
172 https://www.dropbox.com/developers/reference/api#fileops-create-folder
173
174 Creates a folder at the given path.
175
176 ### DropboxClient#deleteItem(path, [optargs], callback(err, metadata))
177 https://www.dropbox.com/developers/reference/api#fileops-delete
178
179 Deletes file or folder from path.
180
181 ### DropboxClient#move(from_path, to_path, [optargs], callback(err, metadata))
182 https://www.dropbox.com/developers/reference/api#fileops-move
183
184 Moves a file to another path.
185
186
ae5b4af @evnm Wrote usage and testing sections.
authored
187 ## Testing
188
938a22a @evnm Update README.
authored
189 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
190
191 Run specs with `node specs.js` from the root `dropbox-node` directory.
192
6232247 @evnm Added installation and todo blurbs.
authored
193 ## TODO
194 * Improve test coverage.
a8ad6eb @evnm Add documentation todo item.
authored
195 * Improve documentation.
ae5b4af @evnm Wrote usage and testing sections.
authored
196 * Add ability to interact with application sandboxes.
Something went wrong with that request. Please try again.