Add common item methods for Web Links (#364)

box · Mar 27, 2019 · 7549d4f · 7549d4f
1 parent a55b299
commit 7549d4f
Show file tree

Hide file tree

Showing 10 changed files with 918 additions and 1 deletion.
diff --git a/docs/collections.md b/docs/collections.md
@@ -14,6 +14,8 @@ all be in the same folder.
 - [Remove File from a Collection](#remove-file-from-a-collection)
 - [Add Folder to a Collection](#add-folder-to-a-collection)
 - [Remove Folder from a Collection](#remove-folder-from-a-collection)
+- [Add Web Link to a Collection](#add-web-link-to-a-collection)
+- [Remove Web Link from a Collection](#remove-web-link-from-a-collection)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -109,3 +111,25 @@ method with the IDs of the folder and collection.
 ```js
 client.folders.removeFromCollection('87263', '235747', callback);
 ```
+
+Add Web Link to a Collection
+----------------------------
+
+To add a web link to a collection, call the
+[`weblinks.addToCollection(webLinkID, collectionID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/WebLinks.html#addToCollection)
+method with the IDs of the web link and collection.
+
+```js
+client.weblinks.addToCollection('87263', '235747', callback);
+```
+
+Remove Web Link from a Collection
+---------------------------------
+
+To remove a web link from a collection, call the
+[`weblinks.removeFromCollection(webLinkID, collectionID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/WebLinks.html#removeFromCollection)
+method with the IDs of the web link and collection.
+
+```js
+client.weblinks.removeFromCollection('87263', '235747', callback);
+```
diff --git a/docs/web-links.md b/docs/web-links.md
@@ -13,6 +13,8 @@ and restore.
 - [Get a Web Link's information](#get-a-web-links-information)
 - [Update a Web Link](#update-a-web-link)
 - [Delete a Web Link](#delete-a-web-link)
+- [Copy a Web Link](#copy-a-web-link)
+- [Move a Web Link](#move-a-web-link)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -240,3 +242,128 @@ client.weblinks.delete('11111')
 		// deletion succeeded — no value returned
 	});
 ```
+
+Copy a Web Link
+---------------
+
+Call the
+[`weblinks.copy(webLinkID, destinationFolderID, options, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/WebLinks.html#copy)
+method to copy a web link into another folder.
+
+```js
+client.weblinks.copy('11111', '0')
+    .then(webLinkCopy => {
+       /* webLinkCopy -> {
+		    type: 'web_link',
+			id: '11112',
+			sequence_id: '0',
+			etag: '0',
+			name: 'Renamed web link copy',
+			url: 'http://example.com',
+			created_by:
+			{ type: 'user',
+				id: '22222',
+				name: 'Example User',
+				login: 'user@example.com' },
+			created_at: '2019-03-26T12:49:06-07:00',
+			modified_at: '2019-03-26T12:49:06-07:00',
+			parent:
+			{ type: 'folder',
+				id: '0',
+				sequence_id: null,
+				etag: null,
+				name: 'All Files' },
+			description: '',
+			item_status: 'active',
+			trashed_at: null,
+			purged_at: null,
+			shared_link: null,
+			path_collection:
+			{ total_count: 1,
+				entries:
+				[ { type: 'folder',
+					id: '0',
+					sequence_id: null,
+					etag: null,
+					name: 'All Files' } ] },
+			modified_by:
+			{ type: 'user',
+				id: '22222',
+				name: 'Example User',
+				login: 'user@example.com' },
+			owned_by:
+			{ type: 'user',
+				id: '22222',
+				name: 'Example User',
+				login: 'user@example.com' } }
+        */
+    });
+```
+
+An optional `name` parameter can also be passed to rename the folder on copy.  This can be
+used to avoid a name conflict when there is already an item with the same name in the
+target folder.
+
+```js
+client.weblinks.copy('12345', '0', {name: 'Renamed web link'})
+    .then(webLinkCopy => {
+        // ...
+    });
+```
+
+Move a Web Link
+---------------
+
+Call the [`weblinks.move(webLinkID, destinationFolderID, callback)`](http://opensource.box.com/box-node-sdk/jsdoc/WebLinks.html#move) method with the destination you want the folder moved to.
+
+```js
+var webLinkID = '88888';
+var destinationFolderID = '0';
+client.weblinks.move(webLinkID, destinationFolderID)
+    .then(webLink => {
+       /* webLink -> {
+		    type: 'web_link',
+			id: '88888',
+			sequence_id: '0',
+			etag: '0',
+			name: 'Example Web Link',
+			url: 'http://example.com',
+			created_by:
+			{ type: 'user',
+				id: '22222',
+				name: 'Example User',
+				login: 'user@example.com' },
+			created_at: '2019-03-26T12:49:06-07:00',
+			modified_at: '2019-03-26T12:49:06-07:00',
+			parent:
+			{ type: 'folder',
+				id: '0',
+				sequence_id: null,
+				etag: null,
+				name: 'All Files' },
+			description: '',
+			item_status: 'active',
+			trashed_at: null,
+			purged_at: null,
+			shared_link: null,
+			path_collection:
+			{ total_count: 1,
+				entries:
+				[ { type: 'folder',
+					id: '0',
+					sequence_id: null,
+					etag: null,
+					name: 'All Files' } ] },
+			modified_by:
+			{ type: 'user',
+				id: '22222',
+				name: 'Example User',
+				login: 'user@example.com' },
+			owned_by:
+			{ type: 'user',
+				id: '22222',
+				name: 'Example User',
+				login: 'user@example.com' } }
+        */
+    });
+```
diff --git a/lib/managers/web-links.js b/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;