box-node-sdk 1.26.1 → 1.29.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.29.0 [2019-04-25]
+
+- Added convenience methods for setting metadata on [files](./docs/metadata.md#set-metadata-on-a-file)
+  and [folders](./docs/metadata.md#set-metadata-on-a-folder) ([#376](https://github.com/box/box-node-sdk/pull/376))
+
+## 1.28.0 [2019-03-28]
+
+- Added methods for [moving](./docs/web-links.md#move-a-web-link) and [copying](./docs/web-links.md#move-a-web-link)
+  weblinks, as well as [adding or removing from a collection](./docs/web-links.md#add-web-link-to-a-collection)
+
+## 1.27.0 [2019-02-28]
+
+- Added the trace ID from API response headers to error messages for easier debugging
+- Added more safety checks in the error flow to protect against throwing when handling a malformed request
+- Added support for [retrieving a user's avatar image](./docs/users.md#get-user-avatar)
+
+## 1.26.2 [2019-02-22]
+
+- Fixed an error where under high request rates, code in the error handling logic could throw when handling a
+  malformed request
+
 ## 1.26.1 [2019-02-12]
 
 - Fixed an error where some methods could throw an error when constructing an iterator

package/lib/api-request.js

@@ -339,7 +339,12 @@ APIRequest.prototype._retry = function(err) {
 APIRequest.prototype._finish = function(err, response) {
 	var callback = this._callback;
 	process.nextTick(() => {
-		callback(err, response);
+		if (err) {
+			callback(err);
+			return;
+		}
+
+		callback(null, response);
 	});
 };
 

package/lib/managers/files.js

@@ -743,6 +743,37 @@ Files.prototype.updateMetadata = function(fileID, scope, template, patch, callba
 	return this.client.wrapWithDefaultHandler(this.client.put)(apiPath, params, callback);
 };
 
+/**
+ * Sets metadata on a file, overwriting any metadata that exists for the provided keys.
+ *
+ * @param {string} fileID - The file to set metadata on
+ * @param {string} scope - The scope of the metadata template
+ * @param {string} template - The key of the metadata template
+ * @param {Object} metadata - The metadata to set
+ * @param {Function} [callback] - Called with updated metadata if successful
+ * @returns {Promise<Object>} A promise resolving to the updated metadata
+ */
+Files.prototype.setMetadata = function(fileID, scope, template, metadata, callback) {
+
+	return this.addMetadata(fileID, scope, template, metadata)
+		.catch(err => {
+
+			if (err.statusCode !== 409) {
+				throw err;
+			}
+
+			// Metadata already exists on the file; update instead
+			var updates = Object.keys(metadata).map(key => ({
+				op: 'add',
+				path: `/${key}`,
+				value: metadata[key],
+			}));
+
+			return this.updateMetadata(fileID, scope, template, updates);
+		})
+		.asCallback(callback);
+};
+
 /**
  * Deletes a metadata template from a file.
  *

package/lib/managers/folders.js

@@ -368,6 +368,37 @@ Folders.prototype.updateMetadata = function(folderID, scope, template, patch, ca
 	return this.client.wrapWithDefaultHandler(this.client.put)(apiPath, params, callback);
 };
 
+/**
+ * Sets metadata on a folder, overwriting any metadata that exists for the provided keys.
+ *
+ * @param {string} folderID - The folder to set metadata on
+ * @param {string} scope - The scope of the metadata template
+ * @param {string} template - The key of the metadata template
+ * @param {Object} metadata - The metadata to set
+ * @param {Function} [callback] - Called with updated metadata if successful
+ * @returns {Promise<Object>} A promise resolving to the updated metadata
+ */
+Folders.prototype.setMetadata = function(folderID, scope, template, metadata, callback) {
+
+	return this.addMetadata(folderID, scope, template, metadata)
+		.catch(err => {
+
+			if (err.statusCode !== 409) {
+				throw err;
+			}
+
+			// Metadata already exists on the file; update instead
+			var updates = Object.keys(metadata).map(key => ({
+				op: 'add',
+				path: `/${key}`,
+				value: metadata[key],
+			}));
+
+			return this.updateMetadata(folderID, scope, template, updates);
+		})
+		.asCallback(callback);
+};
+
 /**
  * Deletes a metadata template from a folder.
  *

package/lib/managers/search.js

@@ -78,6 +78,8 @@ Search.prototype = {
 	 * @param {SearchMetadataFilter[]} [options.mdfilters] - Searches for objects with a specific metadata object association.  Searches with the this parameter do not require a query string
 	 * @param {int} [options.limit=30] - The number of search results to return, max 200
 	 * @param {int} [options.offset=0] - The search result at which to start the response, must be a multiple of limit
+	 * @param {string} [options.sort] - The field on which the results should be sorted, e.g. "modified_at"
+	 * @param {string} [options.direction] - The sort direction: "ASC" for ascending and "DESC" for descending
 	 * @param {APIRequest~Callback} [callback] - passed the new comment data if it was posted successfully
 	 * @returns {Promise<Object>} A promise resolving to the collection of search results
 	 */

package/lib/managers/users.js

@@ -189,6 +189,27 @@ Users.prototype.getGroupMemberships = function(userID, options, callback) {
 	return this.client.wrapWithDefaultHandler(this.client.get)(apiPath, params, callback);
 };
 
+/**
+ * Retrieve the user's avatar image.
+ *
+ * API Endpoint: '/users/:userID/avatar'
+ * Method: GET
+ *
+ * @param {string} userID The ID of the user whose avatar should be retrieved
+ * @param {Function} [callback] Passed a stream over the bytes of the avatar image if successful
+ * @returns {Promise<Readable>} A promise resolving to the image stream
+ */
+Users.prototype.getAvatar = function(userID, callback) {
+
+	var apiPath = urlPath(BASE_PATH, userID, 'avatar'),
+		params = {
+			streaming: true
+		};
+
+	return this.client.get(apiPath, params)
+		.asCallback(callback);
+};
+
 // @NOTE(fschott) 2014-05-06: Still need to implement get, edit, create, etc.
 //  The problem is that they are only available to enterprise admins, so we'll
 //  first need to figure out how we want to handle access to those methods.

package/lib/managers/web-links.js

@@ -89,7 +89,7 @@ WebLinks.prototype.get = function(weblinkID, options, callback) {
  * @param {Object} updates - Fields of the weblink to update
  * @param {string} [updates.name] - Name for the web link. Will default to the URL if empty.
  * @param {string} [updates.description] - Description of the web link. Will provide more context to users about the web link.
- * @param {Function} [callback] - Passed the updated web-link information if it was acquired successfully, error otherwise
+ * @param {Function} [callback] - Passed the updated web link information if it was acquired successfully, error otherwise
  * @returns {Promise<Object>} A promise resolving to the updated web link object
  */
 WebLinks.prototype.update = function(weblinkID, updates, callback) {
@@ -117,4 +117,111 @@ WebLinks.prototype.delete = function(weblinkID, callback) {
 	return this.client.wrapWithDefaultHandler(this.client.del)(apiPath, null, callback);
 };
 
+/**
+ * Move a web link into a new parent folder.
+ *
+ * API Endpoint: '/web_links/:webLinkID'
+ * Method: PUT
+ *
+ * @param {string} webLinkID - The Box ID of the web link being requested
+ * @param {string} newParentID - The Box ID for the new parent folder. '0' to move to All Files.
+ * @param {Function} [callback] - Passed the updated web link information if it was acquired successfully
+ * @returns {Promise<Object>} A promise resolving to the updated web link object
+ */
+WebLinks.prototype.move = function(webLinkID, newParentID, callback) {
+	var params = {
+		body: {
+			parent: {
+				id: newParentID
+			}
+		}
+	};
+	var apiPath = urlPath(BASE_PATH, webLinkID);
+	return this.client.wrapWithDefaultHandler(this.client.put)(apiPath, params, callback);
+};
+
+/**
+ * Copy a web link into a new, different folder
+ *
+ * API Endpoint: '/web_links/:webLinkID/copy
+ * Method: POST
+ *
+ * @param {string} webLinkID - The Box ID of the web link being requested
+ * @param {string} newParentID - The Box ID for the new parent folder. '0' to copy to All Files.
+ * @param {Object} [options] - Optional parameters for the copy operation, can be left null in most cases
+ * @param {string} [options.name] - A new name to use if there is an identically-named item in the new parent folder
+ * @param {Function} [callback] - passed the new web link info if call was successful
+ * @returns {Promise<Object>} A promise resolving to the new web link object
+ */
+WebLinks.prototype.copy = function(webLinkID, newParentID, options, callback) {
+
+	options = options || {};
+
+	options.parent = {
+		id: newParentID
+	};
+
+	var params = {
+		body: options
+	};
+	var apiPath = urlPath(BASE_PATH, webLinkID, '/copy');
+	return this.client.wrapWithDefaultHandler(this.client.post)(apiPath, params, callback);
+};
+
+/**
+ * Add a web link to a given collection
+ *
+ * API Endpoint: '/web_links/:webLinkID'
+ * Method: PUT
+ *
+ * @param {string} webLinkID - The web link to add to the collection
+ * @param {string} collectionID - The collection to add the web link to
+ * @param {Function} [callback] - Passed the updated web link if successful, error otherwise
+ * @returns {Promise<Object>} A promise resolving to the updated web link object
+ */
+WebLinks.prototype.addToCollection = function(webLinkID, collectionID, callback) {
+
+	return this.get(webLinkID, {fields: 'collections'})
+		.then(data => {
+
+			var collections = data.collections || [];
+
+			// Convert to correct format
+			collections = collections.map(c => ({id: c.id}));
+
+			if (!collections.find(c => c.id === collectionID)) {
+
+				collections.push({id: collectionID});
+			}
+
+			return this.update(webLinkID, {collections});
+		})
+		.asCallback(callback);
+};
+
+/**
+ * Remove a web link from a given collection
+ *
+ * API Endpoint: '/web_links/:webLinkID'
+ * Method: PUT
+ *
+ * @param {string} webLinkID - The web link to remove from the collection
+ * @param {string} collectionID - The collection to remove the web link from
+ * @param {Function} [callback] - Passed the updated web link if successful, error otherwise
+ * @returns {Promise<Object>} A promise resolving to the updated web link object
+ */
+WebLinks.prototype.removeFromCollection = function(webLinkID, collectionID, callback) {
+
+	return this.get(webLinkID, {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);
+
+			return this.update(webLinkID, {collections});
+		})
+		.asCallback(callback);
+};
+
 module.exports = WebLinks;

package/lib/util/errors.js

@@ -10,6 +10,7 @@
 var qs = require('querystring'),
 	httpStatusCodes = require('http-status');
 
+const TRACE_ID_HEADER_NAME = 'box-request-id';
 
 // ------------------------------------------------------------------------------
 // Typedefs and Callbacks
@@ -37,14 +38,18 @@ var qs = require('querystring'),
  */
 function Request(req) {
 	this.method = req.method;
-	this.url = {
-		protocol: req.uri.protocol,
-		host: req.uri.host,
-		path: req.uri.pathname,
-		query: qs.parse(req.uri.query),
-		fragment: req.uri.hash
-	};
-	this.httpVersion = req.response.httpVersion;
+	if (req.uri) {
+		this.url = {
+			protocol: req.uri.protocol,
+			host: req.uri.host,
+			path: req.uri.pathname,
+			query: qs.parse(req.uri.query),
+			fragment: req.uri.hash
+		};
+	} else {
+		this.url = null;
+	}
+	this.httpVersion = req.response ? req.response.httpVersion : null;
 	this.headers = req.headers;
 	this.body = req.body;
 }
@@ -76,23 +81,42 @@ module.exports = {
 		message = message || 'API Response Error';
 
 		var statusCode = response.statusCode;
-		var requestID = '';
-		if (response.body && response.body.request_id) {
-			requestID = ` | ${response.body.request_id}`;
+		var statusMessage = httpStatusCodes[statusCode];
+		var debugID = ''; // Of the form <requestID>.<traceID>, both parts optional
+		var errorCode;
+		var errorDescription;
+
+		if (response.headers && response.headers[TRACE_ID_HEADER_NAME]) {
+			// Append trace ID with dot separator — if not present, the dot should be omitted
+			debugID += `.${response.headers[TRACE_ID_HEADER_NAME]}`;
 		}
 
-		var apiMessage = '';
 
 		if (response.body) {
 
-			var code = response.body.code || response.body.error;
-			var description = response.body.message || response.body.error_description;
+			if (response.body.request_id) {
+				// Prepend request ID
+				debugID = response.body.request_id + debugID;
+			}
+
+			errorCode = response.body.code || response.body.error;
+			errorDescription = response.body.message || response.body.error_description;
+		}
+
+		var errorMessage;
+		if (debugID) {
+			errorMessage = `${message} [${statusCode} ${statusMessage} | ${debugID}]`;
+		} else {
+			errorMessage = `${message} [${statusCode} ${statusMessage}]`;
+		}
 
-			apiMessage += code ? ` ${code}` : '';
-			apiMessage += description ? ` - ${description}` : '';
+		if (errorCode) {
+			errorMessage += ` ${errorCode}`;
+		}
+		if (errorDescription) {
+			errorMessage += ` - ${errorDescription}`;
 		}
 
-		var errorMessage = `${message} [${statusCode} ${httpStatusCodes[statusCode]}${requestID}]${apiMessage}`;
 		var responseError = new Error(errorMessage);
 
 		responseError.statusCode = response.statusCode;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "box-node-sdk",
   "author": "Box <oss@box.com>",
-  "version": "1.26.1",
+  "version": "1.29.0",
   "description": "Official SDK for Box Plaform APIs",
   "license": "Apache-2.0",
   "repository": {
@@ -58,7 +58,7 @@
     "nyc": "^11.4.1",
     "shelljs": "^0.8.1",
     "shelljs-nodecli": "^0.1.1",
-    "sinon": "^6.0.0"
+    "sinon": "^7.2.4"
   },
   "files": [
     "config",