box-node-sdk 1.28.0 → 1.29.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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)

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "box-node-sdk",
   "author": "Box <oss@box.com>",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "Official SDK for Box Plaform APIs",
   "license": "Apache-2.0",
   "repository": {