Source: managers/collaboration-allowlist.ts

  1. /**
  2.  * @fileoverview Manager for the Box Collaboration Allowlist Resource
  3.  */
  5. // ------------------------------------------------------------------------------
  6. // Requirements
  7. // ------------------------------------------------------------------------------
  9. import BoxClient from '../box-client';
  10. import urlPath from '../util/url-path';
  12. // -----------------------------------------------------------------------------
  13. // Typedefs
  14. // -----------------------------------------------------------------------------
  16. /**
  17.  * Collaboration Allowlist parameter constant
  18.  * @typedef {string} CollaborationAllowlistDirection Determines the type of restriction for allowlisting for a domain
  19.  */
  20. enum CollaborationAllowlistDirection {
  21. 	INBOUND = 'inbound',
  22. 	OUTBOUND = 'outbound',
  23. 	BOTH = 'both',
  24. }
  26. // ------------------------------------------------------------------------------
  27. // Private
  28. // ------------------------------------------------------------------------------
  30. const BASE_PATH = '/collaboration_whitelist_entries',
  31. 	TARGET_ENTRY_PATH = '/collaboration_whitelist_exempt_targets';
  33. // ------------------------------------------------------------------------------
  34. // Public
  35. // ------------------------------------------------------------------------------
  37. /**
  38.  * Simple manager for interacting with all 'Collaboration Allowlist' endpoints and actions.
  39.  *
  40.  * @constructor
  41.  * @param {BoxClient} client - The Box API Client that is responsible for making calls to the API
  42.  * @returns {void}
  43.  */
  44. class CollaborationAllowlist {
  45. 	client: BoxClient;
  46. 	directions!: Record<string, string>;
  48. 	constructor(client: BoxClient) {
  49. 		this.client = client;
  50. 	}
  52. 	/**
  53. 	 * Add a domain to the enterprise's allowlist.
  54. 	 *
  55. 	 * API Endpoint: '/collaboration_whitelist_entries'
  56. 	 * Method: POST
  57. 	 *
  58. 	 * @param {string} domain - The domain to be added to the allowlist
  59. 	 * @param {CollaborationAllowlistDirection} direction - Inbound refers to collaboration actions within an enterprise. Outbound
  60. 	 *                                                      refers to collaboration actions external to an enterprise. Both refers to
  61. 	 *                                                      collaboration actions taken within and external to an enterprise
  62. 	 * @param {Function} [callback] - Passed the collaboration allowlist information if it was created successfully
  63. 	 * @returns {Promise<Object>} A promise resolve to the collaboration allowlist object
  64. 	 */
  65. 	addDomain(
  66. 		domain: string,
  67. 		direction: CollaborationAllowlistDirection,
  68. 		callback?: Function
  69. 	) {
  70. 		var params = {
  71. 			body: {
  72. 				domain,
  73. 				direction,
  74. 			},
  75. 		};
  77. 		var apiPath = urlPath(BASE_PATH);
  78. 		return this.client.wrapWithDefaultHandler(this.client.post)(
  79. 			apiPath,
  80. 			params,
  81. 			callback
  82. 		);
  83. 	}
  85. 	/**
  86. 	 * Requests a collaboration allowlist entry with a given ID.
  87. 	 *
  88. 	 * API Endpoint: '/collaboration_whitelist_entries/:domainID'
  89. 	 * Method: GET
  90. 	 *
  91. 	 * @param {string} domainID - Box ID of the collaboration allowlist being requested
  92. 	 * @param {Object} [options] - Additional options for the request. Can be left null in most cases.
  93. 	 * @param {Function} [callback] - Passed the collaboration allowlist information if it was acquired successfully
  94. 	 * @returns {Promise<Object>} A promise resolving to the collaboration allowlist object
  95. 	 */
  96. 	getAllowlistedDomain(
  97. 		domainID: string,
  98. 		options?: Record<string, any>,
  99. 		callback?: Function
  100. 	) {
  101. 		var params = { qs: options };
  103. 		var apiPath = urlPath(BASE_PATH, domainID);
  104. 		return this.client.wrapWithDefaultHandler(this.client.get)(
  105. 			apiPath,
  106. 			params,
  107. 			callback
  108. 		);
  109. 	}
  111. 	/**
  112. 	 * Requests all collaboration allowlist entries within an enterprise.
  113. 	 *
  114. 	 * API Endpoint: '/collaboration_whitelist_entries'
  115. 	 * Method: GET
  116. 	 *
  117. 	 * @param {Object} [options] - Additional options. Can be left null in most cases.
  118. 	 * @param {int} [options.limit] - The number of collaboration allowlists to retrieve
  119. 	 * @param {string} [options.marker] - Paging marker, retrieve records starting at this position in the list. Left blank to start at the beginning.
  120. 	 * @param {Function} [callback] - Passed a list of collaboration allowlists if successful, error otherwise
  121. 	 * @returns {Promise<Object>} A promise resolving to the collection of collaboration allowlists
  122. 	 */
  123. 	getAllAllowlistedDomains(
  124. 		options?: {
  125. 			limit?: number;
  126. 			marker?: string;
  127. 		},
  128. 		callback?: Function
  129. 	) {
  130. 		var params = {
  131. 			qs: options,
  132. 		};
  134. 		var apiPath = urlPath(BASE_PATH);
  135. 		return this.client.wrapWithDefaultHandler(this.client.get)(
  136. 			apiPath,
  137. 			params,
  138. 			callback
  139. 		);
  140. 	}
  142. 	/**
  143. 	 * Delete a given collaboration allowlist entry.
  144. 	 *
  145. 	 * API Endpoint: '/collaboration_whitelist_entries/:domainID'
  146. 	 * Method: DELETE
  147. 	 *
  148. 	 * @param {string} domainID - Box ID of the collaboration allowlist being requested
  149. 	 * @param {Function} [callback] - Empty response body passed if successful.
  150. 	 * @returns {Promise<void>} A promise resolving to nothing
  151. 	 */
  152. 	removeDomain(domainID: string, callback?: Function) {
  153. 		var apiPath = urlPath(BASE_PATH, domainID);
  154. 		return this.client.wrapWithDefaultHandler(this.client.del)(
  155. 			apiPath,
  156. 			null,
  157. 			callback
  158. 		);
  159. 	}
  161. 	/**
  162. 	 * Adds a Box User to the exempt target list.
  163. 	 *
  164. 	 * API Endpoint: '/collaboration_whitelist_exempt_targets'
  165. 	 * Method: GET
  166. 	 *
  167. 	 * @param {string} userID - The ID of the Box User to be added to the allowlist
  168. 	 * @param {Function} [callback] - Passed a collaboration allowlist for user if successful, error otherwise
  169. 	 * @returns {Promise<Object>} A promise resolving to a user collaboration allowlist
  170. 	 */
  171. 	addExemption(userID: string, callback?: Function) {
  172. 		var params = {
  173. 			body: {
  174. 				user: {
  175. 					id: userID,
  176. 					type: 'user',
  177. 				},
  178. 			},
  179. 		};
  181. 		var apiPath = urlPath(TARGET_ENTRY_PATH);
  182. 		return this.client.wrapWithDefaultHandler(this.client.post)(
  183. 			apiPath,
  184. 			params,
  185. 			callback
  186. 		);
  187. 	}
  189. 	/**
  190. 	 * Retrieves information about a collaboration allowlist for user by allowlist ID.
  191. 	 *
  192. 	 * API Endpoint: '/collaboration_whitelist_exempt_targets/:exemptionID'
  193. 	 * Method: GET
  194. 	 *
  195. 	 * @param {string} exemptionID - The ID of the collaboration allowlist
  196. 	 * @param {Object} [options] - Additional options for the request. Can be left null in most cases.
  197. 	 * @param {Function} [callback] - Passed the collaboration allowlist information for a user if it was acquired successfully
  198. 	 * @returns {Promise<Object>} A promise resolving to the collaboration allowlist object
  199. 	 */
  200. 	getExemption(
  201. 		exemptionID: string,
  202. 		options?: Record<string, any>,
  203. 		callback?: Function
  204. 	) {
  205. 		var params = {
  206. 			qs: options,
  207. 		};
  209. 		var apiPath = urlPath(TARGET_ENTRY_PATH, exemptionID);
  210. 		return this.client.wrapWithDefaultHandler(this.client.get)(
  211. 			apiPath,
  212. 			params,
  213. 			callback
  214. 		);
  215. 	}
  217. 	/**
  218. 	 * Retrieve a list of all exemptions to an enterprise's collaboration allowlist.
  219. 	 *
  220. 	 * API Endpoint: '/collaboration_whitelist_exempt_targets'
  221. 	 * Method: GET
  222. 	 *
  223. 	 * @param {Object} [options] - Additional options. Can be left null in most cases.
  224. 	 * @param {int} [options.limit] - The number of user collaboration allowlists to retrieve
  225. 	 * @param {string} [options.marker] - Paging marker, retrieve records starting at this position in the list. Left blank to start at the beginning.
  226. 	 * @param {Function} [callback] - Passed a list of user collaboration allowlists if successful, error otherwise
  227. 	 * @returns {Promise<Object>} A promise resolving to the collection of user collaboration allowlists
  228. 	 */
  229. 	getAllExemptions(
  230. 		options?: {
  231. 			limit?: number;
  232. 			marker?: string;
  233. 		},
  234. 		callback?: Function
  235. 	) {
  236. 		var params = {
  237. 			qs: options,
  238. 		};
  240. 		var apiPath = urlPath(TARGET_ENTRY_PATH);
  241. 		return this.client.wrapWithDefaultHandler(this.client.get)(
  242. 			apiPath,
  243. 			params,
  244. 			callback
  245. 		);
  246. 	}
  248. 	/**
  249. 	 * Delete a given user collaboration allowlist.
  250. 	 *
  251. 	 * API Endpoint: '/collaboration_whitelist_exempt_targets/:exemptionID'
  252. 	 * Method: DELETE
  253. 	 *
  254. 	 * @param {string} exemptionID - Box ID of the user collaboration allowlist being requested
  255. 	 * @param {Function} [callback] - Empty response body passed if successful.
  256. 	 * @returns {Promise<void>} A promise resolving to nothing
  257. 	 */
  258. 	removeExemption(exemptionID: string, callback?: Function) {
  259. 		var apiPath = urlPath(TARGET_ENTRY_PATH, exemptionID);
  260. 		return this.client.wrapWithDefaultHandler(this.client.del)(
  261. 			apiPath,
  262. 			null,
  263. 			callback
  264. 		);
  265. 	}
  266. }
  268. /**
  269.  * Enum of valid collaboration allowlist directions
  270.  *
  271.  * @readonly
  272.  * @enum {CollaborationAllowlistDirection}
  273.  */
  274. CollaborationAllowlist.prototype.directions = CollaborationAllowlistDirection;
  276. /**
  277.  * @module box-node-sdk/lib/managers/collaboration-allowlists
  278.  * @see {@Link CollaborationAllowlist}
  279.  */
  280. export = CollaborationAllowlist;