box-node-sdk 1.36.0 → 1.38.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (126) hide show
  1. package/CHANGELOG.md +45 -3
  2. package/README.md +3 -1
  3. package/lib/api-request-manager.d.ts +38 -0
  4. package/lib/api-request-manager.js +48 -55
  5. package/lib/api-request-manager.js.map +1 -0
  6. package/lib/api-request.d.ts +137 -0
  7. package/lib/api-request.js +202 -281
  8. package/lib/api-request.js.map +1 -0
  9. package/lib/box-client.d.ts +269 -0
  10. package/lib/box-client.js +551 -713
  11. package/lib/box-client.js.map +1 -0
  12. package/lib/box-node-sdk.d.ts +216 -0
  13. package/lib/box-node-sdk.js +317 -352
  14. package/lib/box-node-sdk.js.map +1 -0
  15. package/lib/chunked-uploader.d.ts +129 -0
  16. package/lib/chunked-uploader.js +287 -358
  17. package/lib/chunked-uploader.js.map +1 -0
  18. package/lib/enterprise-event-stream.d.ts +82 -0
  19. package/lib/enterprise-event-stream.js +189 -203
  20. package/lib/enterprise-event-stream.js.map +1 -0
  21. package/lib/event-stream.d.ts +92 -0
  22. package/lib/event-stream.js +274 -302
  23. package/lib/event-stream.js.map +1 -0
  24. package/lib/managers/collaboration-allowlist.d.ts +137 -0
  25. package/lib/managers/collaboration-allowlist.js +200 -0
  26. package/lib/managers/collaboration-allowlist.js.map +1 -0
  27. package/lib/managers/collaboration-whitelist.d.ts +3 -0
  28. package/lib/managers/collaboration-whitelist.js +8 -222
  29. package/lib/managers/collaboration-whitelist.js.map +1 -0
  30. package/lib/managers/collaborations.d.ts +166 -0
  31. package/lib/managers/collaborations.js +225 -258
  32. package/lib/managers/collaborations.js.map +1 -0
  33. package/lib/managers/collections.d.ts +42 -0
  34. package/lib/managers/collections.js +45 -50
  35. package/lib/managers/collections.js.map +1 -0
  36. package/lib/managers/comments.d.ts +103 -0
  37. package/lib/managers/comments.js +158 -173
  38. package/lib/managers/comments.js.map +1 -0
  39. package/lib/managers/device-pins.d.ts +52 -0
  40. package/lib/managers/device-pins.js +75 -88
  41. package/lib/managers/device-pins.js.map +1 -0
  42. package/lib/managers/enterprise.d.ts +162 -0
  43. package/lib/managers/enterprise.js +168 -199
  44. package/lib/managers/enterprise.js.map +1 -0
  45. package/lib/managers/events.d.ts +179 -0
  46. package/lib/managers/events.js +232 -254
  47. package/lib/managers/events.js.map +1 -0
  48. package/lib/managers/files.d.ts +773 -0
  49. package/lib/managers/files.js +1401 -1602
  50. package/lib/managers/files.js.map +1 -0
  51. package/lib/managers/folders.d.ts +347 -0
  52. package/lib/managers/folders.js +551 -630
  53. package/lib/managers/folders.js.map +1 -0
  54. package/lib/managers/groups.d.ts +202 -0
  55. package/lib/managers/groups.js +238 -288
  56. package/lib/managers/groups.js.map +1 -0
  57. package/lib/managers/legal-hold-policies.d.ts +190 -0
  58. package/lib/managers/legal-hold-policies.js +228 -272
  59. package/lib/managers/legal-hold-policies.js.map +1 -0
  60. package/lib/managers/metadata.d.ts +228 -0
  61. package/lib/managers/metadata.js +265 -328
  62. package/lib/managers/metadata.js.map +1 -0
  63. package/lib/managers/recent-items.d.ts +38 -0
  64. package/lib/managers/recent-items.js +32 -39
  65. package/lib/managers/recent-items.js.map +1 -0
  66. package/lib/managers/retention-policies.d.ts +251 -0
  67. package/lib/managers/retention-policies.js +278 -281
  68. package/lib/managers/retention-policies.js.map +1 -0
  69. package/lib/managers/search.d.ts +82 -0
  70. package/lib/managers/search.js +68 -88
  71. package/lib/managers/search.js.map +1 -0
  72. package/lib/managers/shared-items.d.ts +33 -0
  73. package/lib/managers/shared-items.js +54 -62
  74. package/lib/managers/shared-items.js.map +1 -0
  75. package/lib/managers/storage-policies.d.ts +86 -0
  76. package/lib/managers/storage-policies.js +108 -142
  77. package/lib/managers/storage-policies.js.map +1 -0
  78. package/lib/managers/tasks.d.ts +161 -0
  79. package/lib/managers/tasks.js +219 -260
  80. package/lib/managers/tasks.js.map +1 -0
  81. package/lib/managers/terms-of-service.d.ts +161 -0
  82. package/lib/managers/terms-of-service.js +250 -273
  83. package/lib/managers/terms-of-service.js.map +1 -0
  84. package/lib/managers/trash.d.ts +30 -0
  85. package/lib/managers/trash.js +30 -41
  86. package/lib/managers/trash.js.map +1 -0
  87. package/lib/managers/users.d.ts +130 -0
  88. package/lib/managers/users.js +160 -203
  89. package/lib/managers/users.js.map +1 -0
  90. package/lib/managers/web-links.d.ts +127 -0
  91. package/lib/managers/web-links.js +183 -209
  92. package/lib/managers/web-links.js.map +1 -0
  93. package/lib/managers/webhooks.d.ts +166 -0
  94. package/lib/managers/webhooks.js +312 -305
  95. package/lib/managers/webhooks.js.map +1 -0
  96. package/lib/sessions/anonymous-session.d.ts +69 -0
  97. package/lib/sessions/anonymous-session.js +88 -102
  98. package/lib/sessions/anonymous-session.js.map +1 -0
  99. package/lib/sessions/app-auth-session.d.ts +92 -0
  100. package/lib/sessions/app-auth-session.js +140 -160
  101. package/lib/sessions/app-auth-session.js.map +1 -0
  102. package/lib/sessions/basic-session.d.ts +56 -0
  103. package/lib/sessions/basic-session.js +40 -50
  104. package/lib/sessions/basic-session.js.map +1 -0
  105. package/lib/sessions/persistent-session.d.ts +96 -0
  106. package/lib/sessions/persistent-session.js +191 -211
  107. package/lib/sessions/persistent-session.js.map +1 -0
  108. package/lib/token-manager.d.ts +191 -0
  109. package/lib/token-manager.js +390 -465
  110. package/lib/token-manager.js.map +1 -0
  111. package/lib/util/config.d.ts +86 -0
  112. package/lib/util/config.js +146 -152
  113. package/lib/util/config.js.map +1 -0
  114. package/lib/util/errors.d.ts +50 -0
  115. package/lib/util/errors.js +134 -145
  116. package/lib/util/errors.js.map +1 -0
  117. package/lib/util/exponential-backoff.d.ts +11 -0
  118. package/lib/util/exponential-backoff.js +10 -22
  119. package/lib/util/exponential-backoff.js.map +1 -0
  120. package/lib/util/paging-iterator.d.ts +53 -0
  121. package/lib/util/paging-iterator.js +202 -218
  122. package/lib/util/paging-iterator.js.map +1 -0
  123. package/lib/util/url-path.d.ts +16 -0
  124. package/lib/util/url-path.js +20 -35
  125. package/lib/util/url-path.js.map +1 -0
  126. package/package.json +14 -3
package/lib/box-client.js CHANGED
@@ -1,87 +1,29 @@
1
+ "use strict";
1
2
  /**
2
3
  * @fileoverview Box API Client
3
4
  */
4
-
5
- 'use strict';
6
-
7
-
8
- // ------------------------------------------------------------------------------
9
- // Typedefs and Callbacks
10
- // ------------------------------------------------------------------------------
11
-
12
- /**
13
- * A collaboration role constant
14
- * @typedef {string} CollaborationRole
15
- */
16
-
17
- /**
18
- * A Box file or folder type constant
19
- * @typedef {string} ItemType
20
- */
21
-
22
- /**
23
- * An access level constant. Used for setting and updating shared links, folder upload, etc.
24
- * @typedef {?Object} AccessLevel
25
- */
26
-
5
+ var bluebird_1 = require("bluebird");
27
6
  // ------------------------------------------------------------------------------
28
7
  // Requirements
29
8
  // ------------------------------------------------------------------------------
30
- var util = require('util'),
31
- qs = require('querystring'),
32
- errors = require('./util/errors'),
33
- httpStatusCodes = require('http-status'),
34
- isIP = require('net').isIP,
35
- merge = require('merge-options'),
36
- PagingIterator = require('./util/paging-iterator'),
37
- Promise = require('bluebird'),
38
- pkg = require('../package.json');
39
-
9
+ var util = require('util'), qs = require('querystring'), errors = require('./util/errors'), httpStatusCodes = require('http-status'), isIP = require('net').isIP, merge = require('merge-options'), PagingIterator = require('./util/paging-iterator'), pkg = require('../package.json');
40
10
  // API Resource Managers
41
- var Users = require('./managers/users'),
42
- Files = require('./managers/files'),
43
- Folders = require('./managers/folders'),
44
- Collaborations = require('./managers/collaborations'),
45
- Groups = require('./managers/groups'),
46
- Comments = require('./managers/comments'),
47
- SharedItems = require('./managers/shared-items'),
48
- Metadata = require('./managers/metadata'),
49
- Collections = require('./managers/collections'),
50
- Events = require('./managers/events'),
51
- Search = require('./managers/search'),
52
- Tasks = require('./managers/tasks'),
53
- Trash = require('./managers/trash'),
54
- Enterprise = require('./managers/enterprise'),
55
- LegalHoldPolicies = require('./managers/legal-hold-policies'),
56
- WebLinks = require('./managers/web-links'),
57
- RetentionPolicies = require('./managers/retention-policies'),
58
- DevicePins = require('./managers/device-pins'),
59
- Webhooks = require('./managers/webhooks'),
60
- RecentItems = require('./managers/recent-items'),
61
- CollaborationWhitelist = require('./managers/collaboration-whitelist'),
62
- TermsOfService = require('./managers/terms-of-service'),
63
- StoragePolicies = require('./managers/storage-policies');
64
-
11
+ var Users = require('./managers/users'), Files = require('./managers/files'), Folders = require('./managers/folders'), Collaborations = require('./managers/collaborations'), Groups = require('./managers/groups'), Comments = require('./managers/comments'), SharedItems = require('./managers/shared-items'), Metadata = require('./managers/metadata'), Collections = require('./managers/collections'), Events = require('./managers/events'), Search = require('./managers/search'), Tasks = require('./managers/tasks'), Trash = require('./managers/trash'), Enterprise = require('./managers/enterprise'), LegalHoldPolicies = require('./managers/legal-hold-policies'), WebLinks = require('./managers/web-links'), RetentionPolicies = require('./managers/retention-policies'), DevicePins = require('./managers/device-pins'), Webhooks = require('./managers/webhooks'), RecentItems = require('./managers/recent-items'), CollaborationAllowlist = require('./managers/collaboration-allowlist'), TermsOfService = require('./managers/terms-of-service'), StoragePolicies = require('./managers/storage-policies');
65
12
  // ------------------------------------------------------------------------------
66
13
  // Private
67
14
  // ------------------------------------------------------------------------------
68
-
69
- // The Authorization header label
70
- var HEADER_AUTHORIZATION = 'Authorization',
71
- // Prefix our token with this string in the Authorization header
72
- HEADER_AUTHORIZATION_PREFIX = 'Bearer ',
73
- // The 'BoxApi' header label
74
- HEADER_BOXAPI = 'BoxApi',
75
- // The XFF header label - Used to give the API better information for uploads, rate-limiting, etc.
76
- HEADER_XFF = 'X-Forwarded-For',
77
- // As-User header
78
- HEADER_AS_USER = 'As-User',
79
- // Range of SUCCESS http status codes
80
- HTTP_STATUS_CODE_SUCCESS_BLOCK_RANGE = [
81
- 200,
82
- 299
83
- ];
84
-
15
+ // The Authorization header label
16
+ var HEADER_AUTHORIZATION = 'Authorization',
17
+ // Prefix our token with this string in the Authorization header
18
+ HEADER_AUTHORIZATION_PREFIX = 'Bearer ',
19
+ // The 'BoxApi' header label
20
+ HEADER_BOXAPI = 'BoxApi',
21
+ // The XFF header label - Used to give the API better information for uploads, rate-limiting, etc.
22
+ HEADER_XFF = 'X-Forwarded-For',
23
+ // As-User header
24
+ HEADER_AS_USER = 'As-User',
25
+ // Range of SUCCESS http status codes
26
+ HTTP_STATUS_CODE_SUCCESS_BLOCK_RANGE = [200, 299];
85
27
  /**
86
28
  * Build the 'Authorization' Header for the API
87
29
  *
@@ -90,31 +32,26 @@ var HEADER_AUTHORIZATION = 'Authorization',
90
32
  * @private
91
33
  */
92
34
  function buildAuthorizationHeader(accessToken) {
93
- return HEADER_AUTHORIZATION_PREFIX + accessToken;
35
+ return HEADER_AUTHORIZATION_PREFIX + accessToken;
94
36
  }
95
-
96
37
  /**
97
38
  * Returns true iff the response is a 401 UNAUTHORIZED that is caused by an expired access token.
98
39
  * @param {APIRequest~ResponseObject} response - The response returned by an APIRequestManager request
99
40
  * @returns {boolean} - true iff the response is a 401 UNAUTHORIZED caused by an expired access token
100
41
  * @private
101
42
  */
102
- function isUnauthorizedDueToExpiredAccessToken(response) {
103
- // There are three cases to consider:
104
- // 1) The response body is a Buffer. This indicates that the request was malformed (i.e. malformed url) so return false.
105
- // 2) The status code is UNAUTHORIZED and the response body is an empty object or null. This indicates that the access tokens are expired, so return true.
106
- // 3) The status code is UNAUTHORIZED and the response body is a non-empty object. This indicates that the 401 was returned for some reason other
107
- // than expired tokens, so return false.
108
-
109
- if (Buffer.isBuffer(response.body)) {
110
- return false;
111
- }
112
-
113
- var isResponseStatusCodeUnauthorized = response.statusCode === httpStatusCodes.UNAUTHORIZED,
114
- isResponseBodyEmpty = !response.body || Object.getOwnPropertyNames(response.body).length === 0;
115
- return isResponseStatusCodeUnauthorized && isResponseBodyEmpty;
43
+ function isUnauthorizedDueToExpiredAccessToken(response /* FIXME */) {
44
+ // There are three cases to consider:
45
+ // 1) The response body is a Buffer. This indicates that the request was malformed (i.e. malformed url) so return false.
46
+ // 2) The status code is UNAUTHORIZED and the response body is an empty object or null. This indicates that the access tokens are expired, so return true.
47
+ // 3) The status code is UNAUTHORIZED and the response body is a non-empty object. This indicates that the 401 was returned for some reason other
48
+ // than expired tokens, so return false.
49
+ if (Buffer.isBuffer(response.body)) {
50
+ return false;
51
+ }
52
+ var isResponseStatusCodeUnauthorized = response.statusCode === httpStatusCodes.UNAUTHORIZED, isResponseBodyEmpty = !response.body || Object.getOwnPropertyNames(response.body).length === 0;
53
+ return isResponseStatusCodeUnauthorized && isResponseBodyEmpty;
116
54
  }
117
-
118
55
  /**
119
56
  * Returns a full URL. If the url argument begins with http:// or https://, then url is simply returned.
120
57
  * Otherwise, the defaultBasePath is prepended to url and returned.
@@ -125,12 +62,11 @@ function isUnauthorizedDueToExpiredAccessToken(response) {
125
62
  * @private
126
63
  */
127
64
  function getFullURL(defaultBasePath, url) {
128
- if (/^https?:\/\//.test(url)) {
129
- return url;
130
- }
131
- return defaultBasePath + url;
65
+ if (/^https?:\/\//.test(url)) {
66
+ return url;
67
+ }
68
+ return defaultBasePath + url;
132
69
  }
133
-
134
70
  /**
135
71
  * Create a valid request object for the Batch API from a standard request
136
72
  * params object
@@ -139,17 +75,14 @@ function getFullURL(defaultBasePath, url) {
139
75
  * @private
140
76
  */
141
77
  function formatRequestForBatch(params) {
142
-
143
- var relativePath = params.url.replace(/^http.*?\/\d\.\d\//, '/');
144
-
145
- return {
146
- method: params.method,
147
- relative_url: relativePath + (params.qs ? `?${qs.stringify(params.qs)}` : ''),
148
- body: params.body,
149
- headers: params.headers
150
- };
78
+ var relativePath = params.url.replace(/^http.*?\/\d\.\d\//, '/');
79
+ return {
80
+ method: params.method,
81
+ relative_url: relativePath + (params.qs ? "?" + qs.stringify(params.qs) : ''),
82
+ body: params.body,
83
+ headers: params.headers,
84
+ };
151
85
  }
152
-
153
86
  /**
154
87
  * Format a Batch API response object into a standard request response
155
88
  * for use in response handling
@@ -157,201 +90,512 @@ function formatRequestForBatch(params) {
157
90
  * @returns {Object} The standard response object
158
91
  * @private
159
92
  */
160
- function formatResponseForBatch(response) {
161
-
162
- return {
163
- statusCode: response.status,
164
- headers: response.headers,
165
- body: response.response
166
- };
93
+ function formatResponseForBatch(response /* FIXME */) {
94
+ return {
95
+ statusCode: response.status,
96
+ headers: response.headers,
97
+ body: response.response,
98
+ };
167
99
  }
168
-
169
100
  /**
170
101
  * Construct the X-Box-UA header to send analytics identifiers
171
102
  * @param {Object} [client] Analytics client information
172
103
  * @returns {string} The header value
173
104
  */
174
- function constructBoxUAHeader(client) {
175
-
176
- var analyticsIdentifiers = {
177
- agent: `box-node-sdk/${pkg.version}`,
178
- env: `Node/${process.version.replace('v', '')}`
179
- };
180
-
181
- if (client) {
182
- analyticsIdentifiers.client = `${client.name}/${client.version}`;
183
- }
184
-
185
- return Object.keys(analyticsIdentifiers).map(k => `${k}=${analyticsIdentifiers[k]}`)
186
- .join('; ');
105
+ function constructBoxUAHeader(client /* FIXME */) {
106
+ var analyticsIdentifiers = {
107
+ agent: "box-node-sdk/" + pkg.version,
108
+ env: "Node/" + process.version.replace('v', ''),
109
+ };
110
+ if (client) {
111
+ analyticsIdentifiers.client = client.name + "/" + client.version;
112
+ }
113
+ return Object.keys(analyticsIdentifiers)
114
+ .map(function (k) { return k + "=" + analyticsIdentifiers[k]; })
115
+ .join('; ');
187
116
  }
188
-
189
- /**
190
- * The BoxClient can make API calls on behalf of a valid API Session. It is responsible
191
- * for formatting the requests and handling the response. Its goal is to deliver
192
- * sensible results to the user.
193
- *
194
- * @param {APISession} apiSession An initialized API Session, used to get/revoke tokens and handle
195
- * unauthorized responses from the API.
196
- * @param {Config} config The SDK configuration options
197
- * @param {APIRequestManager} requestManager The API Request Manager
198
- * @constructor
199
- */
200
- function BoxClient(apiSession, config, requestManager) {
201
- // the API Session used by the client for authentication
202
- this._session = apiSession;
203
-
204
- // Attach a request manager instance for making requests
205
- this._requestManager = requestManager;
206
-
207
- // An object of custom headers to apply to every request. Modified via BoxClient.setCustomHeader().
208
- this._customHeaders = {};
209
- // Attach the configured properties
210
- this._baseURL = util.format('%s/%s', config.apiRootURL, config.apiVersion);
211
- this._uploadBaseURL = util.format('%s/%s', config.uploadAPIRootURL, config.apiVersion);
212
- this._uploadRequestTimeoutMS = config.uploadRequestTimeoutMS;
213
- this._useIterators = config.iterators;
214
- this._analyticsClient = config.analyticsClient;
215
-
216
- // Attach API Resource Managers
217
- this.users = new Users(this);
218
- this.files = new Files(this);
219
- this.folders = new Folders(this);
220
- this.comments = new Comments(this);
221
- this.collaborations = new Collaborations(this);
222
- this.groups = new Groups(this);
223
- this.sharedItems = new SharedItems(this);
224
- this.metadata = new Metadata(this);
225
- this.collections = new Collections(this);
226
- this.events = new Events(this);
227
- this.search = new Search(this);
228
- this.tasks = new Tasks(this);
229
- this.trash = new Trash(this);
230
- this.enterprise = new Enterprise(this);
231
- this.legalHoldPolicies = new LegalHoldPolicies(this);
232
- this.weblinks = new WebLinks(this);
233
- this.retentionPolicies = new RetentionPolicies(this);
234
- this.devicePins = new DevicePins(this);
235
- this.webhooks = new Webhooks(this);
236
- this.recentItems = new RecentItems(this);
237
- this.collaborationWhitelist = new CollaborationWhitelist(this);
238
- this.termsOfService = new TermsOfService(this);
239
- this.storagePolicies = new StoragePolicies(this);
240
-
241
- // Array of requests when in batch mode, null otherwise
242
- this._batch = null;
243
- }
244
-
245
- /**
246
- * Returns an object containing the given headers as well as other headers (like the authorization header and
247
- * custom headers) that should be included in a request.
248
- * @param {?Object} callerHeaders - headers that the caller wishes to include in the request. This method will not
249
- * override these headers with its own. Thus, if all the headers that this method was planning to add are already
250
- * specified here, this method will return an object with exactly the same headers.
251
- * @param {string} accessToken - the access token that will be used to make the request
252
- * @returns {Object} - a new object with the headers needed for the request
253
- * @private
254
- */
255
- BoxClient.prototype._createHeadersForRequest = function(callerHeaders, accessToken) {
256
- var headers = {};
257
-
258
- // 'Authorization' - contains your valid access token for authorization
259
- headers[HEADER_AUTHORIZATION] = buildAuthorizationHeader(accessToken);
260
-
261
- // We copy our own custom headers (XFF, BoxApi, etc.) before copying over the caller-specified headers so that
262
- // the caller-specified headers will take precedence.
263
- Object.assign(headers, this._customHeaders, callerHeaders);
264
-
265
- // Add analytics headers last so they cannot be overwritten
266
- Object.assign(headers, { 'X-Box-UA': constructBoxUAHeader(this._analyticsClient) });
267
-
268
- return headers;
269
- };
270
-
271
- /**
272
- * Makes an API request to the Box API on behalf of the client. Before executing
273
- * the request, it first ensures the user has usable tokens. Will be called again
274
- * if the request returns a temporary error. Will propogate error if request returns
275
- * a permanent error, or if usable tokens are not available.
276
- *
277
- * @param {Object} params - Request lib params to configure the request
278
- * @param {APIRequest~Callback} [callback] - passed response data
279
- * @returns {Promise} Promise resolving to the response
280
- * @private
281
- */
282
- BoxClient.prototype._makeRequest = function(params, callback) {
283
-
284
- var promise;
285
-
286
- if (this._batch) {
287
-
288
- // eslint-disable-next-line promise/avoid-new
289
- promise = new Promise((resolve, reject) => {
290
- this._batch.push({ params, resolve, reject });
291
- });
292
- } else {
293
-
294
- // Check that tokens are fresh, update if tokens are expired or soon-to-be expired
295
- promise = this._session.getAccessToken(this._tokenOptions)
296
- .then(accessToken => {
297
-
298
- params.headers = this._createHeadersForRequest(params.headers, accessToken);
299
-
300
- if (params.streaming) {
301
- // streaming is specific to the SDK, so delete it from params before continuing
302
- delete params.streaming;
303
- var responseStream = this._requestManager.makeStreamingRequest(params);
304
- // Listen to 'response' event, so we can cleanup the token store in case when the request is unauthorized
305
- // due to expired access token
306
- responseStream.on('response', response => {
307
- if (isUnauthorizedDueToExpiredAccessToken(response)) {
308
-
309
- var expiredTokensError = errors.buildAuthError(response);
310
-
311
- // Give the session a chance to handle the error (ex: a persistent session will clear the token store)
312
- if (this._session.handleExpiredTokensError) {
313
- this._session.handleExpiredTokensError(expiredTokensError);
314
- }
315
- }
316
- });
317
-
318
- return responseStream;
319
- }
320
-
321
- // Make the request to Box, and perform standard response handling
322
- return this._requestManager.makeRequest(params);
323
- });
324
- }
325
-
326
- return promise
327
- .then(response => {
328
-
329
- if (!response.statusCode) {
330
- // Response is not yet complete, and is just a stream that will return the response later
331
- // Just return the stream, since it doesn't need further response handling
332
- return response;
333
- }
334
-
335
- if (isUnauthorizedDueToExpiredAccessToken(response)) {
336
- var expiredTokensError = errors.buildAuthError(response);
337
-
338
- // Give the session a chance to handle the error (ex: a persistent session will clear the token store)
339
- if (this._session.handleExpiredTokensError) {
340
- return this._session.handleExpiredTokensError(expiredTokensError);
341
- }
342
-
343
- throw expiredTokensError;
344
- }
345
-
346
- return response;
347
- })
348
- .asCallback(callback);
349
- };
350
-
117
+ var BoxClient = /** @class */ (function () {
118
+ /**
119
+ * The BoxClient can make API calls on behalf of a valid API Session. It is responsible
120
+ * for formatting the requests and handling the response. Its goal is to deliver
121
+ * sensible results to the user.
122
+ *
123
+ * @param {APISession} apiSession An initialized API Session, used to get/revoke tokens and handle
124
+ * unauthorized responses from the API.
125
+ * @param {Config} config The SDK configuration options
126
+ * @param {APIRequestManager} requestManager The API Request Manager
127
+ * @constructor
128
+ */
129
+ function BoxClient(apiSession, config /* FIXME */, requestManager) {
130
+ /**
131
+ * Puts the client into batch mode, which will queue calls instead of
132
+ * immediately making the API request.
133
+ *
134
+ * DEPRECATED: Batch API is not supported and should not be used; make calls in parallel instead.
135
+ *
136
+ * @returns {BoxClient} Current client object
137
+ */
138
+ this.batch = util.deprecate(function () {
139
+ /* eslint-disable no-invalid-this */
140
+ this._batch = [];
141
+ return this;
142
+ /* eslint-enable no-invalid-this */
143
+ }, 'Batch API is not supported and should not be used; make calls in parallel instead.');
144
+ /**
145
+ * Executes a batch of requests.
146
+ *
147
+ * DEPRECATED: Batch API is not supported and should not be used; make calls in parallel instead.
148
+ *
149
+ * @returns {Promise<Object>} Promise resolving to the collection of batch responses
150
+ */
151
+ this.batchExec = util.deprecate(function (callback) {
152
+ /* eslint-disable no-invalid-this */
153
+ if (!this._batch) {
154
+ return bluebird_1.Promise.reject(new Error('Must start a batch before executing')).asCallback(callback);
155
+ }
156
+ var params = {
157
+ body: {
158
+ requests: this._batch.map(function (batchReq /* FIXME */) {
159
+ return formatRequestForBatch(batchReq.params);
160
+ }),
161
+ },
162
+ };
163
+ var batch = this._batch;
164
+ this._batch = null;
165
+ return this.post('/batch', params)
166
+ .then(function (res /* FIXME */) {
167
+ var responses = res.body.responses;
168
+ responses
169
+ .map(function (x) { return formatResponseForBatch(x); })
170
+ .forEach(function (response, index) {
171
+ batch[index].resolve(response);
172
+ });
173
+ return res.body;
174
+ })
175
+ .catch(function (err) {
176
+ batch.forEach(function (req) { return req.reject(err); });
177
+ throw err;
178
+ })
179
+ .asCallback(callback);
180
+ /* eslint-enable no-invalid-this */
181
+ }, 'Batch API is not supported and should not be used; make calls in parallel instead.');
182
+ // the API Session used by the client for authentication
183
+ this._session = apiSession;
184
+ // Attach a request manager instance for making requests
185
+ this._requestManager = requestManager;
186
+ // An object of custom headers to apply to every request. Modified via BoxClient.setCustomHeader().
187
+ this._customHeaders = {};
188
+ // Attach the configured properties
189
+ this._baseURL = util.format('%s/%s', config.apiRootURL, config.apiVersion);
190
+ this._uploadBaseURL = util.format('%s/%s', config.uploadAPIRootURL, config.apiVersion);
191
+ this._uploadRequestTimeoutMS = config.uploadRequestTimeoutMS;
192
+ this._useIterators = config.iterators;
193
+ this._analyticsClient = config.analyticsClient;
194
+ // Attach API Resource Managers
195
+ this.users = new Users(this);
196
+ this.files = new Files(this);
197
+ this.folders = new Folders(this);
198
+ this.comments = new Comments(this);
199
+ this.collaborations = new Collaborations(this);
200
+ this.groups = new Groups(this);
201
+ this.sharedItems = new SharedItems(this);
202
+ this.metadata = new Metadata(this);
203
+ this.collections = new Collections(this);
204
+ this.events = new Events(this);
205
+ this.search = new Search(this);
206
+ this.tasks = new Tasks(this);
207
+ this.trash = new Trash(this);
208
+ this.enterprise = new Enterprise(this);
209
+ this.legalHoldPolicies = new LegalHoldPolicies(this);
210
+ this.weblinks = new WebLinks(this);
211
+ this.retentionPolicies = new RetentionPolicies(this);
212
+ this.devicePins = new DevicePins(this);
213
+ this.webhooks = new Webhooks(this);
214
+ this.recentItems = new RecentItems(this);
215
+ this.collaborationAllowlist = new CollaborationAllowlist(this);
216
+ this.termsOfService = new TermsOfService(this);
217
+ this.storagePolicies = new StoragePolicies(this);
218
+ // Legacy insensitive language
219
+ this.collaborationWhitelist = this.collaborationAllowlist;
220
+ // Array of requests when in batch mode, null otherwise
221
+ this._batch = null;
222
+ }
223
+ /**
224
+ * Returns an object containing the given headers as well as other headers (like the authorization header and
225
+ * custom headers) that should be included in a request.
226
+ * @param {?Object} callerHeaders - headers that the caller wishes to include in the request. This method will not
227
+ * override these headers with its own. Thus, if all the headers that this method was planning to add are already
228
+ * specified here, this method will return an object with exactly the same headers.
229
+ * @param {string} accessToken - the access token that will be used to make the request
230
+ * @returns {Object} - a new object with the headers needed for the request
231
+ * @private
232
+ */
233
+ BoxClient.prototype._createHeadersForRequest = function (callerHeaders, accessToken) {
234
+ var headers = {};
235
+ // 'Authorization' - contains your valid access token for authorization
236
+ headers[HEADER_AUTHORIZATION] = buildAuthorizationHeader(accessToken);
237
+ // We copy our own custom headers (XFF, BoxApi, etc.) before copying over the caller-specified headers so that
238
+ // the caller-specified headers will take precedence.
239
+ Object.assign(headers, this._customHeaders, callerHeaders);
240
+ // Add analytics headers last so they cannot be overwritten
241
+ Object.assign(headers, {
242
+ 'X-Box-UA': constructBoxUAHeader(this._analyticsClient),
243
+ });
244
+ return headers;
245
+ };
246
+ /**
247
+ * Makes an API request to the Box API on behalf of the client. Before executing
248
+ * the request, it first ensures the user has usable tokens. Will be called again
249
+ * if the request returns a temporary error. Will propogate error if request returns
250
+ * a permanent error, or if usable tokens are not available.
251
+ *
252
+ * @param {Object} params - Request lib params to configure the request
253
+ * @param {APIRequest~Callback} [callback] - passed response data
254
+ * @returns {Promise} Promise resolving to the response
255
+ * @private
256
+ */
257
+ BoxClient.prototype._makeRequest = function (params /* FIXME */, callback) {
258
+ var _this = this;
259
+ var promise;
260
+ if (this._batch) {
261
+ // eslint-disable-next-line promise/avoid-new
262
+ promise = new bluebird_1.Promise(function (resolve, reject) {
263
+ _this._batch.push({ params: params, resolve: resolve, reject: reject });
264
+ });
265
+ }
266
+ else {
267
+ // Check that tokens are fresh, update if tokens are expired or soon-to-be expired
268
+ promise = this._session
269
+ .getAccessToken(this._tokenOptions)
270
+ .then(function (accessToken) {
271
+ params.headers = _this._createHeadersForRequest(params.headers, accessToken);
272
+ if (params.streaming) {
273
+ // streaming is specific to the SDK, so delete it from params before continuing
274
+ delete params.streaming;
275
+ var responseStream = _this._requestManager.makeStreamingRequest(params);
276
+ // Listen to 'response' event, so we can cleanup the token store in case when the request is unauthorized
277
+ // due to expired access token
278
+ responseStream.on('response', function (response /* FIXME */) {
279
+ if (isUnauthorizedDueToExpiredAccessToken(response)) {
280
+ var expiredTokensError = errors.buildAuthError(response);
281
+ // Give the session a chance to handle the error (ex: a persistent session will clear the token store)
282
+ if (_this._session.handleExpiredTokensError) {
283
+ _this._session.handleExpiredTokensError(expiredTokensError);
284
+ }
285
+ }
286
+ });
287
+ return responseStream;
288
+ }
289
+ // Make the request to Box, and perform standard response handling
290
+ return _this._requestManager.makeRequest(params);
291
+ });
292
+ }
293
+ return promise
294
+ .then(function (response /* FIXME */) {
295
+ if (!response.statusCode) {
296
+ // Response is not yet complete, and is just a stream that will return the response later
297
+ // Just return the stream, since it doesn't need further response handling
298
+ return response;
299
+ }
300
+ if (isUnauthorizedDueToExpiredAccessToken(response)) {
301
+ var expiredTokensError = errors.buildAuthError(response);
302
+ // Give the session a chance to handle the error (ex: a persistent session will clear the token store)
303
+ if (_this._session.handleExpiredTokensError) {
304
+ return _this._session.handleExpiredTokensError(expiredTokensError);
305
+ }
306
+ throw expiredTokensError;
307
+ }
308
+ return response;
309
+ })
310
+ .asCallback(callback);
311
+ };
312
+ /**
313
+ * Set a custom header. A custom header is applied to every request for the life of the client. To
314
+ * remove a header, set it's value to null.
315
+ *
316
+ * @param {string} header The name of the custom header to set.
317
+ * @param {*} value The value of the custom header. Set to null to remove the given header.
318
+ * @returns {void}
319
+ */
320
+ BoxClient.prototype.setCustomHeader = function (header, value) {
321
+ if (value) {
322
+ this._customHeaders[header] = value;
323
+ }
324
+ else {
325
+ delete this._customHeaders[header];
326
+ }
327
+ };
328
+ /**
329
+ * Sets the list of requesting IP addresses for the X-Forwarded-For header. Used to give the API
330
+ * better information for uploads, rate-limiting, etc.
331
+ *
332
+ * @param {string[]} ips - Array of IP Addresses
333
+ * @returns {void}
334
+ */
335
+ BoxClient.prototype.setIPs = function (ips) {
336
+ var validIPs = ips.filter(function (ipString) { return isIP(ipString); }).join(', ');
337
+ this.setCustomHeader(HEADER_XFF, validIPs);
338
+ this._tokenOptions = { ip: validIPs };
339
+ };
340
+ /**
341
+ * Sets the shared item context on the API Session. Overwrites any current context.
342
+ *
343
+ * @param {string} url The shared link url
344
+ * @param {?string} password The shared link password, null if no password exists.
345
+ * @returns {void}
346
+ */
347
+ BoxClient.prototype.setSharedContext = function (url, password) {
348
+ var sharedContextAuthHeader = this.buildSharedItemAuthHeader(url, password);
349
+ this.setCustomHeader(HEADER_BOXAPI, sharedContextAuthHeader);
350
+ };
351
+ /**
352
+ * Removes any current shared item context from API Session.
353
+ *
354
+ * @returns {void}
355
+ */
356
+ BoxClient.prototype.revokeSharedContext = function () {
357
+ this.setCustomHeader(HEADER_BOXAPI, null);
358
+ };
359
+ /**
360
+ * Set up the As-User context, which is used by enterprise admins to
361
+ * impersonate their managed users and perform actions on their behalf.
362
+ *
363
+ * @param {string} userID - The ID of the user to impersonate
364
+ * @returns {void}
365
+ */
366
+ BoxClient.prototype.asUser = function (userID) {
367
+ this.setCustomHeader(HEADER_AS_USER, userID);
368
+ };
369
+ /**
370
+ * Revoke the As-User context and return to making calls on behalf of the user
371
+ * who owns the client's access token.
372
+ *
373
+ * @returns {void}
374
+ */
375
+ BoxClient.prototype.asSelf = function () {
376
+ this.setCustomHeader(HEADER_AS_USER, null);
377
+ };
378
+ /**
379
+ * Revokes the client's access tokens. The client will no longer be tied to a user
380
+ * and will be unable to make calls to the API, rendering it effectively useless.
381
+ *
382
+ * @param {Function} [callback] Called after revoking, with an error if one existed
383
+ * @returns {Promise} A promise resolving when the client's access token is revoked
384
+ */
385
+ BoxClient.prototype.revokeTokens = function (callback) {
386
+ return this._session.revokeTokens(this._tokenOptions).asCallback(callback);
387
+ };
388
+ /**
389
+ * Exchange the client access token for one with lower scope
390
+ * @param {string|string[]} scopes The scope(s) requested for the new token
391
+ * @param {string} [resource] The absolute URL of an API resource to scope the new token to
392
+ * @param {Object} [options] - Optional parameters
393
+ * @param {ActorParams} [options.actor] - Optional actor parameters for creating annotator tokens with Token Auth client
394
+ * @param {SharedLinkParams} [options.sharedLink] - Optional shared link parameters for creating tokens using shared links
395
+ * @param {Function} [callback] Called with the new token
396
+ * @returns {Promise<TokenInfo>} A promise resolving to the exchanged token info
397
+ */
398
+ BoxClient.prototype.exchangeToken = function (scopes, resource, options, callback) {
399
+ // Shuffle optional parameters
400
+ if (typeof options === 'function') {
401
+ callback = options;
402
+ options = {};
403
+ }
404
+ var opts = Object.assign({ tokenRequestOptions: this._tokenOptions || null }, options);
405
+ return this._session
406
+ .exchangeToken(scopes, resource, opts)
407
+ .asCallback(callback);
408
+ };
409
+ /**
410
+ * Makes GET request to Box API V2 endpoint
411
+ *
412
+ * @param {string} path - path to a certain API endpoint (ex: /file)
413
+ * @param {?Object} params - object containing parameters for the request, such as query strings and headers
414
+ * @param {APIRequest~Callback} [callback] - passed final API response or err if request failed
415
+ * @returns {void}
416
+ */
417
+ BoxClient.prototype.get = function (path, params, callback) {
418
+ var newParams = merge({}, params || {});
419
+ newParams.method = 'GET';
420
+ newParams.url = getFullURL(this._baseURL, path);
421
+ return this._makeRequest(newParams, callback);
422
+ };
423
+ /**
424
+ * Makes POST request to Box API V2 endpoint
425
+ *
426
+ * @param {string} path - path to a certain API endpoint (ex: /file)
427
+ * @param {?Object} params - object containing parameters for the request, such as query strings and headers
428
+ * @param {APIRequest~Callback} [callback] - passed final API response or err if request failed
429
+ * @returns {void}
430
+ */
431
+ BoxClient.prototype.post = function (path, params, callback) {
432
+ var newParams = merge({}, params || {});
433
+ newParams.method = 'POST';
434
+ newParams.url = getFullURL(this._baseURL, path);
435
+ return this._makeRequest(newParams, callback);
436
+ };
437
+ /**
438
+ * Makes PUT request to Box API V2 endpoint
439
+ *
440
+ * @param {string} path - path to a certain API endpoint (ex: /file)
441
+ * @param {?Object} params - object containing parameters for the request, such as query strings and headers
442
+ * @param {APIRequest~Callback} callback - passed final API response or err if request failed
443
+ * @returns {void}
444
+ */
445
+ BoxClient.prototype.put = function (path, params, callback) {
446
+ var newParams = merge({}, params || {});
447
+ newParams.method = 'PUT';
448
+ newParams.url = getFullURL(this._baseURL, path);
449
+ return this._makeRequest(newParams, callback);
450
+ };
451
+ /**
452
+ * Makes DELETE request to Box API V2 endpoint
453
+ *
454
+ * @param {string} path - path to a certain API endpoint (ex: /file)
455
+ * @param {?Object} params - object containing parameters for the request, such as query strings and headers
456
+ * @param {APIRequest~Callback} callback - passed final API response or err if request failed
457
+ * @returns {void}
458
+ */
459
+ BoxClient.prototype.del = function (path, params, callback) {
460
+ var newParams = merge({}, params || {});
461
+ newParams.method = 'DELETE';
462
+ newParams.url = getFullURL(this._baseURL, path);
463
+ return this._makeRequest(newParams, callback);
464
+ };
465
+ /**
466
+ * Makes an OPTIONS call to a Box API V2 endpoint
467
+ *
468
+ * @param {string} path - Path to an API endpoint (e.g. /files/content)
469
+ * @param {?Object} params - An optional object containing request parameters
470
+ * @param {APIRequest~Callback} callback - Called with API call results, or err if call failed
471
+ * @returns {void}
472
+ */
473
+ BoxClient.prototype.options = function (path, params, callback) {
474
+ var newParams = merge({}, params || {});
475
+ newParams.method = 'OPTIONS';
476
+ newParams.url = getFullURL(this._baseURL, path);
477
+ return this._makeRequest(newParams, callback);
478
+ };
479
+ /**
480
+ * Makes a POST call to a Box API V2 upload endpoint
481
+ * @param {string} path - path to an upload API endpoint
482
+ * @param {?Object} params - an optional object containing request parameters
483
+ * @param {?Object} formData - multipart form data to include in the upload request {@see https://github.com/mikeal/request#multipartform-data-multipart-form-uploads}
484
+ * @param {APIRequest~Callback} callback - called with API call results, or an error if the call failed
485
+ * @returns {void}
486
+ */
487
+ BoxClient.prototype.upload = function (path, params, formData, callback) {
488
+ var defaults = {
489
+ method: 'POST',
490
+ };
491
+ var newParams = merge(defaults, params || {});
492
+ newParams.url = getFullURL(this._uploadBaseURL, path);
493
+ newParams.formData = formData;
494
+ newParams.timeout = this._uploadRequestTimeoutMS;
495
+ return this._makeRequest(newParams, callback);
496
+ };
497
+ /**
498
+ * Build the 'BoxApi' Header used for authenticating access to a shared item
499
+ *
500
+ * @param {string} url The shared link url
501
+ * @param {string} [password] The shared link password
502
+ * @returns {string} A properly formatted 'BoxApi' header
503
+ */
504
+ BoxClient.prototype.buildSharedItemAuthHeader = function (url, password) {
505
+ var encodedURL = encodeURIComponent(url), encodedPassword = encodeURIComponent(password !== null && password !== void 0 ? password : '');
506
+ if (password) {
507
+ return util.format('shared_link=%s&shared_link_password=%s', encodedURL, encodedPassword);
508
+ }
509
+ return util.format('shared_link=%s', encodedURL);
510
+ };
511
+ /**
512
+ * Return a callback that properly handles a successful response code by passing the response
513
+ * body to the original callback. Any request error or unsuccessful response codes are propagated
514
+ * back to the callback as errors. This is the standard behavior of most endpoints.
515
+ *
516
+ * @param {Function} callback The original callback given by the consumer
517
+ * @returns {?APIRequest~Callback} A new callback that processes the response before passing it to the callback.
518
+ */
519
+ BoxClient.prototype.defaultResponseHandler = function (callback) {
520
+ var self = this;
521
+ if (!callback) {
522
+ return null;
523
+ }
524
+ return function (err, response /* FIXME */) {
525
+ // Error with Request
526
+ if (err) {
527
+ callback(err);
528
+ return;
529
+ }
530
+ // Successful Response
531
+ if (response.statusCode >= HTTP_STATUS_CODE_SUCCESS_BLOCK_RANGE[0] &&
532
+ response.statusCode <= HTTP_STATUS_CODE_SUCCESS_BLOCK_RANGE[1]) {
533
+ if (self._useIterators && PagingIterator.isIterable(response)) {
534
+ callback(null, new PagingIterator(response, self));
535
+ return;
536
+ }
537
+ callback(null, response.body);
538
+ return;
539
+ }
540
+ // Unexpected Response
541
+ callback(errors.buildUnexpectedResponseError(response));
542
+ };
543
+ };
544
+ /**
545
+ * Wrap a client method with the default handler for both callback and promise styles
546
+ * @param {Function} method The client method (e.g. client.get)
547
+ * @returns {Function} The wrapped method
548
+ */
549
+ BoxClient.prototype.wrapWithDefaultHandler = function (method) {
550
+ var self = this;
551
+ return function wrappedClientMethod( /* arguments */) {
552
+ // Check if the last argument is a callback
553
+ var lastArg = arguments[arguments.length - 1], callback;
554
+ if (typeof lastArg === 'function') {
555
+ callback = self.defaultResponseHandler(lastArg);
556
+ arguments[arguments.length - 1] = callback;
557
+ }
558
+ var ret = method.apply(self, arguments);
559
+ if (ret instanceof bluebird_1.Promise) {
560
+ ret = ret.then(function (response) {
561
+ if (response.statusCode >= HTTP_STATUS_CODE_SUCCESS_BLOCK_RANGE[0] &&
562
+ response.statusCode <= HTTP_STATUS_CODE_SUCCESS_BLOCK_RANGE[1]) {
563
+ if (self._useIterators && PagingIterator.isIterable(response)) {
564
+ return new PagingIterator(response, self);
565
+ }
566
+ return response.body;
567
+ }
568
+ throw errors.buildUnexpectedResponseError(response);
569
+ });
570
+ }
571
+ if (callback) {
572
+ // If the callback will handle any errors, don't worry about the promise
573
+ ret.suppressUnhandledRejections();
574
+ }
575
+ return ret;
576
+ };
577
+ };
578
+ /**
579
+ * Add a SDK plugin. Warning: This will modify the box-client interface and can override existing properties.
580
+ * @param {string} name Plugin name. Will be accessible via client.<plugin-name>
581
+ * @param {Function} plugin The SDK plugin to add
582
+ * @param {Object} [options] Plugin-specific options
583
+ * @returns {void}
584
+ * @throws Will throw an error if plugin name matches an existing method on box-client
585
+ */
586
+ BoxClient.prototype.plug = function (name, plugin, options) {
587
+ options = options || {};
588
+ if (name in this && typeof this[name] === 'function') {
589
+ throw new Error('You cannot define a plugin that overrides an existing method on the client');
590
+ }
591
+ // Create plugin and export plugin onto client.
592
+ this[name] = plugin(this, options);
593
+ };
594
+ return BoxClient;
595
+ }());
351
596
  // ------------------------------------------------------------------------------
352
597
  // Public
353
598
  // ------------------------------------------------------------------------------
354
-
355
599
  /**
356
600
  * Enum of valid collaboration roles
357
601
  *
@@ -359,16 +603,15 @@ BoxClient.prototype._makeRequest = function(params, callback) {
359
603
  * @enum {CollaborationRole}
360
604
  */
361
605
  BoxClient.prototype.collaborationRoles = {
362
- EDITOR: 'editor',
363
- VIEWER: 'viewer',
364
- PREVIEWER: 'previewer',
365
- UPLOADER: 'uploader',
366
- PREVIEWER_UPLOADER: 'previewer uploader',
367
- VIEWER_UPLOADER: 'viewer uploader',
368
- CO_OWNER: 'co-owner',
369
- OWNER: 'owner'
606
+ EDITOR: 'editor',
607
+ VIEWER: 'viewer',
608
+ PREVIEWER: 'previewer',
609
+ UPLOADER: 'uploader',
610
+ PREVIEWER_UPLOADER: 'previewer uploader',
611
+ VIEWER_UPLOADER: 'viewer uploader',
612
+ CO_OWNER: 'co-owner',
613
+ OWNER: 'owner',
370
614
  };
371
-
372
615
  /**
373
616
  * Enum of Box item types
374
617
  *
@@ -376,10 +619,9 @@ BoxClient.prototype.collaborationRoles = {
376
619
  * @enum {ItemType}
377
620
  */
378
621
  BoxClient.prototype.itemTypes = {
379
- FILE: 'file',
380
- FOLDER: 'folder'
622
+ FILE: 'file',
623
+ FOLDER: 'folder',
381
624
  };
382
-
383
625
  /**
384
626
  * Enum of valid values for setting different access levels. To be used when
385
627
  * creating and editting shared links, upload emails, etc.
@@ -388,417 +630,13 @@ BoxClient.prototype.itemTypes = {
388
630
  * @type {AccessLevel}
389
631
  */
390
632
  BoxClient.prototype.accessLevels = {
391
- OPEN: {access: 'open'},
392
- COLLABORATORS: {access: 'collaborators'},
393
- COMPANY: {access: 'company'},
394
- DEFAULT: {},
395
- DISABLED: null
633
+ OPEN: { access: 'open' },
634
+ COLLABORATORS: { access: 'collaborators' },
635
+ COMPANY: { access: 'company' },
636
+ DEFAULT: {},
637
+ DISABLED: null,
396
638
  };
397
-
398
639
  /** @const {string} */
399
640
  BoxClient.prototype.CURRENT_USER_ID = Users.prototype.CURRENT_USER_ID;
400
-
401
- /**
402
- * Set a custom header. A custom header is applied to every request for the life of the client. To
403
- * remove a header, set it's value to null.
404
- *
405
- * @param {string} header The name of the custom header to set.
406
- * @param {*} value The value of the custom header. Set to null to remove the given header.
407
- * @returns {void}
408
- */
409
- BoxClient.prototype.setCustomHeader = function(header, value) {
410
- if (value) {
411
- this._customHeaders[header] = value;
412
- } else {
413
- delete this._customHeaders[header];
414
- }
415
- };
416
-
417
- /**
418
- * Sets the list of requesting IP addresses for the X-Forwarded-For header. Used to give the API
419
- * better information for uploads, rate-limiting, etc.
420
- *
421
- * @param {string[]} ips - Array of IP Addresses
422
- * @returns {void}
423
- */
424
- BoxClient.prototype.setIPs = function(ips) {
425
- var validIPs = ips.filter(ipString => isIP(ipString)).join(', ');
426
-
427
- this.setCustomHeader(HEADER_XFF, validIPs);
428
-
429
- this._tokenOptions = {ip: validIPs};
430
- };
431
-
432
- /**
433
- * Sets the shared item context on the API Session. Overwrites any current context.
434
- *
435
- * @param {string} url The shared link url
436
- * @param {?string} password The shared link password, null if no password exists.
437
- * @returns {void}
438
- */
439
- BoxClient.prototype.setSharedContext = function(url, password) {
440
- var sharedContextAuthHeader = this.buildSharedItemAuthHeader(url, password);
441
- this.setCustomHeader(HEADER_BOXAPI, sharedContextAuthHeader);
442
- };
443
-
444
- /**
445
- * Removes any current shared item context from API Session.
446
- *
447
- * @returns {void}
448
- */
449
- BoxClient.prototype.revokeSharedContext = function() {
450
- this.setCustomHeader(HEADER_BOXAPI, null);
451
- };
452
-
453
- /**
454
- * Set up the As-User context, which is used by enterprise admins to
455
- * impersonate their managed users and perform actions on their behalf.
456
- *
457
- * @param {string} userID - The ID of the user to impersonate
458
- * @returns {void}
459
- */
460
- BoxClient.prototype.asUser = function(userID) {
461
-
462
- this.setCustomHeader(HEADER_AS_USER, userID);
463
- };
464
-
465
- /**
466
- * Revoke the As-User context and return to making calls on behalf of the user
467
- * who owns the client's access token.
468
- *
469
- * @returns {void}
470
- */
471
- BoxClient.prototype.asSelf = function() {
472
-
473
- this.setCustomHeader(HEADER_AS_USER, null);
474
- };
475
-
476
- /**
477
- * Revokes the client's access tokens. The client will no longer be tied to a user
478
- * and will be unable to make calls to the API, rendering it effectively useless.
479
- *
480
- * @param {Function} [callback] Called after revoking, with an error if one existed
481
- * @returns {Promise} A promise resolving when the client's access token is revoked
482
- */
483
- BoxClient.prototype.revokeTokens = function(callback) {
484
-
485
- return this._session.revokeTokens(this._tokenOptions)
486
- .asCallback(callback);
487
- };
488
-
489
- /**
490
- * Exchange the client access token for one with lower scope
491
- * @param {string|string[]} scopes The scope(s) requested for the new token
492
- * @param {string} [resource] The absolute URL of an API resource to scope the new token to
493
- * @param {Object} [options] - Optional parameters
494
- * @param {ActorParams} [options.actor] - Optional actor parameters for creating annotator tokens with Token Auth client
495
- * @param {SharedLinkParams} [options.sharedLink] - Optional shared link parameters for creating tokens using shared links
496
- * @param {Function} [callback] Called with the new token
497
- * @returns {Promise<TokenInfo>} A promise resolving to the exchanged token info
498
- */
499
- BoxClient.prototype.exchangeToken = function(scopes, resource, options, callback) {
500
-
501
- // Shuffle optional parameters
502
- if (typeof options === 'function') {
503
- callback = options;
504
- options = {};
505
- }
506
-
507
- var opts = Object.assign({ tokenRequestOptions: this._tokenOptions || null }, options);
508
-
509
- return this._session.exchangeToken(scopes, resource, opts)
510
- .asCallback(callback);
511
- };
512
-
513
- /**
514
- * Makes GET request to Box API V2 endpoint
515
- *
516
- * @param {string} path - path to a certain API endpoint (ex: /file)
517
- * @param {?Object} params - object containing parameters for the request, such as query strings and headers
518
- * @param {APIRequest~Callback} callback - passed final API response or err if request failed
519
- * @returns {void}
520
- */
521
- BoxClient.prototype.get = function(path, params, callback) {
522
- var newParams = merge({}, params || {});
523
- newParams.method = 'GET';
524
- newParams.url = getFullURL(this._baseURL, path);
525
-
526
- return this._makeRequest(newParams, callback);
527
- };
528
-
529
- /**
530
- * Makes POST request to Box API V2 endpoint
531
- *
532
- * @param {string} path - path to a certain API endpoint (ex: /file)
533
- * @param {?Object} params - object containing parameters for the request, such as query strings and headers
534
- * @param {APIRequest~Callback} callback - passed final API response or err if request failed
535
- * @returns {void}
536
- */
537
- BoxClient.prototype.post = function(path, params, callback) {
538
- var newParams = merge({}, params || {});
539
- newParams.method = 'POST';
540
- newParams.url = getFullURL(this._baseURL, path);
541
- return this._makeRequest(newParams, callback);
542
- };
543
-
544
- /**
545
- * Makes PUT request to Box API V2 endpoint
546
- *
547
- * @param {string} path - path to a certain API endpoint (ex: /file)
548
- * @param {?Object} params - object containing parameters for the request, such as query strings and headers
549
- * @param {APIRequest~Callback} callback - passed final API response or err if request failed
550
- * @returns {void}
551
- */
552
- BoxClient.prototype.put = function(path, params, callback) {
553
- var newParams = merge({}, params || {});
554
- newParams.method = 'PUT';
555
- newParams.url = getFullURL(this._baseURL, path);
556
- return this._makeRequest(newParams, callback);
557
- };
558
-
559
- /**
560
- * Makes DELETE request to Box API V2 endpoint
561
- *
562
- * @param {string} path - path to a certain API endpoint (ex: /file)
563
- * @param {?Object} params - object containing parameters for the request, such as query strings and headers
564
- * @param {APIRequest~Callback} callback - passed final API response or err if request failed
565
- * @returns {void}
566
- */
567
- BoxClient.prototype.del = function(path, params, callback) {
568
- var newParams = merge({}, params || {});
569
- newParams.method = 'DELETE';
570
- newParams.url = getFullURL(this._baseURL, path);
571
- return this._makeRequest(newParams, callback);
572
- };
573
-
574
-
575
- /**
576
- * Makes an OPTIONS call to a Box API V2 endpoint
577
- *
578
- * @param {string} path - Path to an API endpoint (e.g. /files/content)
579
- * @param {?Object} params - An optional object containing request parameters
580
- * @param {APIRequest~Callback} callback - Called with API call results, or err if call failed
581
- * @returns {void}
582
- */
583
- BoxClient.prototype.options = function(path, params, callback) {
584
- var newParams = merge({}, params || {});
585
- newParams.method = 'OPTIONS';
586
- newParams.url = getFullURL(this._baseURL, path);
587
-
588
- return this._makeRequest(newParams, callback);
589
- };
590
-
591
- /**
592
- * Makes a POST call to a Box API V2 upload endpoint
593
- * @param {string} path - path to an upload API endpoint
594
- * @param {?Object} params - an optional object containing request parameters
595
- * @param {?Object} formData - multipart form data to include in the upload request {@see https://github.com/mikeal/request#multipartform-data-multipart-form-uploads}
596
- * @param {APIRequest~Callback} callback - called with API call results, or an error if the call failed
597
- * @returns {void}
598
- */
599
- BoxClient.prototype.upload = function(path, params, formData, callback) {
600
-
601
- var defaults = {
602
- method: 'POST'
603
- };
604
- var newParams = merge(defaults, params || {});
605
- newParams.url = getFullURL(this._uploadBaseURL, path);
606
- newParams.formData = formData;
607
- newParams.timeout = this._uploadRequestTimeoutMS;
608
-
609
- return this._makeRequest(newParams, callback);
610
- };
611
-
612
- /**
613
- * Puts the client into batch mode, which will queue calls instead of
614
- * immediately making the API request.
615
- *
616
- * DEPRECATED: Batch API is not supported and should not be used; make calls in parallel instead.
617
- *
618
- * @returns {BoxClient} Current client object
619
- */
620
- BoxClient.prototype.batch = util.deprecate(function() {
621
- /* eslint-disable no-invalid-this */
622
- this._batch = [];
623
- return this;
624
- /* eslint-enable no-invalid-this */
625
- }, 'Batch API is not supported and should not be used; make calls in parallel instead.');
626
-
627
- /**
628
- * Executes a batch of requests.
629
- *
630
- * DEPRECATED: Batch API is not supported and should not be used; make calls in parallel instead.
631
- *
632
- * @returns {Promise<Object>} Promise resolving to the collection of batch responses
633
- */
634
- BoxClient.prototype.batchExec = util.deprecate(function(callback) {
635
- /* eslint-disable no-invalid-this */
636
- if (!this._batch) {
637
- return Promise.reject(new Error('Must start a batch before executing'))
638
- .asCallback(callback);
639
- }
640
-
641
- var params = {
642
- body: {
643
- requests: this._batch.map(batchReq => formatRequestForBatch(batchReq.params))
644
- }
645
- };
646
-
647
- var batch = this._batch;
648
- this._batch = null;
649
- return this.post('/batch', params)
650
- .then(res => {
651
-
652
- var responses = res.body.responses;
653
-
654
- responses.map(x => formatResponseForBatch(x)).forEach((response, index) => {
655
- batch[index].resolve(response);
656
- });
657
-
658
- return res.body;
659
- })
660
- .catch(err => {
661
- batch.forEach(req => req.reject(err));
662
-
663
- throw err;
664
- })
665
- .asCallback(callback);
666
- /* eslint-enable no-invalid-this */
667
- }, 'Batch API is not supported and should not be used; make calls in parallel instead.');
668
-
669
- /**
670
- * Build the 'BoxApi' Header used for authenticating access to a shared item
671
- *
672
- * @param {string} url The shared link url
673
- * @param {string} [password] The shared link password
674
- * @returns {string} A properly formatted 'BoxApi' header
675
- */
676
- BoxClient.prototype.buildSharedItemAuthHeader = function(url, password) {
677
- var encodedURL = encodeURIComponent(url),
678
- encodedPassword = encodeURIComponent(password);
679
-
680
- if (password) {
681
- return util.format('shared_link=%s&shared_link_password=%s', encodedURL, encodedPassword);
682
- }
683
-
684
- return util.format('shared_link=%s', encodedURL);
685
- };
686
-
687
- /**
688
- * Return a callback that properly handles a successful response code by passing the response
689
- * body to the original callback. Any request error or unsuccessful response codes are propagated
690
- * back to the callback as errors. This is the standard behavior of most endpoints.
691
- *
692
- * @param {Function} callback The original callback given by the consumer
693
- * @returns {?APIRequest~Callback} A new callback that processes the response before passing it to the callback.
694
- */
695
- BoxClient.prototype.defaultResponseHandler = function(callback) {
696
-
697
-
698
- var self = this;
699
-
700
- if (!callback) {
701
- return null;
702
- }
703
-
704
-
705
- return function(err, response) {
706
- // Error with Request
707
- if (err) {
708
- callback(err);
709
- return;
710
- }
711
-
712
- // Successful Response
713
- if (response.statusCode >= HTTP_STATUS_CODE_SUCCESS_BLOCK_RANGE[0]
714
- && response.statusCode <= HTTP_STATUS_CODE_SUCCESS_BLOCK_RANGE[1]) {
715
-
716
- if (self._useIterators && PagingIterator.isIterable(response)) {
717
- callback(null, new PagingIterator(response, self));
718
- return;
719
- }
720
-
721
- callback(null, response.body);
722
- return;
723
- }
724
- // Unexpected Response
725
- callback(errors.buildUnexpectedResponseError(response));
726
- };
727
- };
728
-
729
- /**
730
- * Wrap a client method with the default handler for both callback and promise styles
731
- * @param {Function} method The client method (e.g. client.get)
732
- * @returns {Function} The wrapped method
733
- */
734
- BoxClient.prototype.wrapWithDefaultHandler = function(method) {
735
-
736
- var self = this;
737
- return function wrappedClientMethod(/* arguments */) {
738
-
739
- // Check if the last argument is a callback
740
- var lastArg = arguments[arguments.length - 1],
741
- callback;
742
- if (typeof lastArg === 'function') {
743
- callback = self.defaultResponseHandler(lastArg);
744
- arguments[arguments.length - 1] = callback;
745
- }
746
-
747
- var ret = method.apply(self, arguments);
748
-
749
- if (ret instanceof Promise) {
750
-
751
- ret = ret.then(response => {
752
-
753
- if (response.statusCode >= HTTP_STATUS_CODE_SUCCESS_BLOCK_RANGE[0]
754
- && response.statusCode <= HTTP_STATUS_CODE_SUCCESS_BLOCK_RANGE[1]) {
755
-
756
- if (self._useIterators && PagingIterator.isIterable(response)) {
757
- return new PagingIterator(response, self);
758
- }
759
-
760
- return response.body;
761
- }
762
-
763
- throw errors.buildUnexpectedResponseError(response);
764
- });
765
- }
766
-
767
- if (callback) {
768
- // If the callback will handle any errors, don't worry about the promise
769
- ret.suppressUnhandledRejections();
770
- }
771
-
772
- return ret;
773
- };
774
- };
775
-
776
- /**
777
- * Add a SDK plugin. Warning: This will modify the box-client interface and can override existing properties.
778
- * @param {string} name Plugin name. Will be accessible via client.<plugin-name>
779
- * @param {Function} plugin The SDK plugin to add
780
- * @param {Object} [options] Plugin-specific options
781
- * @returns {void}
782
- * @throws Will throw an error if plugin name matches an existing method on box-client
783
- */
784
- BoxClient.prototype.plug = function(name, plugin, options) {
785
- options = options || {};
786
-
787
- if ((name in this) && (typeof this[name] === 'function')) {
788
- throw new Error('You cannot define a plugin that overrides an existing method on the client');
789
- }
790
-
791
- // Create plugin and export plugin onto client.
792
- this[name] = plugin(this, options);
793
- };
794
-
795
-
796
- // ------------------------------------------------------------------------------
797
- // Public
798
- // ------------------------------------------------------------------------------
799
-
800
- /**
801
- * @module box-node-sdk/lib/box-client
802
- * @see {@Link BoxClient}
803
- */
804
641
  module.exports = BoxClient;
642
+ //# sourceMappingURL=box-client.js.map