Source: managers/users.ts

  1. /**
  2.  * @fileoverview Manager for the Box User Resource
  3.  */
  5. // ------------------------------------------------------------------------------
  6. // Requirements
  7. // ------------------------------------------------------------------------------
  9. import BoxClient from '../box-client';
  10. import urlPath from '../util/url-path';
  11. import { Readable } from 'stream';
  13. // ------------------------------------------------------------------------------
  14. // Private
  15. // ------------------------------------------------------------------------------
  17. const BASE_PATH = '/users',
  18. 	EMAIL_ALIASES_SUBRESOURCE = 'email_aliases',
  19. 	GROUP_MEMBERSHIPS_SUBRESOURCE = 'memberships',
  20. 	CURRENT_USER_ID = 'me';
  22. // ------------------------------------------------------------------------------
  23. // Public
  24. // ------------------------------------------------------------------------------
  26. /**
  27.  * Simple manager for interacting with all 'User' endpoints and actions.
  28.  *
  29.  * @constructor
  30.  * @param {BoxClient} client - The Box API Client that is responsible for making calls to the API
  31.  * @returns {void}
  32.  */
  33. class Users {
  34. 	client: BoxClient;
  36. 	CURRENT_USER_ID!: string;
  38. 	constructor(client: BoxClient) {
  39. 		this.client = client;
  40. 	}
  42. 	/**
  43. 	 * Requests information for the Box user info associated with a given ID
  44. 	 *
  45. 	 * API Endpoint: '/users/:id'
  46. 	 * Method: GET
  47. 	 *
  48. 	 * @param {string} userID - The ID of the user to retrieve
  49. 	 * @param {Object} [options] - Additional options for the request. Can be left null in most cases.
  50. 	 * @param {Function} [callback] - passed the user info if it was acquired successfully
  51. 	 * @returns {Promise<Object>} A promise resolving to the user object
  52. 	 */
  53. 	get(userID: string, options?: Record<string, any>, callback?: Function) {
  54. 		var apiPath = urlPath(BASE_PATH, userID),
  55. 			params = {
  56. 				qs: options,
  57. 			};
  59. 		return this.client.wrapWithDefaultHandler(this.client.get)(
  60. 			apiPath,
  61. 			params,
  62. 			callback
  63. 		);
  64. 	}
  66. 	/**
  67. 	 * Update some information about a user.
  68. 	 *
  69. 	 * API Endpoint: '/users/:id'
  70. 	 * Method: PUT
  71. 	 *
  72. 	 * @param {string} userID - The ID of the user to update
  73. 	 * @param {Object} updates - User fields to update
  74. 	 * @param {Function} [callback] - Passed the updated user information if it was acquired successfully
  75. 	 * @returns {Promise<Object>} A promise resolving to the updated user object
  76. 	 */
  77. 	update(userID: string, updates: Record<string, any>, callback?: Function) {
  78. 		var apiPath = urlPath(BASE_PATH, userID),
  79. 			params = {
  80. 				body: updates,
  81. 			};
  83. 		return this.client.wrapWithDefaultHandler(this.client.put)(
  84. 			apiPath,
  85. 			params,
  86. 			callback
  87. 		);
  88. 	}
  90. 	/**
  91. 	 * Deletes a user in an enterprise account.
  92. 	 *
  93. 	 * API Endpoint: '/users/:userID'
  94. 	 * Method: DELETE
  95. 	 *
  96. 	 * @param {string} userID - The ID of the user to delete
  97. 	 * @param {Object} [options] - Additional options for the request. Can be left null in most cases.
  98. 	 * @param {boolean} [options.notify] - Determines if the destination user should receive email notification of the transfer.
  99. 	 * @param {boolean} [options.force] - Whether or not the user should be deleted even if this user still own files.
  100. 	 * @param {Function} [callback] - Empty response body passed if successful, error otherwise
  101. 	 * @returns {Promise<void>} A promise resolving to nothing
  102. 	 */
  103. 	delete(
  104. 		userID: string,
  105. 		options?: {
  106. 			notify?: boolean;
  107. 			force?: boolean;
  108. 		},
  109. 		callback?: Function
  110. 	) {
  111. 		var apiPath = urlPath(BASE_PATH, userID),
  112. 			params = {
  113. 				qs: options,
  114. 			};
  116. 		return this.client.wrapWithDefaultHandler(this.client.del)(
  117. 			apiPath,
  118. 			params,
  119. 			callback
  120. 		);
  121. 	}
  123. 	// @NOTE(mwiller) 2014-06-10: This does not include their primary email address!
  124. 	/**
  125. 	 * Get all linked email addresses for a user.
  126. 	 *
  127. 	 * API Endpoint: '/users/:id/email_aliases'
  128. 	 * Method: GET
  129. 	 *
  130. 	 * @param {string} userID - The ID of the user to retrieve email alises for
  131. 	 * @param {Function} [callback] - Passed the email aliases if successful
  132. 	 * @returns {Promise<Object>} A promise resolving to the collection of email aliases
  133. 	 */
  134. 	getEmailAliases(userID: string, callback?: Function) {
  135. 		var apiPath = urlPath(BASE_PATH, userID, EMAIL_ALIASES_SUBRESOURCE);
  136. 		return this.client.wrapWithDefaultHandler(this.client.get)(
  137. 			apiPath,
  138. 			null,
  139. 			callback
  140. 		);
  141. 	}
  143. 	/**
  144. 	 * Add a linked email address to a user's account.
  145. 	 *
  146. 	 * API Endpoint: '/users/:id/email_aliases'
  147. 	 * Method: POST
  148. 	 *
  149. 	 * @param {string} userID - The ID of the user to add an email alias to
  150. 	 * @param {string} email - The email address to add
  151. 	 * @param {Object} [options] - Optional parameters
  152. 	 * @param {boolean} [options.is_confirmed=false] Whether or not to attempt to auto-confirm the alias (for admins)
  153. 	 * @param {Function} [callback] - Passed the new alias if successful
  154. 	 * @returns {Promise<Object>} A promise resolving to the new email alias
  155. 	 */
  156. 	addEmailAlias(
  157. 		userID: string,
  158. 		email: string,
  159. 		options?:
  160. 			| {
  161. 					is_confirmed?: boolean;
  162. 			  }
  163. 			| Function,
  164. 		callback?: Function
  165. 	) {
  166. 		options = options || {};
  167. 		if (typeof options === 'function') {
  168. 			callback = options;
  169. 			options = {};
  170. 		}
  172. 		var apiPath = urlPath(BASE_PATH, userID, EMAIL_ALIASES_SUBRESOURCE),
  173. 			params = {
  174. 				body: {
  175. 					email,
  176. 					is_confirmed: false, // don't attempt to autoconfirm aliases for admins by default
  177. 				},
  178. 			};
  180. 		Object.assign(params.body, options);
  182. 		return this.client.wrapWithDefaultHandler(this.client.post)(
  183. 			apiPath,
  184. 			params,
  185. 			callback
  186. 		);
  187. 	}
  189. 	/**
  190. 	 * Remove a linked email address from the current user by alias ID.
  191. 	 *
  192. 	 * API Endpoint: '/users/:id/email_aliases/:aliasID'
  193. 	 * Method: DELETE
  194. 	 *
  195. 	 * @param {string} userID - The ID of the user to remove the email alias from
  196. 	 * @param {string} aliasID - The ID of the linked email alias to remove
  197. 	 * @param {Function} [callback] - Passed nothing on success
  198. 	 * @returns {Promise<void>} A promise resolving to nothing
  199. 	 */
  200. 	removeEmailAlias(userID: string, aliasID: string, callback?: Function) {
  201. 		var apiPath = urlPath(
  202. 			BASE_PATH,
  203. 			userID,
  204. 			EMAIL_ALIASES_SUBRESOURCE,
  205. 			aliasID
  206. 		);
  207. 		return this.client.wrapWithDefaultHandler(this.client.del)(
  208. 			apiPath,
  209. 			null,
  210. 			callback
  211. 		);
  212. 	}
  214. 	/**
  215. 	 * Retrieve a list of group memberships for the user, which show which groups
  216. 	 * the user belongs to.  This ability is restricted to group admins.
  217. 	 *
  218. 	 * API Endpoint: '/users/:userID/memberships'
  219. 	 * Method: GET
  220. 	 *
  221. 	 * @param {string} userID - The ID of the user to get group memberships for
  222. 	 * @param {Object} [options] - Optional parameters, can be left null in most cases
  223. 	 * @param {int} [options.limit] - The number of memberships to retrieve
  224. 	 * @param {int} [options.offset] - Paging marker, retrieve records starting at this position in the list
  225. 	 * @param {Function} [callback] - Passed a list of memberships if successful, error otherwise
  226. 	 * @returns {Promise<Object>} A promise resolving to the collection of group memberships
  227. 	 */
  228. 	getGroupMemberships(
  229. 		userID: string,
  230. 		options?: {
  231. 			limit?: number;
  232. 			offset?: number;
  233. 		},
  234. 		callback?: Function
  235. 	) {
  236. 		var apiPath = urlPath(BASE_PATH, userID, GROUP_MEMBERSHIPS_SUBRESOURCE),
  237. 			params = {
  238. 				qs: options,
  239. 			};
  241. 		return this.client.wrapWithDefaultHandler(this.client.get)(
  242. 			apiPath,
  243. 			params,
  244. 			callback
  245. 		);
  246. 	}
  248. 	/**
  249. 	 * Retrieve the user's avatar image.
  250. 	 *
  251. 	 * API Endpoint: '/users/:userID/avatar'
  252. 	 * Method: GET
  253. 	 *
  254. 	 * @param {string} userID The ID of the user whose avatar should be retrieved
  255. 	 * @param {Function} [callback] Passed a stream over the bytes of the avatar image if successful
  256. 	 * @returns {Promise<Readable>} A promise resolving to the image stream
  257. 	 */
  258. 	getAvatar(userID: string, callback?: Function) {
  259. 		var apiPath = urlPath(BASE_PATH, userID, 'avatar'),
  260. 			params = {
  261. 				streaming: true,
  262. 			};
  264. 		return this.client.get(apiPath, params).asCallback(callback);
  265. 	}
  267. 	/**
  268. 	 * Set the user's avatar image.
  269. 	 *
  270. 	 * API Endpoint: '/users/:userID/avatar'
  271. 	 * Method: POST
  272. 	 *
  273. 	 * @param {string} userID The ID of the user whose avatar should be set
  274. 	 * @param {string|Buffer|ReadStream} avatar - the content of the file. It can be a string, a Buffer, or a read stream
  275. 	 * (like that returned by fs.createReadStream()).
  276. 	 * @param {Function} [callback] Passed dictionary of picture urls if successful
  277. 	 * @returns {Promise<Object>} A promise resolving to the picture urls
  278. 	 */
  279. 	setAvatar(
  280. 		userID: string,
  281. 		avatar: string | Buffer | Readable,
  282. 		callback?: Function
  283. 	) {
  284. 		var apiPath = urlPath(BASE_PATH, userID, 'avatar'),
  285. 			params = {
  286. 				formData: {
  287. 					pic: avatar,
  288. 				},
  289. 			};
  291. 		return this.client.wrapWithDefaultHandler(this.client.post)(
  292. 			apiPath,
  293. 			params,
  294. 			callback
  295. 		);
  296. 	}
  298. 	/**
  299. 	 * Delete the user's avatar image.
  300. 	 *
  301. 	 * API Endpoint: '/users/:userID/avatar'
  302. 	 * Method: DELETE
  303. 	 *
  304. 	 * @param {string} userID The ID of the user whose avatar should be deleted
  305. 	 * @param {Function} [callback] Passed nothing if successful
  306. 	 * @returns {Promise<void>} A promise resolving to nothing
  307. 	 */
  308. 	deleteAvatar(userID: string, callback?: Function) {
  309. 		var apiPath = urlPath(BASE_PATH, userID, 'avatar'),
  310. 			params = {};
  312. 		return this.client.wrapWithDefaultHandler(this.client.del)(
  313. 			apiPath,
  314. 			params,
  315. 			callback
  316. 		);
  317. 	}
  319. 	/**
  320. 	 * Validates the roles and permissions of the user,
  321. 	 * and creates asynchronous jobs to terminate the user's sessions.
  322. 	 *
  323. 	 * API Endpoint: '/users/terminate_sessions'
  324. 	 * Method: POST
  325. 	 *
  326. 	 * @param {Object} options - The user IDs or logins to terminate sessions
  327. 	 * @param {string[]} [options.userIDs] - The user IDs to terminate sessions
  328. 	 * @param {string[]} [options.userLogins] - The user logins to terminate sessions
  329. 	 * @returns {Promise<Object>} A promise resolving a message about the request status.
  330. 	 */
  331. 	terminateSession(options: {
  332. 			userIDs?: string[],
  333. 			userLogins?: string[],
  334. 		},
  335. 		callback?: Function
  336. 	) {
  337. 		var apiPath = urlPath(BASE_PATH, 'terminate_sessions'),
  338. 			params = {
  339. 				body: options
  340. 			};
  341. 		return this.client.wrapWithDefaultHandler(this.client.post)(
  342. 			apiPath,
  343. 			params,
  344. 			callback
  345. 		);
  346. 	}
  347. }
  349. /** @const {string} */
  350. Users.prototype.CURRENT_USER_ID = CURRENT_USER_ID;
  352. /**
  353.  * @module box-node-sdk/lib/managers/users
  354.  * @see {@Link Users}
  355.  */
  356. export = Users;