box-node-sdk 1.9.0 → 1.12.0

package/.nycrc

@@ -0,0 +1,15 @@
+{
+    "include": [
+        "lib/**/*.js"
+    ],
+    "reporter": [
+        "text-summary"
+    ],
+    "check-coverage": true,
+    "lines": 98,
+    "statements": 98,
+    "functions": 99,
+    "branches": 92,
+    "report-dir": "./coverage",
+    "all": true
+}

package/.travis.yml

@@ -1,5 +1,7 @@
 language: node_js
 node_js:
+    - "9"
+    - "8"
     - "7"
     - "6"
     - "5"

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.12.0
+
+- Added support for [metadata template deletion](./docs/metadata.md#delete-metadata-template)
+
+## 1.11.0
+
+- Added options to preserve file timestamps on [file upload](./docs/files.md#upload-a-file)
+and to rename a file or preserve modification timestamp on [new version upload](./docs/files.md#upload-a-new-version-of-a-file)
+- Added [Collaboration Whitelist](./docs/collaboration-whitelist.md) functionality to allow enterprise admins
+to control which external users can collaborate on their content
+- Added an option to Token Exchange to generate [annotator tokens](./docs/authentication.md#annotator-tokens) for use with Box View
+
+## 1.10.1
+
+- Updated to jsonwebtoken@8.1.0 to fix an issue where some users were getting
+an error when using App Auth
+
+## 1.10.0
+
+- Added support for [Terms of Service](./docs/terms-of-service.md) endpoints
+- Fixed a bug where receiving a collection without paging parameters from the API
+would cause the SDK to throw an exception when using the `iterators` SDK option.
+Now, this will return an iterator over the items returned by the API.
+- Fixed a bug in Token Exchange where passing multiple scopes would result in an error
+- Added support for [getting Representations info on a file](./docs/files.md#get-representation-info)
+
 ## 1.9.0
 
 - Fixed token methods to return bluebird Promises instead of native Promises

package/Makefile.js

@@ -11,6 +11,7 @@
 
 require('shelljs/make');
 var nodeCLI = require('shelljs-nodecli');
+var semver = require('semver');
 
 //------------------------------------------------------------------------------
 // Helpers
@@ -85,7 +86,10 @@ target.lint = function() {
 
 target.test = function() {
 	var code = target.lint();
-	code += nodeCLI.exec('istanbul', 'cover', MOCHA_BINARY, '--', '-c', '-R spec', TEST_FILES).code;
+	if (semver.gte(process.version.substr(1), '6.0.0')) {
+		code += nodeCLI.exec('nsp', 'check').code;
+	}
+	code += nodeCLI.exec('nyc', MOCHA_BINARY, '-c', '-R spec', '--exit', TEST_FILES).code;
 
 	if (code) {
 		exit(code);

package/lib/box-client.js

@@ -57,7 +57,9 @@ var Users = require('./managers/users'),
 	RetentionPolicies = require('./managers/retention-policies'),
 	DevicePins = require('./managers/device-pins'),
 	Webhooks = require('./managers/webhooks'),
-	RecentItems = require('./managers/recent-items');
+	RecentItems = require('./managers/recent-items'),
+	CollaborationWhitelist = require('./managers/collaboration-whitelist'),
+	TermsOfService = require('./managers/terms-of-service');
 
 // ------------------------------------------------------------------------------
 // Private
@@ -207,6 +209,9 @@ function BoxClient(apiSession, config, requestManager) {
 	this.devicePins = new DevicePins(this);
 	this.webhooks = new Webhooks(this);
 	this.recentItems = new RecentItems(this);
+	this.collaborationWhitelist = new CollaborationWhitelist(this);
+	this.termsOfService = new TermsOfService(this);
+
 
 	// Array of requests when in batch mode, null otherwise
 	this._batch = null;
@@ -458,12 +463,22 @@ BoxClient.prototype.revokeTokens = function(callback) {
  * 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 {Object} [options] - Optional parameters
+ * @param {ActorParams} [options.actor] - Optional actor parameters for creating annotator tokens with Token Auth client
  * @param {Function} [callback] Called with the new token
  * @returns {Promise<TokenInfo>} A promise resolving to the exchanged token info
  */
-BoxClient.prototype.exchangeToken = function(scopes, resource, callback) {
+BoxClient.prototype.exchangeToken = function(scopes, resource, options, callback) {
+
+	// Shuffle optional parameters
+	if (typeof options === 'function') {
+		callback = options;
+		options = {};
+	}
+
+	var opts = Object.assign({ tokenRequestOptions: this._tokenOptions || null }, options);
 
-	return this._session.exchangeToken(scopes, resource, this._tokenOptions)
+	return this._session.exchangeToken(scopes, resource, opts)
 		.asCallback(callback);
 };
 

package/lib/event-stream.js

@@ -181,57 +181,57 @@ EventStream.prototype.fetchEvents = function() {
 
 	// Get new events after the rate limiter expires
 	return this._rateLimiter.then(() => this._client.events.get(eventParams)
-			.then(events => {
-
-				// Reset the rate limiter
-				this._rateLimiter = Promise.delay(this._options.fetchInterval);
-
-				// If the response wasn't what we expected, re-poll
-				if (!events.entries || !events.next_stream_position) {
-					this.doLongPoll();
-					return;
-				}
-
-				this._streamPosition = events.next_stream_position;
-
-				// De-duplicate the fetched events, since the API often returns
-				// the same events at multiple subsequent stream positions
-				var newEvents = events.entries.filter(event => !this._dedupHash[event.event_id]);
-
-				// If there aren't any non-duplicate events, go back to polling
-				if (!newEvents.length) {
-					this.doLongPoll();
-					return;
-				}
-
-				// Pause the stream to avoid race conditions while pushing in the new events.
-				// Without this, _read() would be called again from inside each push(),
-				// resulting in multiple parallel calls to fetchEvents().
-				// See https://github.com/nodejs/node/issues/3203
-				var wasPaused = this.isPaused();
-				this.pause();
-
-				// Push new events into the stream
-				newEvents.forEach(event => {
-					this._dedupHash[event.event_id] = true;
-					this.push(event);
-				});
-
-				if (!wasPaused) {
-					// This will deliver the events and trigger the next call to _read() once they have been consumed.
-					this.resume();
-				}
-
-				// Once the deduplication filter gets too big, clean it up
-				if (Object.keys(this._dedupHash).length >= this._options.deduplicationFilterSize) {
-					this.cleanupDedupFilter(events.entries);
-				}
-			})
-			.catch(err => {
-
-				this.emit('error', err);
-				setTimeout(() => this.getLongPollInfo(), this._options.retryDelay);
-			})
+		.then(events => {
+
+			// Reset the rate limiter
+			this._rateLimiter = Promise.delay(this._options.fetchInterval);
+
+			// If the response wasn't what we expected, re-poll
+			if (!events.entries || !events.next_stream_position) {
+				this.doLongPoll();
+				return;
+			}
+
+			this._streamPosition = events.next_stream_position;
+
+			// De-duplicate the fetched events, since the API often returns
+			// the same events at multiple subsequent stream positions
+			var newEvents = events.entries.filter(event => !this._dedupHash[event.event_id]);
+
+			// If there aren't any non-duplicate events, go back to polling
+			if (!newEvents.length) {
+				this.doLongPoll();
+				return;
+			}
+
+			// Pause the stream to avoid race conditions while pushing in the new events.
+			// Without this, _read() would be called again from inside each push(),
+			// resulting in multiple parallel calls to fetchEvents().
+			// See https://github.com/nodejs/node/issues/3203
+			var wasPaused = this.isPaused();
+			this.pause();
+
+			// Push new events into the stream
+			newEvents.forEach(event => {
+				this._dedupHash[event.event_id] = true;
+				this.push(event);
+			});
+
+			if (!wasPaused) {
+				// This will deliver the events and trigger the next call to _read() once they have been consumed.
+				this.resume();
+			}
+
+			// Once the deduplication filter gets too big, clean it up
+			if (Object.keys(this._dedupHash).length >= this._options.deduplicationFilterSize) {
+				this.cleanupDedupFilter(events.entries);
+			}
+		})
+		.catch(err => {
+
+			this.emit('error', err);
+			setTimeout(() => this.getLongPollInfo(), this._options.retryDelay);
+		})
 	);
 };
 

package/lib/managers/collaboration-whitelist.js

@@ -0,0 +1,225 @@
+/**
+ * @fileoverview Manager for the Box Collaboration Whitelist Resource
+ */
+
+'use strict';
+// -----------------------------------------------------------------------------
+// Typedefs
+// -----------------------------------------------------------------------------
+
+/**
+ * Collaboration Whitelist parameter constant
+ * @typedef {string} CollaborationWhitelistDirection Determines the type of restriction for whitelisting for a domain
+ */
+
+// ------------------------------------------------------------------------------
+// Requirements
+// ------------------------------------------------------------------------------
+var urlPath = require('../util/url-path');
+
+
+// ------------------------------------------------------------------------------
+// Private
+// ------------------------------------------------------------------------------
+var BASE_PATH = '/collaboration_whitelist_entries',
+	TARGET_ENTRY_PATH = '/collaboration_whitelist_exempt_targets';
+
+// ------------------------------------------------------------------------------
+// Public
+// ------------------------------------------------------------------------------
+
+/**
+ * Simple manager for interacting with all 'Collaboration Whitelist' endpoints and actions.
+ *
+ * @constructor
+ * @param {BoxClient} client - The Box API Client that is responsible for making calls to the API
+ * @returns {void}
+ */
+function CollaborationWhitelist(client) {
+	this.client = client;
+}
+
+/**
+ * Enum of valid collaboration whitelist directions
+ *
+ * @readonly
+ * @enum {CollaborationWhitelistDirection}
+ */
+CollaborationWhitelist.prototype.directions = Object.freeze({
+	INBOUND: 'inbound',
+	OUTBOUND: 'outbound',
+	BOTH: 'both'
+});
+
+/**
+ * Add a domain to the enterprise's whitelist.
+ *
+ * API Endpoint: '/collaboration_whitelist_entries'
+ * Method: POST
+ *
+ * @param {string} domain - The domain to be added to the whitelist
+ * @param {CollaborationWhitelistDirection} direction - Inbound refers to collaboration actions within an enterprise. Outbound
+ *                                                      refers to collaboration actions external to an enterprise. Both refers to
+ *                                                      collaboration actions taken within and external to an enterprise
+ * @param {Function} [callback] - Passed the collaboration whitelist information if it was created successfully
+ * @returns {Promise<Object>} A promise resolve to the collaboration whitelist object
+ */
+CollaborationWhitelist.prototype.addDomain = function(domain, direction, callback) {
+
+	var params = {
+		body: {
+			domain: domain,
+			direction: direction
+		}
+	};
+
+	var apiPath = urlPath(BASE_PATH);
+	return this.client.wrapWithDefaultHandler(this.client.post)(apiPath, params, callback);
+};
+
+/**
+ * Requests a collaboration whitelist entry with a given ID.
+ *
+ * API Endpoint: '/collaboration_whitelist_entries/:domainID'
+ * Method: GET
+ *
+ * @param {string} domainID - Box ID of the collaboration whitelist being requested
+ * @param {Object} [qs] - Additional options can be passed with the request via querystring. Can be left null in most cases.
+ * @param {Function} [callback] - Passed the collaboration whitelist information if it was acquired successfully
+ * @returns {Promise<Object>} A promise resolving to the collaboration whitelist object
+ */
+CollaborationWhitelist.prototype.getWhitelistedDomain = function(domainID, qs, callback) {
+
+	var params = { qs };
+
+	var apiPath = urlPath(BASE_PATH, domainID);
+	return this.client.wrapWithDefaultHandler(this.client.get)(apiPath, params, callback);
+};
+
+/**
+ * Requests all collaboration whitelist entries within an enterprise.
+ *
+ * API Endpoint: '/collaboration_whitelist_entries'
+ * Method: GET
+ *
+ * @param {Object} [options] - Additional options. Can be left null in most cases.
+ * @param {int} [options.limit] - The number of collaboration whitelists to retrieve
+ * @param {string} [options.marker] - Paging marker, retrieve records starting at this position in the list. Left blank to start at the beginning.
+ * @param {Function} [callback] - Passed a list of collaboration whitelists if successful, error otherwise
+ * @returns {Promise<Object>} A promise resolving to the collection of collaboration whitelists
+ */
+CollaborationWhitelist.prototype.getAllWhitelistedDomains = function(options, callback) {
+
+	var params = {
+		qs: options
+	};
+
+	var apiPath = urlPath(BASE_PATH);
+	return this.client.wrapWithDefaultHandler(this.client.get)(apiPath, params, callback);
+};
+
+/**
+ * Delete a given collaboration whitelist entry.
+ *
+ * API Endpoint: '/collaboration_whitelist_entries/:domainID'
+ * Method: DELETE
+ *
+ * @param {string} domainID - Box ID of the collaboration whitelist being requested
+ * @param {Function} [callback] - Empty response body passed if successful.
+ * @returns {Promise<void>} A promise resolving to nothing
+ */
+CollaborationWhitelist.prototype.removeDomain = function(domainID, callback) {
+
+	var apiPath = urlPath(BASE_PATH, domainID);
+	return this.client.wrapWithDefaultHandler(this.client.del)(apiPath, null, callback);
+};
+
+/**
+ * Adds a Box User to the exempt target list.
+ *
+ * API Endpoint: '/collaboration_whitelist_exempt_targets'
+ * Method: GET
+ *
+ * @param {string} userID - The ID of the Box User to be added to the whitelist
+ * @param {Function} [callback] - Passed a collaboration whitelist for user if successful, error otherwise
+ * @returns {Promise<Object>} A promise resolving to a user collaboration whitelist
+ */
+CollaborationWhitelist.prototype.addExemption = function(userID, callback) {
+
+	var params = {
+		body: {
+			user: {
+				id: userID,
+				type: 'user'
+			}
+		}
+	};
+
+	var apiPath = urlPath(TARGET_ENTRY_PATH);
+	return this.client.wrapWithDefaultHandler(this.client.post)(apiPath, params, callback);
+};
+
+/**
+ * Retrieves information about a collaboration whitelist for user by whitelist ID.
+ *
+ * API Endpoint: '/collaboration_whitelist_exempt_targets/:exemptionID'
+ * Method: GET
+ *
+ * @param {string} exemptionID - The ID of the collaboration whitelist
+ * @param {Object} [qs] - Additional options can be passed with the request via querystring. Can be left null in most cases.
+ * @param {Function} [callback] - Passed the collaboration whitelist information for a user if it was acquired successfully
+ * @returns {Promise<Object>} A promise resolving to the collaboration whitelist object
+ */
+CollaborationWhitelist.prototype.getExemption = function(exemptionID, qs, callback) {
+
+	var params = {
+		qs: qs
+	};
+
+	var apiPath = urlPath(TARGET_ENTRY_PATH, exemptionID);
+	return this.client.wrapWithDefaultHandler(this.client.get)(apiPath, params, callback);
+};
+
+/**
+ * Retrieve a list of all exemptions to an enterprise's collaboration whitelist.
+ *
+ * API Endpoint: '/collaboration_whitelist_exempt_targets'
+ * Method: GET
+ *
+ * @param {Object} [options] - Additional options. Can be left null in most cases.
+ * @param {string} [options.limit] - The number of user collaboration whitelists to retrieve
+ * @param {string} [options.marker] - Paging marker, retrieve records starting at this position in the list. Left blank to start at the beginning.
+ * @param {Function} [callback] - Passed a list of user collaboration whitelists if successful, error otherwise
+ * @returns {Promise<Object>} A promise resolving to the collection of user collaboration whitelists
+ */
+CollaborationWhitelist.prototype.getAllExemptions = function(options, callback) {
+
+	var params = {
+		qs: options
+	};
+
+	var apiPath = urlPath(TARGET_ENTRY_PATH);
+	return this.client.wrapWithDefaultHandler(this.client.get)(apiPath, params, callback);
+};
+
+/**
+ * Delete a given user collaboration whitelist.
+ *
+ * API Endpoint: '/collaboration_whitelist_exempt_targets/:exemptionID'
+ * Method: DELETE
+ *
+ * @param {string} exemptionID - Box ID of the user collaboration whitelist being requested
+ * @param {Function} [callback] - Empty response body passed if successful.
+ * @returns {Promise<void>} A promise resolving to nothing
+ */
+CollaborationWhitelist.prototype.removeExemption = function(exemptionID, callback) {
+
+	var apiPath = urlPath(TARGET_ENTRY_PATH, exemptionID);
+	return this.client.wrapWithDefaultHandler(this.client.del)(apiPath, null, callback);
+};
+
+/**
+ * @module box-node-sdk/lib/managers/collaboration-whitelists
+ * @see {@Link CollaborationWhitelist}
+ */
+module.exports = CollaborationWhitelist;