'use strict';
var _ = require('lodash');
module.exports = function (Connection) {
Connection.addInstanceMethods(
/** @lends Connection.prototype */
{
/**
* 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″.
* @summary Get Information About a Folder.
* @see {@link https://developers.box.com/docs/#folders-get-information-about-a-folder}
* @param {number} id - The folder's ID.
* @param {requestCallback} done - The callback to invoke (with possible errors) when the request returns.
* @param {?RequestHeaders} [headers] - Additional headers.
* @param {?RequestConfig} [config] - Configure the request behaviour.
*/
getFolderInfo: function (id, done, headers, config) {
if (!_.isNumber(parseInt(id, 10))) {
return done(new Error('id must be specified.'));
}
this._request(['folders', id], 'GET', done, null, null, null, headers, null, config);
},
/**
* 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 {@linkcode 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.
* {@linkcode opts.fields=name,created_at}. Paginated results can be retrieved using the
* {@linkcode opts.limit} and {@linkcode opts.offset} parameters.
* @summary Retrieve a Folder’s Items.
* @see {@link https://developers.box.com/docs/#folders-retrieve-a-folders-items}
* @param {number} id - The folder's ID.
* @param {?external:OptsFLO} opts - Request options.
* @param {requestCallback} done - The callback to invoke (with possible errors) when the request returns.
* @param {?RequestConfig} [config] - Configure the request behaviour.
*/
getFolderItems: function (id, opts, done, config) {
if (!_.isNumber(parseInt(id, 10))) {
return done(new Error('id must be specified.'));
}
this._request(['folders', id, 'items'], 'GET', done, opts, null, null, null, null, config);
},
/**
* Used to create a new empty folder. The new folder will be created inside of the
* specified parent folder.
* @summary Create a New Folder.
* @see {@link https://developers.box.com/docs/#folders-create-a-new-folder}
* @param {string} name - The folder's name.
* @param {number} parent_id - The parent folder's ID.
* @param {requestCallback} done - The callback to invoke (with possible errors) when the request returns.
* @param {?RequestConfig} [config] - Configure the request behaviour.
*/
createFolder: function (name, parent_id, done, config) {
if (!_.isString(name) || !_.isNumber(parseInt(parent_id, 10))) {
return done(new Error('Invalid params. Required - name: string, parent_id: number'));
}
this._request(['folders'], 'POST', done, null, {
name: name,
parent: {
id: parent_id.toString()
}
}, null, null, null, config);
},
/**
* Fields to set for {@link Connection#updateFolder}.
* @external FieldsUpdateFolder
* @see {@link https://developers.box.com/docs/#folders-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
* {@linkcode fields.folder_upload_email} attribute. An optional {@linkcode header[If-Match]}
* header can be included to ensure that client only updates the folder if it knows about
* the latest version.
* @summary Update Information About a Folder.
* @see {@link https://developers.box.com/docs/#folders-update-information-about-a-folder}
* @param {number} id - The folder's ID.
* @param {external:FieldsUpdateFolder} fields - The fields to update.
* @param {requestCallback} done - The callback to invoke (with possible errors) when the request returns.
* @param {?RequestHeaders} [headers] - Additional headers.
* @param {?RequestConfig} [config] - Configure the request behaviour.
*/
updateFolder: function (id, fields, done, headers, config) {
if (!_.isNumber(parseInt(id, 10))) {
return done(new Error('id must be specified.'));
}
if (!_.isObject(fields)) {
return done(new Error('An fields object must be provided.'));
}
this._request(['folders', id], 'PUT', done, null, fields, null, headers, null, config);
},
/**
* Options to pass to {@link Connection#deleteFolder}.
* @external OptsDeleteFolder
* @see {@link https://developers.box.com/docs/#folders-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 {@linkcode header[If-Match]} header can be
* included to ensure that client only deletes the folder if it knows about the latest version.
* @summary Delete a Folder.
* @see {@link https://developers.box.com/docs/#folders-delete-a-folder}
* @param {number} id - The folder's ID.
* @param {?external:OptsDeleteFolder} opts - Options to control recursive delete.
* @param {requestCallback} done - The callback to invoke (with possible errors) when the request returns.
* @param {?RequestHeaders} [headers] - Additional headers.
* @param {?RequestConfig} [config] - Configure the request behaviour.
*/
deleteFolder: function (id, opts, done, headers, config) {
if (!_.isNumber(parseInt(id, 10))) {
return done(new Error('id must be specified.'));
}
this._request(['folders', id], 'DELETE', done, opts, null, null, headers, null, config);
},
/**
* Used to create a copy of a folder in another folder. The original version of the folder
* will not be altered.
* @summary Copy a Folder.
* @see {@link https://developers.box.com/docs/#folders-copy-a-folder}
* @param {number} id - The source folder's ID.
* @param {number} parent_id - The destination parent folder's ID.
* @param {?string} name - The destination folder's name.
* @param {requestCallback} done - The callback to invoke (with possible errors) when the request returns.
* @param {?RequestConfig} [config] - Configure the request behaviour.
*/
copyFolder: function (id, parent_id, name, done, config) {
if (!_.isNumber(parseInt(id, 10)) || !_.isNumber(parseInt(parent_id, 10))) {
return done(new Error('Invalid params. Required - id: number, parent_id: number'));
}
var opts = {
parent: {
id: parent_id.toString()
}
};
if (name) {
opts.name = name;
}
this._request(['folders', id, 'copy'], 'POST', done, null, opts, null, null, null, config);
},
/**
* Use this to get a list of all the
* {@link http://developers.box.com/docs/#collaborations|collaborations} on a folder
* i.e. all of the users that have access to that folder.
* @summary View a Folder’s Collaborations.
* @see {@link https://developers.box.com/docs/#folders-view-a-folders-collaborations}
* @param {number} id - The folder's ID.
* @param {requestCallback} done - The callback to invoke (with possible errors) when the request returns.
* @param {?RequestConfig} [config] - Configure the request behaviour.
*/
getFolderCollaborations: function (id, done, config) {
if (!_.isNumber(parseInt(id, 10))) {
return done(new Error('id must be specified.'));
}
this._request(['folders', id, 'collaborations'], 'GET', done, null, null, null, null, null, config);
},
/**
* Retrieves the files and/or folders that have been moved to the trash. Any attribute
* in the full {@link http://developers.box.com/docs/files/file-object-2/|files} or
* {@link http://developers.box.com/docs/folders/folder-object-2/|folders} objects can
* be passed in with the {@linkcode 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. {@linkcode opts.fields='name,created_at'}. Paginated results
* can be retrieved using the {@linkcode opts.limit} and {@linkcode opts.offset} parameters.
* @summary Get the Items in the Trash.
* @see {@link https://developers.box.com/docs/#folders-get-the-items-in-the-trash}
* @param {?external:OptsFLO} opts - Request options.
* @param {requestCallback} done - The callback to invoke (with possible errors) when the request returns.
* @param {?RequestConfig} [config] - Configure the request behaviour.
*/
getTrashedItems: function (opts, done, config) {
this._request(['folders', 'trash', 'items'], 'GET', done, opts, null, null, null, null, config);
},
/**
* Retrieves an item that has been moved to the trash.
* @summary Get a Trashed Folder.
* @see {@link https://developers.box.com/docs/#folders-get-a-trashed-folder}
* @param {number} id - The folder's ID.
* @param {requestCallback} done - The callback to invoke (with possible errors) when the request returns.
* @param {?RequestConfig} [config] - Configure the request behaviour.
*/
getTrashedFolder: function (id, done, config) {
if (!_.isNumber(parseInt(id, 10))) {
return done(new Error('id must be specified.'));
}
this._request(['folders', id, 'trash'], 'GET', done, null, null, null, null, null, config);
},
/**
* Permanently deletes an item that is in the trash. The item will no longer exist in Box.
* This action cannot be undone.
* @summary Permanently Delete a Trashed Folder.
* @see {@link https://developers.box.com/docs/#folders-permanently-delete-a-trashed-folder}
* @param {number} id - The folder's ID.
* @param {requestCallback} done - The callback to invoke (with possible errors) when the request returns.
* @param {?RequestConfig} [config] - Configure the request behaviour.
*/
deleteTrashedFolder: function (id, done, config) {
if (!_.isNumber(parseInt(id, 10))) {
return done(new Error('id must be specified.'));
}
this._request(['folders', id, 'trash'], 'DELETE', done, null, null, null, null, null, config);
},
/**
* 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.
* @summary Restore a Trashed Folder.
* @see {@link https://developers.box.com/docs/#folders-restore-a-trashed-folder}
* @param {number} id - The folder's ID.
* @param {?string} name - The folder's name.
* @param {?number} parent_id - The parent folder's ID.
* @param {requestCallback} done - The callback to invoke (with possible errors) when the request returns.
* @param {?RequestConfig} [config] - Configure the request behaviour.
*/
restoreTrashedFolder: function (id, name, parent_id, done, config) {
if ((name && !_.isString(name)) || (parent_id && !_.isNumber(parseInt(parent_id, 10)))) {
return done(new Error('Invalid params. Required - name: string, parent_id: number'));
}
var opts = {};
if (name) {
opts.name = name;
}
if (parent_id) {
opts.parent = {
id: parent_id.toString()
};
}
this._request(['folders', id], 'POST', done, null, opts, null, null, null, config);
}
});
};