Source: managers/web-links.ts

  1. /**
  2.  * @fileoverview Manager for the Web Links Resource
  3.  */
  5. // ------------------------------------------------------------------------------
  6. // Requirements
  7. // ------------------------------------------------------------------------------
  9. import BoxClient from '../box-client';
  10. import urlPath from '../util/url-path';
  12. // ------------------------------------------------------------------------------
  13. // Private
  14. // ------------------------------------------------------------------------------
  16. const BASE_PATH = '/web_links';
  18. // ------------------------------------------------------------------------------
  19. // Public
  20. // ------------------------------------------------------------------------------
  22. /**
  23.  * Simple manager for interacting with all 'Weblinks' endpoints and actions.
  24.  *
  25.  * @constructor
  26.  * @param {BoxClient} client - The Box API Client that is responsible for making calls to the API
  27.  * @returns {void}
  28.  */
  29. class WebLinks {
  30. 	client: BoxClient;
  32. 	constructor(client: BoxClient) {
  33. 		this.client = client;
  34. 	}
  36. 	/**
  37. 	 * Creates a web link object within a given folder.
  38. 	 *
  39. 	 * API Endpoint: '/web_links'
  40. 	 * Method: POST
  41. 	 *
  42. 	 * @param {string} url - URL you want the web link to point to. Must include http:// or https://
  43. 	 * @param {string} parentID - The ID of the parent folder where you're creating the web link
  44. 	 * @param {Object} [options] - Additional parameters
  45. 	 * @param {string} [options.name] - Name for the web link. Will default to the URL if empty.
  46. 	 * @param {string} [options.description] - Description of the web link. Will provide more context to users about the web link.
  47. 	 * @param {Function} [callback] - Passed the new web link information if it was acquired successfully, error otherwise
  48. 	 * @returns {Promise<Object>} A promise resolving to the created weblink object
  49. 	 */
  50. 	create(
  51. 		url: string,
  52. 		parentID: string,
  53. 		options?: {
  54. 			name?: string;
  55. 			description?: string;
  56. 		},
  57. 		callback?: Function
  58. 	) {
  59. 		var apiPath = urlPath(BASE_PATH),
  60. 			params = {
  61. 				body: {
  62. 					url,
  63. 					parent: {
  64. 						id: parentID,
  65. 					},
  66. 				},
  67. 			};
  69. 		Object.assign(params.body, options);
  71. 		return this.client.wrapWithDefaultHandler(this.client.post)(
  72. 			apiPath,
  73. 			params,
  74. 			callback
  75. 		);
  76. 	}
  78. 	/**
  79. 	 * Use to get information about the web link.
  80. 	 *
  81. 	 * API Endpoint: '/web_links/:weblinkID'
  82. 	 * Method: GET
  83. 	 *
  84. 	 * @param {string} weblinkID - The Box ID of web link being requested
  85. 	 * @param {Object} [options] - Additional options for the request. Can be left null in most cases.
  86. 	 * @param {Function} [callback] - Passed the web-link information if it was acquired successfully, error otherwise
  87. 	 * @returns {Promise<Object>} A promise resolving to the weblink object
  88. 	 */
  89. 	get(weblinkID: string, options?: Record<string, any>, callback?: Function) {
  90. 		var apiPath = urlPath(BASE_PATH, weblinkID),
  91. 			params = {
  92. 				qs: options,
  93. 			};
  95. 		return this.client.wrapWithDefaultHandler(this.client.get)(
  96. 			apiPath,
  97. 			params,
  98. 			callback
  99. 		);
  100. 	}
  102. 	/**
  103. 	 * Updates information for a web link.
  104. 	 *
  105. 	 * API Endpoint: '/web_links/:weblinkID'
  106. 	 * Method: PUT
  107. 	 *
  108. 	 * @param {string} weblinkID - The Box ID of the web link being updated
  109. 	 * @param {Object} updates - Fields of the weblink to update
  110. 	 * @param {string} [updates.name] - Name for the web link. Will default to the URL if empty.
  111. 	 * @param {string} [updates.description] - Description of the web link. Will provide more context to users about the web link.
  112. 	 * @param {Function} [callback] - Passed the updated web link information if it was acquired successfully, error otherwise
  113. 	 * @returns {Promise<Object>} A promise resolving to the updated web link object
  114. 	 */
  115. 	update(
  116. 		weblinkID: string,
  117. 		updates?: {
  118. 			name?: string;
  119. 			description?: string;
  120. 			collections?: string[];
  121. 		},
  122. 		callback?: Function
  123. 	) {
  124. 		var apiPath = urlPath(BASE_PATH, weblinkID),
  125. 			params = {
  126. 				body: updates,
  127. 			};
  129. 		return this.client.wrapWithDefaultHandler(this.client.put)(
  130. 			apiPath,
  131. 			params,
  132. 			callback
  133. 		);
  134. 	}
  136. 	/**
  137. 	 * Deletes a web link and moves it to the trash
  138. 	 *
  139. 	 * API Endpoint: '/web_links/:weblinkID'
  140. 	 * Method: DELETE
  141. 	 *
  142. 	 * @param {string} weblinkID - The Box ID of the web link being moved to the trash
  143. 	 * @param {Function} [callback] - Empty body passed if successful, error otherwise
  144. 	 * @returns {Promise<Object>} A promise resolving to nothing
  145. 	 */
  146. 	delete(weblinkID: string, callback?: Function) {
  147. 		var apiPath = urlPath(BASE_PATH, weblinkID);
  149. 		return this.client.wrapWithDefaultHandler(this.client.del)(
  150. 			apiPath,
  151. 			null,
  152. 			callback
  153. 		);
  154. 	}
  156. 	/**
  157. 	 * Move a web link into a new parent folder.
  158. 	 *
  159. 	 * API Endpoint: '/web_links/:webLinkID'
  160. 	 * Method: PUT
  161. 	 *
  162. 	 * @param {string} webLinkID - The Box ID of the web link being requested
  163. 	 * @param {string} newParentID - The Box ID for the new parent folder. '0' to move to All Files.
  164. 	 * @param {Function} [callback] - Passed the updated web link information if it was acquired successfully
  165. 	 * @returns {Promise<Object>} A promise resolving to the updated web link object
  166. 	 */
  167. 	move(webLinkID: string, newParentID: string, callback?: Function) {
  168. 		var params = {
  169. 			body: {
  170. 				parent: {
  171. 					id: newParentID,
  172. 				},
  173. 			},
  174. 		};
  175. 		var apiPath = urlPath(BASE_PATH, webLinkID);
  176. 		return this.client.wrapWithDefaultHandler(this.client.put)(
  177. 			apiPath,
  178. 			params,
  179. 			callback
  180. 		);
  181. 	}
  183. 	/**
  184. 	 * Copy a web link into a new, different folder
  185. 	 *
  186. 	 * API Endpoint: '/web_links/:webLinkID/copy
  187. 	 * Method: POST
  188. 	 *
  189. 	 * @param {string} webLinkID - The Box ID of the web link being requested
  190. 	 * @param {string} newParentID - The Box ID for the new parent folder. '0' to copy to All Files.
  191. 	 * @param {Object} [options] - Optional parameters for the copy operation, can be left null in most cases
  192. 	 * @param {string} [options.name] - A new name to use if there is an identically-named item in the new parent folder
  193. 	 * @param {Function} [callback] - passed the new web link info if call was successful
  194. 	 * @returns {Promise<Object>} A promise resolving to the new web link object
  195. 	 */
  196. 	copy(
  197. 		webLinkID: string,
  198. 		newParentID: string,
  199. 		options?: {
  200. 			name?: string;
  201. 		},
  202. 		callback?: Function
  203. 	) {
  204. 		options = options || {};
  206. 		(options as Record<string, any>).parent = {
  207. 			id: newParentID,
  208. 		};
  210. 		var params = {
  211. 			body: options,
  212. 		};
  213. 		var apiPath = urlPath(BASE_PATH, webLinkID, '/copy');
  214. 		return this.client.wrapWithDefaultHandler(this.client.post)(
  215. 			apiPath,
  216. 			params,
  217. 			callback
  218. 		);
  219. 	}
  221. 	/**
  222. 	 * Add a web link to a given collection
  223. 	 *
  224. 	 * API Endpoint: '/web_links/:webLinkID'
  225. 	 * Method: PUT
  226. 	 *
  227. 	 * @param {string} webLinkID - The web link to add to the collection
  228. 	 * @param {string} collectionID - The collection to add the web link to
  229. 	 * @param {Function} [callback] - Passed the updated web link if successful, error otherwise
  230. 	 * @returns {Promise<Object>} A promise resolving to the updated web link object
  231. 	 */
  232. 	addToCollection(
  233. 		webLinkID: string,
  234. 		collectionID: string,
  235. 		callback?: Function
  236. 	) {
  237. 		return this.get(webLinkID, { fields: 'collections' })
  238. 			.then((data: any /* FIXME */) => {
  239. 				var collections = data.collections || [];
  241. 				// Convert to correct format
  242. 				collections = collections.map((c: any /* FIXME */) => ({ id: c.id }));
  244. 				if (!collections.find((c: any /* FIXME */) => c.id === collectionID)) {
  245. 					collections.push({ id: collectionID });
  246. 				}
  248. 				return this.update(webLinkID, { collections });
  249. 			})
  250. 			.asCallback(callback);
  251. 	}
  253. 	/**
  254. 	 * Remove a web link from a given collection
  255. 	 *
  256. 	 * API Endpoint: '/web_links/:webLinkID'
  257. 	 * Method: PUT
  258. 	 *
  259. 	 * @param {string} webLinkID - The web link to remove from the collection
  260. 	 * @param {string} collectionID - The collection to remove the web link from
  261. 	 * @param {Function} [callback] - Passed the updated web link if successful, error otherwise
  262. 	 * @returns {Promise<Object>} A promise resolving to the updated web link object
  263. 	 */
  264. 	removeFromCollection(
  265. 		webLinkID: string,
  266. 		collectionID: string,
  267. 		callback?: Function
  268. 	) {
  269. 		return this.get(webLinkID, { fields: 'collections' })
  270. 			.then((data: any /* FIXME */) => {
  271. 				var collections = data.collections || [];
  272. 				// Convert to correct object format and remove the specified collection
  273. 				collections = collections
  274. 					.map((c: any /* FIXME */) => ({ id: c.id }))
  275. 					.filter((c: any /* FIXME */) => c.id !== collectionID);
  277. 				return this.update(webLinkID, { collections });
  278. 			})
  279. 			.asCallback(callback);
  280. 	}
  281. }
  283. export = WebLinks;