new Connection(box, email)
Parameters:
Name | Type | Description |
---|---|---|
box |
Box | The Box object though which this connection is managed. |
email |
string | The email account identifier to connect to. |
- Source:
Methods
-
<private> _emit(done)
The internal event emitter.
-
Do not call this method directly.
Parameters:
Name Type Description done
function The callback. - Source:
Fires:
-
<private> _longPoll(done)
The internal long-polling sequence.
-
Do not call this method directly.
Parameters:
Name Type Description done
optionalErrorCallback Called after finishing one round of long polling. - Source:
Fires:
-
<private> _request(segments, method, callback, query, payload, data, headers, pipe, config)
Perform an HTTP request on this connection.
-
Do not call this method directly. Use one of the wrapper API methods instead.
Parameters:
Name Type Argument Description segments
string | Array.<string> The path segments to append to the API base URL. method
string The HTTP verb to use for this request. callback
requestCallback The callback to invoke (with possible errors) when the request returns. query
Object <optional>
<nullable>
A map of query parameters. payload
Object <optional>
<nullable>
The request payload. data
external:Readable <optional>
<nullable>
Readable stream representing file data to be uploaded. headers
RequestHeaders <optional>
<nullable>
Additional headers. pipe
external:Writable <optional>
Writable stream representing file data to be saved. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. - Source:
-
<private> _revokeAccess()
Set the authentication tokens for this connection.
-
Do not call this function directly.
- Source:
-
<private> _setTokens(tokens)
Set the authentication tokens for this connection.
-
Do not call this method directly.
Parameters:
Name Type Description tokens
AuthTokens The authentication tokens. - Source:
Fires:
-
<private> _trackEvent(event)
The internal tracker for remote events.
-
Do not call this method directly.
Parameters:
Name Type Description event
Object The event to push. - Source:
-
copyFile(id, parent_id, name, done, config)
Copy a File.
-
Used to create a copy of a file in another folder. The original version of the file will not be altered.
Parameters:
Name Type Argument Description id
number The file's ID. parent_id
number The destination parent folder's ID. name
string The destination file's name. Can be null. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
copyFolder(id, parent_id, name, done, config)
Copy a Folder.
-
Used to create a copy of a folder in another folder. The original version of the folder will not be altered.
Parameters:
Name Type Argument Description id
number The source folder's ID. parent_id
number The destination parent folder's ID. name
string <nullable>
The destination folder's name. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
createFolder(name, parent_id, done, config)
Create a New Folder.
-
Used to create a new empty folder. The new folder will be created inside of the specified parent folder.
Parameters:
Name Type Argument Description name
string The folder's name. parent_id
number The parent folder's ID. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
deleteFile(id, done, headers, config)
Delete a file.
-
Discards a file to the trash. The etag of the file can be included as an
header[If-Match]
header to prevent race conditions.Parameters:
Name Type Argument Description id
number The file's ID. done
requestCallback The callback to invoke (with possible errors) when the request returns. headers
RequestHeaders <optional>
<nullable>
Additional headers. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
deleteFileVersion(id, version, done, headers, config)
Delete an Old Version of a File.
-
Discards a specific file version to the trash.
Parameters:
Name Type Argument Description id
number The file's ID. version
number File version to promote. done
requestCallback The callback to invoke (with possible errors) when the request returns. headers
RequestHeaders <optional>
<nullable>
Additional headers. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
deleteFolder(id, opts, done, headers, config)
Delete a Folder.
-
Used to delete a folder. A recursive parameter must be included in order to delete folders that have items inside of them. An optional
header[If-Match]
header can be included to ensure that client only deletes the folder if it knows about the latest version.Parameters:
Name Type Argument Description id
number The folder's ID. opts
external:OptsDeleteFolder <nullable>
Options to control recursive delete. done
requestCallback The callback to invoke (with possible errors) when the request returns. headers
RequestHeaders <optional>
<nullable>
Additional headers. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
deleteTrashedFile(id, done, config)
Permanently Delete a Trashed File.
-
Permanently deletes an item that is in the trash. The item will no longer exist in Box. This action cannot be undone.
Parameters:
Name Type Argument Description id
number The folder's ID. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
deleteTrashedFolder(id, done, config)
Permanently Delete a Trashed Folder.
-
Permanently deletes an item that is in the trash. The item will no longer exist in Box. This action cannot be undone.
Parameters:
Name Type Argument Description id
number The folder's ID. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
getAuthURL() → {string}
Get the authentication URL to manually navigate to.
-
The returned URL should be provided to the end user when running in standalone mode.
- Source:
Returns:
The authentication URL.- Type
- string
-
getFile(id, version, dest, done, config)
Download a File.
-
Retrieves the actual data of the file. An optional
opts.version
parameter can be set to download a previous version of the file.Parameters:
Name Type Argument Description id
number The file's ID. version
number File version to download. Can be null (meaning get the latest). dest
string Full path to where the file should be saved. done
getFileCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
getFileComments(id, done, config)
View the Comments on a File.
-
Retrieves the comments on a particular file, if any exist.
Parameters:
Name Type Argument Description id
number The file's ID. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
getFileInfo(id, done, headers, config)
Get Information About a File.
-
Used to retrieve the metadata about a file.
Parameters:
Name Type Argument Description id
number The file's ID. done
requestCallback The callback to invoke (with possible errors) when the request returns. headers
RequestHeaders <optional>
<nullable>
Additional headers. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
getFileTasks(id, done, config)
Get the tasks for a file.
-
Retrieves all of the tasks for given file.
Parameters:
Name Type Argument Description id
number The file's ID. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
getFileThumbnail(id, opts, dest, done, config)
Get a Thumbnail for a File.
-
Retrieves a thumbnail, or smaller image representation, of this file. Sizes of 32x32, 64x64, 128x128, and 256x256 can be returned. Currently thumbnails are only available in .png format and will only be generated for image file formats.
Parameters:
Name Type Argument Description id
number The file's ID. opts
external:OptsGetFileThumbnail Thumbnail options. dest
string Full path to where the file should be saved. done
getFileCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
getFileVersions(id, done, config)
View Versions of a File.
-
If there are previous versions of this file, this method can be used to retrieve metadata about the older versions.
Parameters:
Name Type Argument Description id
number The file's ID. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
getFolderCollaborations(id, done, config)
View a Folder’s Collaborations.
-
Use this to get a list of all the collaborations on a folder i.e. all of the users that have access to that folder.
Parameters:
Name Type Argument Description id
number The folder's ID. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
getFolderInfo(id, done, headers, config)
Get Information About a Folder.
-
Retrieves the full metadata about a folder, including information about when it was last updated as well as the files and folders contained in it. The root folder of a Box account is always represented by the id “0″.
Parameters:
Name Type Argument Description id
number The folder's ID. done
requestCallback The callback to invoke (with possible errors) when the request returns. headers
RequestHeaders <optional>
<nullable>
Additional headers. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
getFolderItems(id, opts, done, config)
Retrieve a Folder’s Items.
-
Retrieves the files and/or folders contained within this folder without any other metadata about the folder. Any attribute in the full files or folders objects can be passed in with the
opts.fields
parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default. Multiple attributes can be passed in separated by commas e.g.opts.fields=name,created_at
. Paginated results can be retrieved using theopts.limit
andopts.offset
parameters.Parameters:
Name Type Argument Description id
number The folder's ID. opts
external:OptsFLO <nullable>
Request options. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
getTrashedFile(id, done, config)
Get a Trashed File.
-
Retrieves an item that has been moved to the trash.
Parameters:
Name Type Argument Description id
number The folder's ID. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
getTrashedFolder(id, done, config)
Get a Trashed Folder.
-
Retrieves an item that has been moved to the trash.
Parameters:
Name Type Argument Description id
number The folder's ID. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
getTrashedItems(opts, done, config)
Get the Items in the Trash.
-
Retrieves the files and/or folders that have been moved to the trash. Any attribute in the full files or folders objects can be passed in with the
opts.fields
parameter to get specific attributes, and only those specific attributes back; otherwise, the mini format is returned for each item by default. Multiple attributes can be passed in separated by commas e.g.opts.fields='name,created_at'
. Paginated results can be retrieved using theopts.limit
andopts.offset
parameters.Parameters:
Name Type Argument Description opts
external:OptsFLO <nullable>
Request options. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
isAuthenticated() → {boolean}
-
Determine id the connection has been authenticated.
- Source:
Returns:
True if authenticated.- Type
- boolean
-
promoteFileVersion(id, version, done, config)
Promote an Old Version of a File.
-
If there are previous versions of this file, this method can be used to promote one of the older versions to the top of the stack. This actually mints a copy of the old version and puts it on the top of the versions stack. The file will have the exact same contents, the same SHA1/etag, and the same name as the original. Other properties such as comments do not get updated to their former values.
Parameters:
Name Type Argument Description id
number The file's ID. version
number File version to promote. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
ready(callback)
-
Wait for a connection to get ready.
Parameters:
Name Type Description callback
optionalErrorCallback The callback with an optional err argument, to be invoked once ready. - Source:
-
restoreTrashedFile(id, name, parent_id, done, config)
Restore a Trashed Item.
-
Restores an item that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request.
Parameters:
Name Type Argument Description id
number The file's ID. name
string <nullable>
The file's name. parent_id
number The parent folder's ID. Can be null. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
restoreTrashedFolder(id, name, parent_id, done, config)
Restore a Trashed Folder.
-
Restores an item that has been moved to the trash. Default behavior is to restore the item to the folder it was in before it was moved to the trash. If that parent folder no longer exists or if there is now an item with the same name in that parent folder, the new parent folder and/or new name will need to be included in the request.
Parameters:
Name Type Argument Description id
number The folder's ID. name
string <nullable>
The folder's name. parent_id
number <nullable>
The parent folder's ID. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
search(query, opts, done, config)
Search a user's account.
-
Provides a simple way of finding items that are accessible in a given user’s Box account.
Parameters:
Name Type Argument Description query
string The search keyword. opts
OptsSearch <nullable>
Additional search options. done
requestCallback The callback to invoke (with possible errors) when the request returns. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
setConcurrency(concurrency)
Set the maximum concurrent requests that this connection will process.
-
A connection starts with a default concurrency of
7
. Note that long-polling will consume a request from the request pool, so it is generally not a good idea to set this to less than2
.Parameters:
Name Type Description concurrency
number The number of concurrent requests. - Source:
Throws:
-
Concurrency must be an integer >
0
. - Type
- RangeError
-
startLongPolling()
-
Start long-polling for events.
Fires:
-
stopLongPolling()
-
Stop a running long-polling process.
-
updateFile(id, fields, done, headers, config)
Update a file’s information.
-
Used to update individual or multiple fields in the file object, including renaming the file, changing it’s description, and creating a shared link for the file. To move a file, change the ID of its parent folder. An optional
header[If-Match]
header can be included to ensure that client only updates the file if it knows about the latest version.Parameters:
Name Type Argument Description id
number The file's ID. fields
external:FieldsUpdateFile The fields to update. done
requestCallback The callback to invoke (with possible errors) when the request returns. headers
RequestHeaders <optional>
<nullable>
Additional headers. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
updateFolder(id, fields, done, headers, config)
Update Information About a Folder.
-
Used to update information about the folder. To move a folder, update the ID of its parent. To enable an email address that can be used to upload files to this folder, update the
fields.folder_upload_email
attribute. An optionalheader[If-Match]
header can be included to ensure that client only updates the folder if it knows about the latest version.Parameters:
Name Type Argument Description id
number The folder's ID. fields
external:FieldsUpdateFolder The fields to update. done
requestCallback The callback to invoke (with possible errors) when the request returns. headers
RequestHeaders <optional>
<nullable>
Additional headers. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
uploadFile(name, parent_id, opts, done, headers, config)
Upload a File.
-
Use the Uploads API to allow users to add a new file. The user can then upload a file by specifying the destination folder for the file. If the user provides a file name that already exists in the destination folder, the user will receive an error. You can optionally specify a
header[Content-MD5]
header with the SHA1 hash of the file to ensure that the file is not corrupted in transit.Parameters:
Name Type Argument Description name
string The fully qualified path to the local file. parent_id
number The parent folder's ID. opts
OptsUploadFile <nullable>
Request options. done
requestCallback The callback to invoke (with possible errors) when the request returns. headers
RequestHeaders <optional>
<nullable>
Additional headers. config
RequestConfig <optional>
<nullable>
Configure the request behaviour. -
uploadFileNewVersion(name, id, opts, done, headers, config)
Upload a New Version of a File.
-
This method is used to upload a new version of an existing file in a user’s account. An optional
header[If-Match]
header can be included to ensure that client only overwrites the file if it knows about the latest version. The filename on Box will remain the same as the previous version.Parameters:
Name Type Argument Description name
string The fully qualified path to the local file. id
number The file's ID. opts
OptsUploadFileNewVersion <nullable>
Request options. done
requestCallback The callback to invoke (with possible errors) when the request returns. headers
RequestHeaders <optional>
<nullable>
Additional headers. config
RequestConfig <optional>
<nullable>
Configure the request behaviour.
Events
-
"polling.end"
-
Fires when a running long-polling process ends.
- Source:
- See:
-
"polling.error"
-
Fires when an error occurs during long-polling.
Type:
- Error
- Source:
- See:
-
"polling.event.EVENT"
-
Fires when an event is read from the event stream during long-polling.
Type:
- Source:
-
"polling.ready"
-
Fires when a stream position has been fixed. All events from here onwards will be captured.
- Source:
-
"tokens.error"
-
Fires when an error occurs while setting access tokens have been set on this connection. Could be triggered more than once, so listeners must deregister after receiving the first event. Preferably use the
Connection#ready
method.Type:
- Error
- Source:
- See:
-
"tokens.set"
-
Fires when access tokens have been set on this connection. Could be triggered more than once, so listeners must deregister after receiving the first event. Preferably use the
Connection#ready
method.Type:
- Source:
- See: