box-node-sdk 1.9.0 → 1.12.0

package/lib/managers/files.js

@@ -3,6 +3,14 @@
  */
 
 'use strict';
+// -----------------------------------------------------------------------------
+// Typedefs
+// -----------------------------------------------------------------------------
+
+/**
+ * A representation request type constant
+ * @typedef {string} FileRepresentationType Different representations we can request from reps endpoint
+ */
 
 // -----------------------------------------------------------------------------
 // Requirements
@@ -46,18 +54,23 @@ var lockTypes = {
  * Returns the multipart form value for file upload metadata.
  * @param {string} parentFolderID - the ID of the parent folder to upload to
  * @param {string} filename - the file name that the uploaded file should have
+ * @param {Object} [options] - Optional metadata
  * @returns {Object} - the form value expected by the API for the 'metadata' key
  * @private
  */
-function createFileMetadataFormData(parentFolderID, filename) {
+function createFileMetadataFormData(parentFolderID, filename, options) {
 	// Although the filename and parent folder ID can be specified without using a
 	// metadata form field, Platform has recommended that we use the metadata form
 	// field to specify these parameters (one benefit is that UTF-8 characters can
 	// be specified in the filename).
-	return JSON.stringify({
+	var metadata = {
 		name: filename,
 		parent: { id: parentFolderID }
-	});
+	};
+
+	Object.assign(metadata, options);
+
+	return JSON.stringify(metadata);
 }
 
 /**
@@ -145,11 +158,11 @@ Files.prototype.getDownloadURL = function(fileID, qs, callback) {
 			case httpStatusCodes.FOUND:
 				return response.headers.location;
 
-			// 202 - Download isn't ready yet.
+				// 202 - Download isn't ready yet.
 			case httpStatusCodes.ACCEPTED:
 				throw errors.buildResponseError(response, 'Download not ready at this time');
 
-			// Unexpected Response
+				// Unexpected Response
 			default:
 				throw errors.buildUnexpectedResponseError(response);
 			}
@@ -176,7 +189,7 @@ Files.prototype.getReadStream = function(fileID, qs, callback) {
 	// Get the download URL to download from
 	return this.getDownloadURL(fileID, qs)
 		// Return a read stream to download the file
-		.then(url => this.client.get(url, {streaming: true}))
+		.then(url => this.client.get(url, { streaming: true }))
 		.asCallback(callback);
 };
 
@@ -219,15 +232,15 @@ Files.prototype.getThumbnail = function(fileID, qs, callback) {
 					location: response.headers.location
 				};
 
-			// 200 - Thumbnail image recieved
-			// return the thumbnail file
+				// 200 - Thumbnail image recieved
+				// return the thumbnail file
 			case httpStatusCodes.OK:
 				return {
 					statusCode: response.statusCode,
 					file: response.body
 				};
 
-			// Unexpected Response
+				// Unexpected Response
 			default:
 				throw errors.buildUnexpectedResponseError(response);
 			}
@@ -288,20 +301,20 @@ Files.prototype.update = function(fileID, options, callback) {
  */
 Files.prototype.addToCollection = function(fileID, collectionID, callback) {
 
-	return this.get(fileID, {fields: 'collections'})
+	return this.get(fileID, { fields: 'collections' })
 		.then(data => {
 
 			var collections = data.collections || [];
 
 			// Convert to correct format
-			collections = collections.map(c => ({id: c.id}));
+			collections = collections.map(c => ({ id: c.id }));
 
 			if (!collections.find(c => c.id === collectionID)) {
 
-				collections.push({id: collectionID});
+				collections.push({ id: collectionID });
 			}
 
-			return this.update(fileID, {collections});
+			return this.update(fileID, { collections });
 		})
 		.asCallback(callback);
 };
@@ -319,14 +332,14 @@ Files.prototype.addToCollection = function(fileID, collectionID, callback) {
  */
 Files.prototype.removeFromCollection = function(fileID, collectionID, callback) {
 
-	return this.get(fileID, {fields: 'collections'})
+	return this.get(fileID, { fields: 'collections' })
 		.then(data => {
 
 			var collections = data.collections || [];
 			// Convert to correct object format and remove the specified collection
-			collections = collections.map(c => ({id: c.id})).filter(c => c.id !== collectionID);
+			collections = collections.map(c => ({ id: c.id })).filter(c => c.id !== collectionID);
 
-			return this.update(fileID, {collections});
+			return this.update(fileID, { collections });
 		})
 		.asCallback(callback);
 };
@@ -510,14 +523,24 @@ Files.prototype.promoteVersion = function(fileID, versionID, callback) {
  * @param {string} filename - the file name that the uploaded file should have
  * @param {string|Buffer|ReadStream} content - the content of the file. It can be a string, a Buffer, or a read stream
  * (like that returned by fs.createReadStream()).
+ * @param {Object} [options] - Optional parameters
+ * @param {string} [options.content_created_at] - RFC 3339 timestamp when the file was created
+ * @param {string} [options.content_modified_at] - RFC 3339 timestamp when the file was last modified
  * @param {Function} [callback] - called with data about the upload if successful, or an error if the
  * upload failed
  * @returns {Promise<Object>} A promise resolving to the uploaded file
  */
-Files.prototype.uploadFile = function(parentFolderID, filename, content, callback) {
+Files.prototype.uploadFile = function(parentFolderID, filename, content, options, callback) {
+
+	// Shuffle around optional parameter
+	if (typeof options === 'function') {
+		callback = options;
+		options = {};
+	}
+
 	var apiPath = urlPath(BASE_PATH, '/content'),
 		multipartFormData = {
-			attributes: createFileMetadataFormData(parentFolderID, filename),
+			attributes: createFileMetadataFormData(parentFolderID, filename, options),
 			content: createFileContentFormData(content)
 		};
 
@@ -534,16 +557,30 @@ Files.prototype.uploadFile = function(parentFolderID, filename, content, callbac
  * @param {string} fileID - the id of the file to upload a new version of
  * @param {string|Buffer|Stream} content - the content of the file. It can be a string, a Buffer, or a read stream
  * (like that returned by fs.createReadStream()).
+ * @param {Object} [options] - Optional parameters
+ * @param {string} [options.content_modified_at] - RFC 3339 timestamp when the file was last modified
+ * @param {string} [options.name] - A new name for the file
  * @param {Function} [callback] - called with data about the upload if successful, or an error if the
  * upload failed
  * @returns {Promise<Object>} A promise resolving to the uploaded file
  */
-Files.prototype.uploadNewFileVersion = function(fileID, content, callback) {
+Files.prototype.uploadNewFileVersion = function(fileID, content, options, callback) {
+
+	// Shuffle around optional parameter
+	if (typeof options === 'function') {
+		callback = options;
+		options = {};
+	}
+
 	var apiPath = urlPath(BASE_PATH, fileID, '/content'),
 		multipartFormData = {
 			content: createFileContentFormData(content)
 		};
 
+	if (options) {
+		multipartFormData.attributes = JSON.stringify(options);
+	}
+
 	return this.client.wrapWithDefaultHandler(this.client.upload)(apiPath, null, multipartFormData, callback);
 };
 
@@ -1105,7 +1142,7 @@ Files.prototype.commitUploadSession = function(sessionID, fileHash, options, cal
 					.then(() => {
 
 						// Ensure we don't have to fetch parts from the API again on retry
-						options = Object.assign({}, options, {parts: params.body.parts});
+						options = Object.assign({}, options, { parts: params.body.parts });
 						return this.commitUploadSession(sessionID, fileHash, options);
 					});
 			}
@@ -1242,6 +1279,61 @@ Files.prototype.getCollaborations = function(fileID, options, callback) {
 	return this.client.wrapWithDefaultHandler(this.client.get)(apiPath, params, callback);
 };
 
+/**
+ * Enum of valid x-rep- hint values for generating representation info
+ *
+ * @readonly
+ * @enum {FileRepresentationType}
+ */
+Files.prototype.representation = {
+	PDF: '[pdf]',
+	THUMBNAIL: '[jpg?dimensions=320x320]',
+	IMAGE_MEDIUM: '[jpg?dimensions=1024x1024][png?dimensions=1024x1024]',
+	IMAGE_LARGE: '[jpg?dimensions=2048x2048][png?dimensions=2048x2048]',
+	EXTRACTED_TEXT: '[extracted_text]'
+};
+/**
+ * Requests information for all representation objects generated for a specific Box file
+ *
+ * API Endpoint: '/files/:fileID?fields=representations'
+ * Method : GET
+ *
+ * @param {string} fileID - Box ID of the file being requested
+ * @param {client.files.representation} representationType - The x-rep-hints value the application should create a
+ *    representation for. This value can either come from FileRepresentationType enum or manually created
+ * @param {Function} [callback] - Passed an array of representaton objects if successful
+ * @returns {Promise<Object>} A promise resolving to the representation response objects
+*/
+Files.prototype.getRepresentationInfo = function(fileID, representationType, callback) {
+	var params = {
+		qs: {
+			fields: 'representations'
+		},
+		headers: {
+			'x-rep-hints': representationType
+		}
+	};
+	var apiPath = urlPath(BASE_PATH, fileID);
+
+	return this.client.get(apiPath, params)
+		.then(response => {
+			switch (response.statusCode) {
+			// 202 - A Box file representation will be generated, but is not ready yet
+			case httpStatusCodes.ACCEPTED:
+				throw errors.buildResponseError(response, 'Representation not ready at this time');
+
+			// 200 - A Boxfile representation generated successfully
+			// return the representation object
+			case httpStatusCodes.OK:
+				return response.body.representations;
+
+			// Unexpected Response
+			default:
+				throw errors.buildUnexpectedResponseError(response);
+			}
+		})
+		.asCallback(callback);
+};
 /**
  * @module box-node-sdk/lib/managers/files
  * @see {@Link Files}

package/lib/managers/metadata.js

@@ -165,6 +165,24 @@ Metadata.prototype = {
 			};
 
 		return this.client.wrapWithDefaultHandler(this.client.put)(apiPath, params, callback);
+	},
+
+	/**
+	 * Delete a metadata template from an enterprise.
+	 *
+	 * API Endpoint: '/metadata_templates/:scope/:template/schema'
+	 * Method: DELETE
+	 *
+	 * @param {string} scope - The scope of the template to delete
+	 * @param {string} template - The template to delete
+	 * @param {Function} [callback] - Passed empty response body if successful, err otherwise
+	 * @returns {Promise<void>} A promise resolving to nothing
+	 * @see {@link https://docs.box.com/reference#delete-metadata-schema}
+	 */
+	deleteTemplate: function(scope, template, callback) {
+
+		var apiPath = urlPath(BASE_PATH, scope, template, SCHEMA_SUBRESOURCE);
+		return this.client.wrapWithDefaultHandler(this.client.del)(apiPath, callback);
 	}
 };
 

package/lib/managers/search.js

@@ -23,9 +23,9 @@ var urlPath = require('../util/url-path'),
  * @property {Object} filters Key/value filters against individual metadata template properties
  */
 
- /** @typedef {string} SearchScope */
+/** @typedef {string} SearchScope */
 
- /** @typedef {string} SearchTrashContent */
+/** @typedef {string} SearchTrashContent */
 
 // -----------------------------------------------------------------------------
 // Private

package/lib/managers/terms-of-service.js

@@ -0,0 +1,307 @@
+/**
+ * @fileoverview Manager for the  Box Terms of Service Resource
+ */
+
+'use strict';
+// -----------------------------------------------------------------------------
+// Typedefs
+// -----------------------------------------------------------------------------
+
+/**
+ * Terms of service parameter constant
+ * @typedef {string} TermsOfServicesStatus Determines whether the terms of service created is currently enabled or disabled
+ * @typedef {string} TermsOfServicesType Determines whether the terms of service is for internal users or users outside of the enterprise
+ */
+
+// -----------------------------------------------------------------------------
+// Requirements
+// -----------------------------------------------------------------------------
+
+var urlPath = require('../util/url-path'),
+	/* eslint-disable no-unused-vars*/
+	Promise = require('bluebird'),
+	/* eslint-enable no-unused-vars*/
+	errors = require('../util/errors'),
+	httpStatusCodes = require('http-status');
+
+// -----------------------------------------------------------------------------
+// Private
+// -----------------------------------------------------------------------------
+
+// Base path for all terms of service endpoints
+var BASE_PATH = '/terms_of_services',
+	USER_STATUSES_PATH = '/terms_of_service_user_statuses';
+
+// ------------------------------------------------------------------------------
+// Public
+// ------------------------------------------------------------------------------
+
+/**
+ * Simple manager for interacting with all 'Terms of Services' and 'Terms of Service User Statuses' endpoints and actions.
+ *
+ * @param {BoxClient} client The Box API Client that is responsible for making calls to the API
+ * @constructor
+ */
+function TermsOfService(client) {
+	// Attach the client, for making API calls
+	this.client = client;
+}
+
+/**
+ * Enum value of scope of the custom terms of services set to either managed by an enterprise or enternal to an enterprise
+ *
+ * @readonly
+ * @enum {TermsOfServicesType}
+ */
+TermsOfService.prototype.type = {
+	MANAGED: 'managed',
+	EXTERNAL: 'external'
+};
+
+/**
+ * Enum value of status of the custom terms of services, either currently enabled or currently disabled
+ *
+ * @readonly
+ * @enum {TermsOfServicesStatus}
+ */
+TermsOfService.prototype.status = {
+	ENABLED: 'enabled',
+	DISABLED: 'disabled'
+};
+
+/**
+ * Creates a custom terms of services with user specified values
+ *
+ * API Endpoint: '/terms_of_services'
+ * Method: POST
+ *
+ * @param {TermsOfServicesType} termsOfServicesType - Determine if the custom terms of service is scoped internall or externally to an enterprise
+ * @param {TermsOfServicesStatus} termsOfServicesStatus - Determine if the custom terms of service is enabled or disabled
+ * @param {string} termsOfServicesText - Text field for message associated with custom terms of services
+ * @param {Function} [callback] - Passed the terms of services information if successful, error otherwise
+ * @returns {Promise<Object>} A promise resolving to the terms of services object
+ */
+TermsOfService.prototype.create = function(termsOfServicesType, termsOfServicesStatus, termsOfServicesText, callback) {
+	var params = {
+		body: {
+			status: termsOfServicesStatus,
+			tos_type: termsOfServicesType,
+			text: termsOfServicesText
+		}
+	};
+
+	var apiPath = urlPath(BASE_PATH);
+	return this.client.wrapWithDefaultHandler(this.client.post)(apiPath, params, callback);
+};
+
+/**
+ * Updates a custom terms of services with new specified values
+ *
+ * API Endpoint: '/terms_of_services/:termsOfServicesID'
+ * Method: PUT
+ *
+ * @param {string} termsOfServicesID - The id of the custom terms of services to update
+ * @param {Object} [options] - Additional options. Can be left null in most cases.
+ * @param {TermsOfServicesStatus} [options.status] - Determine if the custom terms of service is scoped internall or externally to an enterprise
+ * @param {string} [options.text] - Text field for message associated with custom terms of services
+ * @param {Function} [callback] - Passed the terms of services updated information if successful, error otherwise
+ * @returns {Promise<Object>} A promise resolving to the terms of services object
+ */
+TermsOfService.prototype.update = function(termsOfServicesID, options, callback) {
+	var params = {
+		body: options
+	};
+
+	var apiPath = urlPath(BASE_PATH, termsOfServicesID);
+	return this.client.wrapWithDefaultHandler(this.client.put)(apiPath, params, callback);
+};
+
+/**
+ * Gets a specific custom terms of services with specified ID
+ *
+ * API Endpoint: '/terms_of_services/:termsOfServicesID'
+ * Method: GET
+ *
+ * @param {string} termsOfServicesID - The id of the custom terms of services to retrieve
+ * @param {Object} [options] - Additional options. Can be left null in most cases.
+ * @param {string} [options.fields] - Comma-separated list of fields to return on the collaboration objects
+ * @param {Function} [callback] - Passed the terms of services information with specified ID if successful, error otherwise
+ * @returns {Promise<Object>} A promise resolving to the terms of services object
+ */
+TermsOfService.prototype.get = function(termsOfServicesID, options, callback) {
+	var params = {
+		qs: options
+	};
+
+	var apiPath = urlPath(BASE_PATH, termsOfServicesID);
+	return this.client.wrapWithDefaultHandler(this.client.get)(apiPath, params, callback);
+};
+
+/**
+ * Gets custom terms of services for the user's enterprise
+ *
+ * API Endpoint: '/terms_of_services'
+ * Method: GET
+ *
+ * @param {Object} [options] - Additional options. Can be left null in most cases.
+ * @param {TermsOfServiceType} [options.tos_type] - Optional, indicates whether the terms of service is set for external or managed under enterprise
+ * @param {string} [options.fields] - Comma-separated list of fields to return on the collaboration objects
+ * @param {Function} [callback] - Passed the terms of services information if successful, error otherwise
+ * @returns {Promise<Object>} A promise resolving to the terms of services object
+ */
+TermsOfService.prototype.getAll = function(options, callback) {
+	var params = {
+		qs: options
+	};
+
+	var apiPath = urlPath(BASE_PATH);
+	return this.client.wrapWithDefaultHandler(this.client.get)(apiPath, params, callback);
+};
+
+/**
+ * Accepts/rejects custom terms of services for the user
+ *
+ * API Endpoint: '/terms_of_service_user_statuses'
+ * Method: POST
+ *
+ * @param {string} termsOfServicesID - Terms of services ID to retrieve user statuses on
+ * @param {bool} isAccepted - Determines wehether the terms of services has been accepted or rejected
+ * @param {Object} [options] - Additional options. Can be left null in most cases.
+ * @param {string} [options.user_id] - Optional, user id to retrieve terms of service status on, default is current user
+ * @param {Function} [callback] - Passed the terms of service user status information if successful, error otherwise
+ * @returns {Promise<Object>} A promise resolving to the terms of service user status
+ */
+TermsOfService.prototype.createUserStatus = function(termsOfServicesID, isAccepted, options, callback) {
+	var params = {
+		body: {
+			tos: {
+				id: termsOfServicesID,
+				type: 'terms_of_service'
+			},
+			is_accepted: isAccepted
+		}
+	};
+
+	if (options && options.user_id) {
+		params.body.user = {id: options.user_id, type: 'user'};
+	}
+
+	var apiPath = urlPath(USER_STATUSES_PATH);
+	return this.client.wrapWithDefaultHandler(this.client.post)(apiPath, params, callback);
+};
+
+/**
+ * Gets a terms os service status given the terms of services id
+ *
+ * API Endpoint: '/terms_of_service_user_statuses'
+ * Method: GET
+ *
+ * @param {string} termsOfServicesID - The ID of the terms of services to retrieve status on
+ * @param {Object} [options] - Additional options. Can be left null in most cases
+ * @param {string} [options.user_id] - Optional, the id of the user to retrieve status of custom terms and service on
+ * @param {Function} [callback] - Passed the terms of service user status information if successful, error otherwise
+ * @returns {Promise<Object>} A promise resolving to the terms of service user status
+ */
+TermsOfService.prototype.getUserStatus = function(termsOfServicesID, options, callback) {
+	var params = {
+		qs: {
+			tos_id: termsOfServicesID
+		}
+	};
+
+	if (options) {
+		Object.assign(params.qs, options);
+	}
+
+	var apiPath = urlPath(USER_STATUSES_PATH);
+	return this.client.get(apiPath, params)
+		.then(response => {
+			if (response.statusCode !== 200) {
+				throw errors.buildUnexpectedResponseError(response);
+			}
+			return response.body.entries[0];
+		})
+		.asCallback(callback);
+};
+
+/**
+ * Accepts/rejects custom terms of services for the user
+ *
+ * API Endpoint: '/terms_of_service_user_statuses'
+ * Method: PUT
+ *
+ * @param {string} termsOfServiceUserStatusID - Terms of service user status object ID
+ * @param {bool} isAccepted - Determines wehether the terms of services has been accepted or rejected
+ * @param {Function} [callback] - Passed the terms of service user status updated information if successful, error otherwise
+ * @returns {Promise<Object>} A promise resolving to the updated terms of service user status
+ */
+TermsOfService.prototype.updateUserStatus = function(termsOfServiceUserStatusID, isAccepted, callback) {
+	var params = {
+		body: {
+			is_accepted: isAccepted
+		}
+	};
+
+	var apiPath = urlPath(USER_STATUSES_PATH, termsOfServiceUserStatusID);
+	return this.client.wrapWithDefaultHandler(this.client.put)(apiPath, params, callback);
+};
+
+/**
+ * Creates a user status for terms of service, if already exists then update existing user status for terms of service
+ *
+ * API Endpoint: '/terms_of_service_user_statuses'
+ * Method: POST/PUT
+ *
+ * @param {string} termsOfServicesID - Terms of services ID to retrieve user statuses on
+ * @param {bool} isAccepted - Determines wehether the terms of services has been accepted or rejected
+ * @param {Object} [options] - Additional options. Can be left null in most cases.
+ * @param {string} [options.user_id] - Optional, user id to retrieve terms of service status on, default is current user
+ * @param {Function} [callback] - Passed the terms of service user status information if successful, error otherwise
+ * @returns {Promise<Object>} A promise resolving to the terms of service user status
+ */
+TermsOfService.prototype.setUserStatus = function(termsOfServicesID, isAccepted, options, callback) {
+	var params = {
+		body: {
+			tos: {
+				id: termsOfServicesID,
+				type: 'terms_of_service'
+			},
+			is_accepted: isAccepted
+		}
+	};
+
+	if (options && options.user_id) {
+		params.body.user = {id: options.user_id, type: 'user'};
+	}
+
+	var apiPath = urlPath(USER_STATUSES_PATH);
+
+	return this.client.post(apiPath, params)
+		.then(response => {
+			switch (response.statusCode) {
+
+			// 200 - A user status has been successfully created on terms of service
+			// return the terms of service user status object
+			case httpStatusCodes.OK:
+				return response.body;
+
+				// 409 - Conflict
+				// Terms of Service already exists. Update the existing terms of service object
+			case httpStatusCodes.CONFLICT:
+				var getOptions = Object.assign({fields: 'id'}, options);
+				return this.getUserStatus(termsOfServicesID, getOptions)
+					.then(userStatus => this.updateUserStatus(userStatus.id, isAccepted));
+
+			default:
+				throw errors.buildUnexpectedResponseError(response);
+			}
+		})
+		.asCallback(callback);
+};
+
+/**
+ * @module box-node-sdk/lib/managers/terms-of-service
+ * @see {@Link TermsOfService}
+ */
+module.exports = TermsOfService;
+

package/lib/sessions/app-auth-session.js

@@ -116,7 +116,9 @@ AppAuthSession.prototype.revokeTokens = function(options) {
  * Exchange the client access token for one with lower scope
  * @param {string|string[]} scopes The scope(s) requested for the new token
  * @param {string} [resource] The absolute URL of an API resource to scope the new token to
- * @param {TokenRequestOptions} [options] - Sets optional behavior for the token grant
+ * @param {Object} [options] - Optional parameters
+ * @param {TokenRequestOptions} [options.tokenRequestOptions] - Sets optional behavior for the token grant
+ * @param {ActorParams} [options.actor] - Optional actor parameters for creating annotator tokens
  * @returns {Promise<TokenInfo>} Promise resolving to the new token info
  */
 AppAuthSession.prototype.exchangeToken = function(scopes, resource, options) {

package/lib/sessions/basic-session.js

@@ -57,7 +57,9 @@ BasicSession.prototype.revokeTokens = function(options) {
  * Exchange the client access token for one with lower scope
  * @param {string|string[]} scopes The scope(s) requested for the new token
  * @param {string} [resource] The absolute URL of an API resource to scope the new token to
- * @param {TokenRequestOptions} [options] - Sets optional behavior for the token grant
+ * @param {Object} [options] - Optional parameters
+ * @param {TokenRequestOptions} [options.tokenRequestOptions] - Sets optional behavior for the token grant
+ * @param {ActorParams} [options.actor] - Optional actor parameters for creating annotator tokens
  * @returns {Promise<TokenInfo>} Promise resolving to the new token info
  */
 BasicSession.prototype.exchangeToken = function(scopes, resource, options) {

package/lib/sessions/persistent-session.js

@@ -217,7 +217,8 @@ PersistentSession.prototype.revokeTokens = function(options) {
  * Exchange the client access token for one with lower scope
  * @param {string|string[]} scopes The scope(s) requested for the new token
  * @param {string} [resource] The absolute URL of an API resource to scope the new token to
- * @param {TokenRequestOptions} [options] - Sets optional behavior for the token grant
+ * @param {Object} [options] - Optional parameters
+ * @param {TokenRequestOptions} [options.tokenRequestOptions] - Sets optional behavior for the token grant
  * @returns {void}
  */
 PersistentSession.prototype.exchangeToken = function(scopes, resource, options) {