Add metadata query (#487)

Author: sujaygarlanka

CHANGELOG.md

@@ -2,7 +2,8 @@
 
 ## Next Release
 
-- Fixed an issue where an error is thrown during a retry when a response is not returned by the previous call (#476).
+- Fixed an issue where an error is thrown during a retry when a response is not returned by the previous call ([#476](https://github.com/box/box-node-sdk/pull/76)).
+- Added the ability to [query](./docs/metadata.md#query) Box items based on their metadata ([#487](https://github.com/box/box-node-sdk/pull/487)).
 
 ## 1.31.0 [2020-02-13]
 

docs/metadata.md

@@ -43,6 +43,7 @@ in a flexible way, without pre-defined template structure.
 - [Get All Cascade Policies For a Folder](#get-all-cascade-policies-for-a-folder)
 - [Force Apply Cascade Policy](#force-apply-cascade-policy)
 - [Delete Cascade Policy](#delete-cascade-policy)
+- [Query](#query)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -902,3 +903,138 @@ client.metadata.deleteCascadePolicy(policyID)
 ```
 
 [delete-cascade-policy]: http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#deleteCascadePolicy
+
+Query
+---------------------
+
+To query box items based on their metadata, call [`metadata.query(from, ancestorFolderId, options, callback)`][query] with the metadata template and the folder ID to restrain the query. Additional options like the a specific query, a marker, etc. can be passed in through the options object.
+
+```js
+var from = 'enterprise_12345.someTemplate',
+	ancestorFolderId = '5555',
+	options = {
+		query: 'amount >= :arg',
+		queryParams: {
+			arg: 100
+		},
+		useIndex: 'amountAsc',
+		orderBy: [
+			{
+				field_key: 'amount',
+				direction: 'asc'
+			}
+		],
+		limit: 100,
+		marker: 'AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff'
+	};
+client.metadata.query(from, ancestorFolderId, options)
+	.then(items => {
+		/* items -> {
+			"entries": [
+			{
+				"item": {
+					"type": "file",
+					"id": "1617554169109",
+					"file_version": {
+						"type": "file_version",
+						"id": "1451884469385",
+						"sha1": "69888bb1bff455d1b2f8afea75ed1ff0b4879bf6"
+					},
+					"sequence_id": "0",
+					"etag": "0",
+					"sha1": "69888bb1bff455d1b2f8afea75ed1ff0b4879bf6",
+					"name": "My Contract.docx",
+					"description": "",
+					"size": 25600,
+					"path_collection": {
+						"total_count": 4,
+						"entries": [
+						{
+							"type": "folder",
+							"id": "0",
+							"sequence_id": null,
+							"etag": null,
+							"name": "All Files"
+						},
+						{
+							"type": "folder",
+							"id": "15017998644",
+							"sequence_id": "0",
+							"etag": "0",
+							"name": "Contracts"
+						},
+						{
+							"type": "folder",
+							"id": "15286891196",
+							"sequence_id": "1",
+							"etag": "1",
+							"name": "North America"
+						},
+						{
+							"type": "folder",
+							"id": "16125613433",
+							"sequence_id": "0",
+							"etag": "0",
+							"name": "2017"
+						}
+						]
+					},
+					"created_at": "2017-04-20T12:55:27-07:00",
+					"modified_at": "2017-04-20T12:55:27-07:00",
+					"trashed_at": null,
+					"purged_at": null,
+					"content_created_at": "2017-01-06T17:59:01-08:00",
+					"content_modified_at": "2017-01-06T17:59:01-08:00",
+					"created_by": {
+						"type": "user",
+						"id": "193973366",
+						"name": "Box Admin",
+						"login": "admin@company.com"
+					},
+					"modified_by": {
+						"type": "user",
+						"id": "193973366",
+						"name": "Box Admin",
+						"login": "admin@company.com"
+					},
+					"owned_by": {
+						"type": "user",
+						"id": "193973366",
+						"name": "Box Admin",
+						"login": "admin@company.com"
+					},
+					"shared_link": null,
+					"parent": {
+						"type": "folder",
+						"id": "16125613433",
+						"sequence_id": "0",
+						"etag": "0",
+						"name": "2017"
+					},
+					"item_status": "active"
+				},
+				"metadata": {
+					"enterprise_123456": {
+						"someTemplate": {
+						"$parent": "file_161753469109",
+						"$version": 0,
+						"customerName": "Phoenix Corp",
+						"$type": "someTemplate-3d5fcaca-f496-4bb6-9046-d25c37bc5594",
+						"$typeVersion": 0,
+						"$id": "ba52e2cc-371d-4659-8d53-50f1ac642e35",
+						"amount": 100,
+						"claimDate": "2016-04-10T00:00:00Z",
+						"region": "West",
+						"$typeScope": "enterprise_123456"
+						}
+					}
+				}
+			}
+			],
+			"next_marker": ""
+		}
+		*/
+	});
+```
+
+[query]: http://opensource.box.com/box-node-sdk/jsdoc/Metadata.html#query

lib/api-request.js

@@ -224,7 +224,6 @@ APIRequest.prototype.getResponseStream = function() {
  * @private
  */
 APIRequest.prototype._handleResponse = function(err, response) {
-	
 	// Clean sensitive headers here to prevent the user from accidentily using/logging them in prod
 	cleanSensitiveHeaders(this.request);
 

lib/managers/folders.js

@@ -61,7 +61,7 @@ Folders.prototype.get = function(folderID, options, callback) {
  * @param {string} folderID - Box ID of the folder being requested
  * @param {Object} [options] - Additional options for the request. Can be left null in most cases.
  * @param {Function} [callback] - Passed the folder information if it was acquired successfully
- * @returns {Promise<Object>} A prmoise resolving to the collection of the items in the folder
+ * @returns {Promise<Object>} A promise resolving to the collection of the items in the folder
  */
 Folders.prototype.getItems = function(folderID, options, callback) {
 	var params = {

lib/managers/metadata.js

@@ -28,7 +28,8 @@
 // -----------------------------------------------------------------------------
 // Requirements
 // -----------------------------------------------------------------------------
-var urlPath = require('../util/url-path');
+var urlPath = require('../util/url-path'),
+	merge = require('merge-options');
 
 // -----------------------------------------------------------------------------
 // Private
@@ -38,7 +39,8 @@ var PROPERTIES_TEMPLATE = 'properties',
 	SCHEMA_SUBRESOURCE = 'schema',
 	ENTERPRISE_SCOPE = 'enterprise',
 	GLOBAL_SCOPE = 'global',
-	CASCADE_POLICIES_PATH = '/metadata_cascade_policies';
+	CASCADE_POLICIES_PATH = '/metadata_cascade_policies',
+	QUERY_PATH = '/metadata_queries/execute_read';
 
 // -----------------------------------------------------------------------------
 // Public
@@ -313,6 +315,31 @@ Metadata.prototype = {
 			};
 
 		return this.client.wrapWithDefaultHandler(this.client.post)(apiPath, params, callback);
+	},
+
+	/**
+	 * Query Box items by their metadata
+	 *
+	 * API Endpoint: '/metadata_queries/execute_read'
+	 * Method: POST
+	 *
+	 * @param {string} from - The template used in the query. Must be in the form scope.templateKey
+	 * @param {string} ancestorFolderId - The folder_id to which to restrain the query
+	 * @param {Object} options - Query options
+	 * @param {Function} [callback] - Passed a collection of items and their associated metadata
+	 * @returns {Promise<void>} Promise resolving to a collection of items and their associated metadata
+	 */
+	query(from, ancestorFolderId, options, callback) {
+		var body = {
+			from,
+			ancestor_folder_id: ancestorFolderId
+		};
+
+		var params = {
+			body: merge(body, options)
+		};
+
+		return this.client.wrapWithDefaultHandler(this.client.post)(QUERY_PATH, params, callback);
 	}
 };
 

lib/util/paging-iterator.js

@@ -58,11 +58,11 @@ class PagingIterator {
 	 * @returns {boolean} Whether the response is iterable
 	 */
 	static isIterable(response) {
-		var isGetRequest = (response.request && response.request.method === 'GET'),
+		var isGetOrPostRequest = (response.request && (response.request.method === 'GET' || response.request.method === 'POST')),
 			hasEntries = (response.body && Array.isArray(response.body.entries)),
 			notEventStream = (response.body && !response.body.next_stream_position);
 
-		return Boolean(isGetRequest && hasEntries && notEventStream);
+		return Boolean(isGetOrPostRequest && hasEntries && notEventStream);
 	}
 
 	/**
@@ -80,7 +80,6 @@ class PagingIterator {
 
 
 		var data = response.body;
-
 		if (Number.isSafeInteger(data.offset)) {
 			this.nextField = PAGING_MODES.OFFSET;
 			this.nextValue = data.offset;
@@ -102,6 +101,13 @@ class PagingIterator {
 			headers: response.request.headers,
 			qs: querystring.parse(response.request.uri.query)
 		};
+		if (response.request.body) {
+			if (Object.prototype.toString.call(response.request.body) === '[object Object]') {
+				this.options.body = response.request.body;
+			} else {
+				this.options.body = JSON.parse(response.request.body);
+			}
+		}
 
 		// querystring.parse() makes everything a string, ensure numeric params are the correct type
 		if (this.options.qs.limit) {
@@ -112,7 +118,12 @@ class PagingIterator {
 		}
 
 		delete this.options.headers.Authorization;
-		this.fetch = client.get.bind(client, href);
+		if (response.request.method === 'GET') {
+			this.fetch = client.get.bind(client, href);
+		}
+		if (response.request.method === 'POST') {
+			this.fetch = client.post.bind(client, href);
+		}
 		this.buffer = response.body.entries;
 		this.queue = new PromiseQueue(1, Infinity);
 		this._updatePaging(response);
@@ -146,8 +157,13 @@ class PagingIterator {
 				this.done = true;
 			}
 		}
-
-		this.options.qs[this.nextField] = this.nextValue;
+		if (response.request.method === 'GET') {
+			this.options.qs[this.nextField] = this.nextValue;
+		} else if (response.request.method === 'POST') {
+			this.options.body[this.nextField] = this.nextValue;
+			let bodyString = JSON.stringify(this.options.body);
+			this.options.headers['content-length'] = bodyString.length;
+		}
 	}
 
 	/**