box-view v2.0.0
Box View API Node Client
A node client for the Box View API
Installation
npm install box-view
Usage
Create a client:
var myKey = process.env.BOX_VIEW_API_TOKEN;
var client = require('box-view').createClient(myKey);
See the Box View API Documentation for a list of available endpoints and their parameters.
Documents
list
client.documents.list(options, callback)
Fetch a list of documents uploaded using this API key.
[options]
- (object
) An optional set of options for the request[options.params]
- (object
) An optional map of URL parameters for filtering documents[options.params.limit]
- (int
) The number of documents to return (default: 10, max: 50)[options.params.created_before]
- (Date
) An upper limit on the creation timestamps of documents returned (default: now)[options.params.created_after]
- (Date
) A lower limit on the creation timestamps of documents returned[options.retry]
- (boolean
) Whether to retry the request afterretry-after
seconds if the retry-after header is sent (default:false
)
[callback]
- (Function
) A callback to call with the following arguments:- an error object or
null
- JSON-parsed response data
- the http response object
- an error object or
Example:
client.documents.list(function (err, list, res) {
// `list` is the JSON-parsed response body
// `res` is the HTTP Response object
console.log(list);
});
get
client.documents.get(id, options, callback)
Fetch the metadata for a single document.
id
- (string
) The document uuid[options]
- (object
) An optional set of options for the request[options.fields]
- (Array
orstring
) An optional array or comma-separated list of fields to return (e.g.,['name', 'status']
or'name,status'
); id and type are always returned[options.retry]
- (boolean
) Whether to retry the request afterretry-after
seconds if the retry-after header is sent (default:false
)
[callback]
- (Function
) A callback to call with the following arguments:- an error object or
null
- JSON-parsed response data
- the http response object
- an error object or
Example:
client.documents.get('some document id', function (err, doc, res) {
// `doc` is the JSON-parsed response body
// `res` is the HTTP Response object
console.log(doc);
});
update
client.documents.update(id, data, options, callback)
Update the metadata for a single document.
id
- (string
) The document uuiddata
- (object
) The new metadata (currently onlyname
is supported)[options]
- (object
) An optional set of options for the request[options.retry]
- (boolean
) Whether to retry the request afterretry-after
seconds if the retry-after header is sent (default:false
)
[callback]
- (Function
) A callback to call with the following arguments:- an error object or
null
- JSON-parsed response data
- the http response object
- an error object or
delete (documents)
client.documents.delete(id, options, callback)
Delete a single document.
id
- (string
) The document uuid[options]
- (object
) An optional set of options for the request[options.retry]
- (boolean
) Whether to retry the request afterretry-after
seconds if the retry-after header is sent (default:false
)
[callback]
- (Function
) A callback to call with the following arguments:- an error object or
null
- JSON-parsed body if error
- the http response object if error
- an error object or
uploadFile
client.documents.uploadFile(file, options, callback)
Do a multipart upload.
NOTE: the retry
option is not supported for multipart uploads (uploads specified via string filename or Stream.
file
- (string
orstream.Readable
orFile
orBuffer
) A path to a file to read, a readable stream, a File object (e.g., in a browser), or a Buffer[options]
- (object
) An optional set of options for the request[options.params]
- (object
) An optional map of upload parameters[options.params.name]
- (string
) The name of the file. Ifoptions.params.name
is not set, it will be inferred from the file path.[options.params.thumbnails]
- (string
) Comma-separated list of thumbnail dimensions of the format{width}x{height}
(e.g.'128×128,256×256'
) – width can be between 16 and 1024, height between 16 and 768[options.params.non_svg]
- (boolean
) Whether to also create the non-svg version of the document[options.retry]
- (boolean
) Whether to retry the request afterretry-after
seconds if the retry-after header is sent (default:false
). See above note about retry support for streams.
[callback]
- (Function
) A callback to call with the following arguments:- an error object or
null
- JSON-parsed response data
- the http response object
- an error object or
uploadURL
client.documents.uploadURL(url, options, callback)
Do a URL upload of a file.
[url]
- (string
) A URL to a publicly-accessible file to upload[options]
- (object
) An optional set of options for the request[options.params]
- (object
) An optional map of upload parameters[options.params.name]
- (string
) The name of the file. Ifoptions.params.name
is not set, it will be inferred from the URL.[options.params.thumbnails]
- (string
) Comma-separated list of thumbnail dimensions of the format{width}x{height}
(e.g.'128×128,256×256'
) – width can be between 16 and 1024, height between 16 and 768[options.params.non_svg]
- (boolean
) Whether to also create the non-svg version of the document[options.retry]
- (boolean
) Whether to retry the request afterretry-after
seconds if the retry-after header is sent (default:false
)
[callback]
- (Function
) A callback to call with the following arguments:- an error object or
null
- JSON-parsed response data
- the http response object
- an error object or
getContent
client.documents.getContent(id, options, callback)
Fetch a document of a specified format.
- If an extension is not specified, the document's original format is returned.
id
- (string
) The document uuid[options]
- (object
) An optional set of options for the request[options.extension]
- (string
) Optional document format to request ('pdf'
or'zip'
). If excluded, the original document format will be returned.[options.retry]
- (boolean
) Whether to retry the request afterretry-after
seconds if the retry-after header is sent (default:false
)
[callback]
- (Function
) A callback to call with the following arguments:- an error object or
null
- the http response object (or JSON-parsed body if error)
- the http response object if error
- an error object or
Example:
client.documents.getContent(id, { extension: 'zip' }, function (err, res) {
if (err) {
console.error(err);
return;
}
// `res` is the HTTP Response object
res.pipe(fs.createWriteStream('./doc.zip'));
});
getThumbnail
client.documents.getThumbnail(id, width, height, options, callback)
Fetch a thumbnail for the given document id.
id
- (string
) The document uuidwidth
- (int
) The thumbnail widthheight
- (int
) The thumbnail height[options]
- (object
) An optional set of options for the request[options.retry]
- (boolean
) Whether to retry the request afterretry-after
seconds if the retry-after header is sent (default:false
)
[callback]
- (Function
) A callback to call with the following arguments:- an error object or
null
- the http response object (or JSON-parsed body if error)
- the http response object if error
- an error object or
Example:
client.documents.getThumbnail(id, params, function (err, res) {
if (err) {
console.error(err);
return;
}
// `res` is the HTTP Response object
res.pipe(fs.createWriteStream('./thumbnail.png'));
});
Sessions
create
client.sessions.create(id, options, callback)
Request a viewing session for a document.
[id]
- (string
) The document uuid[options]
- (object
) An optional set of options for the request[options.params]
- (object
) An optional map of session parameters[options.params.duration]
- (int
) The duration in minutes until the session expires (default: 60)[options.params.expires_at]
- (Date
) The timestamp at which the session should expire[options.params.is_downloadable]
- (boolean
) Whether the original file will be available for download via GET /sessions/{id}/content while the session is active[options.retry]
- (boolean
) Whether to retry the request afterretry-after
seconds if the retry-after header is sent (default:false
)
[callback]
- (Function
) A callback to call with the following arguments:- an error object or
null
- JSON-parsed response data
- the http response object
- an error object or
delete (sessions)
client.sessions.delete(id, options, callback)
Delete a single session.
id
- (string
) The session uuid[options]
- (object
) An optional set of options for the request[options.retry]
- (boolean
) Whether to retry the request afterretry-after
seconds if the retry-after header is sent (default:false
)
[callback]
- (Function
) A callback to call with the following arguments:- an error object or
null
- JSON-parsed body if error
- the http response object if error
- an error object or
Running Tests
Make sure you have the development dependencies installed by running npm install
, then you should be able to run the tests with npm test
.
API Support
For any bugs or feedback with conversion or the API in general, please email api@box.com.
License
Copyright 2014 Cameron Lakenen
9 years ago
9 years ago
9 years ago
9 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago