Source: managers/events.ts

  1. /**
  2.  * @fileoverview Manager for the Box Events Resource
  3.  */
  5. // ------------------------------------------------------------------------------
  6. // Requirements
  7. // ------------------------------------------------------------------------------
  9. import { Promise } from 'bluebird';
  10. import httpStatusCodes from 'http-status';
  11. import BoxClient from '../box-client';
  12. import EnterpriseEventStream from '../enterprise-event-stream';
  13. import EventStream from '../event-stream';
  14. import errors from '../util/errors';
  15. import urlPath from '../util/url-path';
  17. // -----------------------------------------------------------------------------
  18. // Typedefs
  19. // -----------------------------------------------------------------------------
  21. /**
  22.  * Enum of enterprise event types
  23.  *
  24.  * @readonly
  25.  * @enum {EventType}
  26.  */
  27. enum EventType {
  28. 	ADD_DEVICE_ASSOCIATION = 'ADD_DEVICE_ASSOCIATION',
  29. 	ADD_LOGIN_ACTIVITY_DEVICE = 'ADD_LOGIN_ACTIVITY_DEVICE',
  30. 	ADMIN_INVITE_ACCEPT = 'MASTER_INVITE_ACCEPT',
  31. 	ADMIN_INVITE_REJECT = 'MASTER_INVITE_REJECT',
  32. 	ADMIN_LOGIN = 'ADMIN_LOGIN',
  33. 	APPLICATION_PUBLIC_KEY_ADDED = 'APPLICATION_PUBLIC_KEY_ADDED',
  34. 	APPLICATION_PUBLIC_KEY_DELETED = 'APPLICATION_PUBLIC_KEY_DELETED',
  35. 	CHANGE_ADMIN_ROLE = 'CHANGE_ADMIN_ROLE',
  36. 	COLLABORATION_ACCEPT = 'COLLABORATION_ACCEPT',
  37. 	COLLABORATION_EXPIRATION = 'COLLABORATION_EXPIRATION',
  38. 	COLLABORATION_INVITE = 'COLLABORATION_INVITE',
  39. 	COLLABORATION_REMOVE = 'COLLABORATION_REMOVE',
  40. 	COLLABORATION_ROLE_CHANGE = 'COLLABORATION_ROLE_CHANGE',
  41. 	COMMENT_CREATE = 'COMMENT_CREATE',
  42. 	COMMENT_DELETE = 'COMMENT_DELETE',
  43. 	COMMENT_EDIT = 'COMMENT_EDIT',
  44. 	CONTENT_ACCESS = 'CONTENT_ACCESS',
  45. 	CONTENT_WORKFLOW_AUTOMATION_ADD = 'CONTENT_WORKFLOW_AUTOMATION_ADD',
  46. 	CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION = 'CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION',
  47. 	COPY = 'COPY',
  48. 	DELETE = 'DELETE',
  49. 	DELETE_USER = 'DELETE_USER',
  50. 	DOWNLOAD = 'DOWNLOAD',
  51. 	EDIT = 'EDIT',
  52. 	EDIT_USER = 'EDIT_USER',
  53. 	EMAIL_ALIAS_CONFIRM = 'EMAIL_ALIAS_CONFIRM',
  54. 	ENABLE_TWO_FACTOR_AUTH = 'ENABLE_TWO_FACTOR_AUTH',
  55. 	ENTERPRISE_APP_AUTHORIZATION_DELETE = 'ENTERPRISE_APP_AUTHORIZATION_DELETE',
  56. 	FAILED_LOGIN = 'FAILED_LOGIN',
  57. 	FILE_MARKED_MALICIOUS = 'FILE_MARKED_MALICIOUS',
  58. 	FILE_WATERMARKED_DOWNLOAD = 'FILE_WATERMARKED_DOWNLOAD',
  59. 	GROUP_ADD_FILE = 'GROUP_ADD_FILE',
  60. 	GROUP_ADD_FOLDER = 'GROUP_ADD_FOLDER',
  61. 	GROUP_ADD_ITEM = 'GROUP_ADD_ITEM',
  62. 	GROUP_ADD_USER = 'GROUP_ADD_USER',
  63. 	GROUP_CREATION = 'GROUP_CREATION',
  64. 	GROUP_DELETION = 'GROUP_DELETION',
  65. 	GROUP_EDITED = 'GROUP_EDITED',
  66. 	GROUP_REMOVE_FILE = 'GROUP_REMOVE_FILE',
  67. 	GROUP_REMOVE_FOLDER = 'GROUP_REMOVE_FOLDER',
  68. 	GROUP_REMOVE_USER = 'GROUP_REMOVE_USER',
  69. 	ITEM_MODIFY = 'ITEM_MODIFY',
  70. 	ITEM_OPEN = 'ITEM_OPEN',
  71. 	ITEM_SHARED_UPDATE = 'ITEM_SHARED_UPDATE',
  72. 	ITEM_SYNC = 'ITEM_SYNC',
  73. 	ITEM_UNSYNC = 'ITEM_UNSYNC',
  74. 	LOCK = 'LOCK',
  75. 	LOGIN = 'LOGIN',
  76. 	METADATA_INSTANCE_CREATE = 'METADATA_INSTANCE_CREATE',
  77. 	METADATA_INSTANCE_DELETE = 'METADATA_INSTANCE_DELETE',
  78. 	METADATA_INSTANCE_UPDATE = 'METADATA_INSTANCE_UPDATE',
  79. 	METADATA_TEMPLATE_CREATE = 'METADATA_TEMPLATE_CREATE',
  80. 	METADATA_TEMPLATE_UPDATE = 'METADATA_TEMPLATE_UPDATE',
  81. 	MOVE = 'MOVE',
  82. 	NEW_USER = 'NEW_USER',
  83. 	PREVIEW = 'PREVIEW',
  84. 	REMOVE_DEVICE_ASSOCIATION = 'REMOVE_DEVICE_ASSOCIATION',
  85. 	REMOVE_LOGIN_ACTIVITY_DEVICE = 'REMOVE_LOGIN_ACTIVITY_DEVICE',
  86. 	RENAME = 'RENAME',
  87. 	SHARE = 'SHARE',
  88. 	SHARE_EXPIRATION = 'SHARE_EXPIRATION',
  89. 	STORAGE_EXPIRATION = 'STORAGE_EXPIRATION',
  90. 	TASK_ASSIGNMENT_CREATE = 'TASK_ASSIGNMENT_CREATE',
  91. 	TASK_ASSIGNMENT_UPDATE = 'TASK_ASSIGNMENT_UPDATE',
  92. 	TASK_CREATE = 'TASK_CREATE',
  93. 	TERMS_OF_SERVICE_AGREE = 'TERMS_OF_SERVICE_AGREE',
  94. 	TERMS_OF_SERVICE_REJECT = 'TERMS_OF_SERVICE_REJECT',
  95. 	UNDELETE = 'UNDELETE',
  96. 	UNLOCK = 'UNLOCK',
  97. 	UNSHARE = 'UNSHARE',
  98. 	UPDATE_COLLABORATION_EXPIRATION = 'UPDATE_COLLABORATION_EXPIRATION',
  99. 	UPDATE_SHARE_EXPIRATION = 'UPDATE_SHARE_EXPIRATION',
  100. 	UPLOAD = 'UPLOAD',
  101. 	WATERMARK_LABEL_CREATE = 'WATERMARK_LABEL_CREATE',
  102. 	WATERMARK_LABEL_DELETE = 'WATERMARK_LABEL_DELETE',
  103. }
  105. // ------------------------------------------------------------------------------
  106. // Private
  107. // ------------------------------------------------------------------------------
  109. // Base path for all files endpoints
  110. const BASE_PATH = '/events';
  112. /** @const {string} */
  113. const CURRENT_STREAM_POSITION = 'now';
  115. // ------------------------------------------------------------------------------
  116. // Public
  117. // ------------------------------------------------------------------------------
  119. /**
  120.  * Simple manager for interacting with all 'Events' endpoints and actions.
  121.  *
  122.  * @param {BoxClient} client The Box API Client that is responsible for making calls to the API
  123.  * @constructor
  124.  */
  125. class Events {
  126. 	client: BoxClient;
  128. 	CURRENT_STREAM_POSITION!: string;
  129. 	enterpriseEventTypes!: typeof EventType;
  131. 	constructor(client: BoxClient) {
  132. 		// Attach the client, for making API calls
  133. 		this.client = client;
  134. 	}
  136. 	/**
  137. 	 * Get the current stream position.
  138. 	 *
  139. 	 * API Endpoint: '/events'
  140. 	 * Method: GET
  141. 	 *
  142. 	 * @param {Function} [callback] Passed the current stream position if successful
  143. 	 * @returns {Promise<string>} A promise resolving to the stream position
  144. 	 */
  145. 	getCurrentStreamPosition(callback?: Function) {
  146. 		var params = {
  147. 			qs: {
  148. 				stream_position: CURRENT_STREAM_POSITION,
  149. 			},
  150. 		};
  151. 		var apiPath = urlPath(BASE_PATH);
  152. 		return this.client
  153. 			.get(apiPath, params)
  154. 			.then((response: any /* FIXME */) => {
  155. 				if (response.statusCode !== httpStatusCodes.OK) {
  156. 					throw errors.buildUnexpectedResponseError(response);
  157. 				}
  159. 				return response.body.next_stream_position;
  160. 			})
  161. 			.asCallback(callback);
  162. 	}
  164. 	/**
  165. 	 * Get a chunk of events
  166. 	 *
  167. 	 * API Endpoint: '/events'
  168. 	 * Method: GET
  169. 	 *
  170. 	 * To get events from admin events stream you have to pick stream_type from `admin_logs` or `admin_logs_streaming`.
  171. 	 * The `admin_logs` stream emphasis is on completeness over latency,
  172. 	 * which means that Box will deliver admin events in chronological order and without duplicates,
  173. 	 * but with higher latency. You can specify start and end time/dates.
  174. 	 *
  175. 	 * To monitor recent events that have been generated within Box across the enterprise use
  176. 	 * `admin_logs_streaming` as stream type. The emphasis for this feed is on low latency rather than chronological
  177. 	 * accuracy, which means that Box may return events more than once and out of chronological order.
  178. 	 * Events are returned via the API around 12 seconds after they are processed by Box
  179. 	 * (the 12 seconds buffer ensures that new events are not written after your cursor position).
  180. 	 * Only two weeks of events are available via this feed, and you cannot set start and end time/dates.
  181. 	 *
  182. 	 * @param {Object} [options] - Additional options for the request. Can be left null in most cases.
  183. 	 * @param {string} [options.stream_type] - From which stream events should be selected.
  184. 	 * 	Possible values are `admin_logs` and `admin_logs_streaming`
  185. 	 * @param {string} [options.created_after] - The date to start from in ISO-8601 timestamp format: '2001-01-01T00:00:00-08:00'
  186. 	 * @param {string} [options.created_before] - The date to end at in ISO-8601 timestamp format: '2001-01-01T00:00:00-08:00'
  187. 	 * @param {string} [options.event_type] - String of event types to return coma separated: for example 'DOWNLOAD,UPLOAD'
  188. 	 * @param {number} [options.limit] - Number of events to fetch per call
  189. 	 * @param {string} [options.stream_position] - The stream position to start from (pass '0' for all past events)
  190. 	 * @param {Function} [callback] Passed the current stream position if successful
  191. 	 * @returns {Promise<Object>} A promise resolving to the collection of events
  192. 	 */
  193. 	get(options?: {
  194. 		[key: string]: any;
  195. 		stream_type?: string,
  196. 		created_after?: string,
  197. 		created_before?: string,
  198. 		event_type?: string,
  199. 		limit?: number,
  200. 		stream_position?: string
  201. 	}, callback?: Function) {
  202. 		const params = {
  203. 			qs: options,
  204. 		};
  205. 		if(options && options.stream_type && options.stream_type === 'admin_logs_streaming') {
  206. 			const {created_after, created_before, ...filteredOptions} = options;
  207. 			params.qs = filteredOptions;
  208. 		}
  209. 		const apiPath = urlPath(BASE_PATH);
  210. 		return this.client.wrapWithDefaultHandler(this.client.get)(
  211. 			apiPath,
  212. 			params,
  213. 			callback
  214. 		);
  215. 	}
  217. 	/**
  218. 	 * Get information for long-polling until new events are available
  219. 	 *
  220. 	 * API Endpoint: '/events'
  221. 	 * Method: OPTIONS
  222. 	 *
  223. 	 * @param {Function} [callback] Passed the long poll info if successful
  224. 	 * @returns {Promise<Object>} A promise resolving to the long poll info
  225. 	 */
  226. 	getLongPollInfo(callback?: Function) {
  227. 		const apiPath = urlPath(BASE_PATH);
  228. 		return this.client
  229. 			.options(apiPath, {})
  230. 			.then((response: any /* FIXME */) => {
  231. 				if (response.statusCode !== httpStatusCodes.OK) {
  232. 					throw errors.buildUnexpectedResponseError(response);
  233. 				}
  235. 				let longpollInfo = response.body.entries.find(
  236. 					(entry: any /* FIXME */) => entry.type === 'realtime_server'
  237. 				);
  239. 				if (!longpollInfo) {
  240. 					throw errors.buildResponseError(
  241. 						'No valid long poll server specified',
  242. 						response
  243. 					);
  244. 				}
  246. 				return longpollInfo;
  247. 			})
  248. 			.asCallback(callback);
  249. 	}
  251. 	/**
  252. 	 * Create a stream of events, using the long-poll API to wait for new events.
  253. 	 *
  254. 	 * API Endpoint: '/events'
  255. 	 * Method: OPTIONS
  256. 	 *
  257. 	 * @param {string} [streamPosition] Starting stream position
  258. 	 * @param {Object} [options] Optional parameters for the event stream
  259. 	 * @param {int} [options.retryDelay=1000] Number of ms to wait before retrying after an error
  260. 	 * @param {int} [options.deduplicationFilterSize=5000] Number of IDs to track for deduplication
  261. 	 * @param {int} [options.fetchInterval=1000] Minimunm number of ms between calls for more events
  262. 	 * @param {Function} [callback] Passed the events stream if successful
  263. 	 * @returns {Promise<EventStream>} A promise resolving to the event stream
  264. 	 */
  265. 	getEventStream(
  266. 		streamPosition: string,
  267. 		options?:
  268. 			| {
  269. 					retryDelay?: number;
  270. 					deduplicationFilterSize?: number;
  271. 					fetchInterval?: number;
  272. 			  }
  273. 			| Function,
  274. 		callback?: Function
  275. 	) {
  276. 		const self = this;
  277. 		if (typeof streamPosition === 'string') {
  278. 			if (typeof options === 'function') {
  279. 				callback = options;
  280. 				options = {};
  281. 			}
  283. 			return Promise.resolve(
  284. 				new EventStream(self.client, streamPosition, options)
  285. 			).asCallback(callback);
  286. 		}
  288. 		// Fix up optional arguments
  289. 		callback = options as any /* FIXME */;
  290. 		options = streamPosition;
  291. 		if (typeof options === 'function') {
  292. 			callback = options;
  293. 			options = {};
  294. 		}
  296. 		return this.getCurrentStreamPosition()
  297. 			.then(
  298. 				(currentStreamPosition: any /* FIXME */) =>
  299. 					new EventStream(
  300. 						self.client,
  301. 						currentStreamPosition,
  302. 						options as Record<string, any>
  303. 					)
  304. 			)
  305. 			.asCallback(callback);
  306. 	}
  308. 	/**
  309. 	 * Create a stream of enterprise events.
  310. 	 *
  311. 	 * By default, the stream starts from the current time.
  312. 	 * Pass 'startDate' to start from a specific time.
  313. 	 * Pass 'streamPosition' to start from a previous stream position, or '0' for all available past events (~1 year).
  314. 	 * Once the stream catches up to the current time, it will begin polling every 'pollingInterval' seconds.
  315. 	 * If 'pollingInterval' = 0, then the stream will end when it catches up to the current time (no polling).
  316. 	 *
  317. 	 * By default, stream pools `admin_logs` for events. The emphasis for this stream is on completeness over latency,
  318. 	 * which means that Box will deliver admin events in chronological order and without duplicates,
  319. 	 * but with higher latency. You can specify start and end time/dates.
  320. 	 *
  321. 	 * To monitor recent events that have been generated within Box across the enterprise use
  322. 	 * `admin_logs_streaming` as stream type. The emphasis for this feed is on low latency rather than chronological
  323. 	 * accuracy, which means that Box may return events more than once and out of chronological order.
  324. 	 * Events are returned via the API around 12 seconds after they are processed by Box
  325. 	 * (the 12 seconds buffer ensures that new events are not written after your cursor position).
  326. 	 * Only two weeks of events are available via this feed, and you cannot set start and end time/dates.
  327. 	 *
  328. 	 * This method will only work with an API connection for an enterprise admin account
  329. 	 * or service account with a manage enterprise properties.
  330. 	 *
  331. 	 * @param {Object} [options] - Options
  332. 	 * @param {string} [options.streamPosition] - The stream position to start from (pass '0' for all past events)
  333. 	 * @param {string} [options.startDate] - The date to start from
  334. 	 * @param {string} [options.endDate] - The date to end at
  335. 	 * @param {EventType[]} [options.eventTypeFilter] - Array of event types to return
  336. 	 * @param {int} [options.pollingInterval=60] - Polling interval (in seconds).  Pass 0 for no polling.
  337. 	 * @param {int} [options.chunkSize=500] - Number of events to fetch per call (max = 500)
  338. 	 * @param {string} [options.streamType] - From which stream events should be selected.
  339. 	 * 	Possible values are `admin_logs` and `admin_logs_streaming`
  340. 	 * @param {Function} [callback] Passed the events stream if successful
  341. 	 * @returns {Promise<EnterpriseEventStream>} A promise resolving to the enterprise event stream
  342. 	 */
  343. 	getEnterpriseEventStream(
  344. 		options?: {
  345. 			streamPosition?: string;
  346. 			startDate?: string;
  347. 			endDate?: string;
  348. 			eventTypeFilter?: EventType[];
  349. 			pollingInterval?: number;
  350. 			chunkSize?: number;
  351. 			streamType?: 'admin_logs' | 'admin_logs_streaming';
  352. 		},
  353. 		callback?: Function
  354. 	) {
  355. 		const self = this;
  356. 		return Promise.resolve(
  357. 			new EnterpriseEventStream(self.client, options)
  358. 		).asCallback(callback);
  359. 	}
  360. }
  362. Events.prototype.CURRENT_STREAM_POSITION = CURRENT_STREAM_POSITION;
  364. Events.prototype.enterpriseEventTypes = EventType;
  366. export = Events;