box-node-sdk 1.36.0 → 1.38.0

package/CHANGELOG.md

@@ -1,6 +1,48 @@
 # Changelog
 
-## 1.36.0 (2020-01-27)
+## Next Release
+
+## 1.38.0 (2021-08-05)
+
+**New Features and Enhancements:**
+
+- Add sensitive-language event types for admin invites ([#648](https://github.com/box/box-node-sdk/pull/648))
+- Use BetterDocs to adapt JSDocs to TypeScript ([#646](https://github.com/box/box-node-sdk/pull/646))
+- Change ProxyAgent import to be dynamic ([#641](https://github.com/box/box-node-sdk/pull/641))
+- New API for get files and file versions under retention ([#585](https://github.com/box/box-node-sdk/pull/585))
+
+**Bug Fixes:**
+
+- Deeply freeze Config except Buffers and Readable streams ([#651](https://github.com/box/box-node-sdk/pull/651))
+- Fix a typo in docs of src/managers/search.ts ([#649](https://github.com/box/box-node-sdk/pull/649))
+- Update broken documentation link ([#647](https://github.com/box/box-node-sdk/pull/647))
+- fix type annotations for exchangeToken functions ([#645](https://github.com/box/box-node-sdk/pull/645))
+- Deprecate files getThumbnail API in favor of getRepresentationContent ([#627](https://github.com/box/box-node-sdk/pull/627))
+
+## 1.37.2 (2021-05-20)
+
+**Bug Fixes:**
+
+- Fix backwards compatibility issue by moving some TypeScript @types as direct dependencies ([#630](https://github.com/box/box-node-sdk/pull/630))
+
+## 1.37.1 (2021-05-19)
+
+**Bug Fixes:**
+
+- Insensitive language: replace whitelist with allowlist ([#625](https://github.com/box/box-node-sdk/pull/625))
+
+## 1.37.0 (2021-04-16)
+
+**New Features and Enhancements:**
+
+- Add support for copyInstanceOnItemCopy field for metadata templates ([#572](https://github.com/box/box-node-sdk/pull/572))
+
+**Bug Fixes:**
+
+- Fix webhook signature validation ([#568](https://github.com/box/box-node-sdk/pull/568))
+- Update dependencies to patch security vulnerabilities ([#578](https://github.com/box/box-node-sdk/pull/578))
+
+## 1.36.0 (2021-01-27)
 
 **New Features and Enhancements:**
 
@@ -163,11 +205,11 @@ to specify a client ID and secret (thanks to @cbetta)
 
 ## 1.16.0 [2018-04-10]
 
-- Added support for [assigning Retention Policies to Metadata Templates](https://github.com/box/box-node-sdk/blob/master/docs/retention-policies.md#assign-retention-policy)
+- Added support for [assigning Retention Policies to Metadata Templates](https://github.com/box/box-node-sdk/blob/main/docs/retention-policies.md#assign-retention-policy)
 
 ## 1.15.0 [2018-03-29]
 
-- Fixed [`client.webhooks.validateMessage() and `sdk.validateWebhookMessage()`](https://github.com/box/box-node-sdk/blob/master/docs/webhooks.md#validate-a-webhook-message)
+- Fixed [`client.webhooks.validateMessage() and `sdk.validateWebhookMessage()`](https://github.com/box/box-node-sdk/blob/main/docs/webhooks.md#validate-a-webhook-message)
 to accept the request body as an `Object`
 - Fixed `sdk.configure()` to correct reconfigure all options
 - Improved error messages for API errors and added the request object as `error.request` for easier debugging

package/README.md

@@ -7,6 +7,8 @@ Box Node.js SDK
 
 A Node.js interface to the [Box Content API](https://developers.box.com/docs/).
 
+Getting Started Docs: https://developer.box.com/guides/tooling/sdks/node/
+
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
@@ -184,7 +186,7 @@ client.comments.delete('456')
 
 For complete documentation about the available operations, please see
 the [SDK documentation pages](./docs) and the auto-generated
-[JSDocs](https://rawgit.com/box/box-node-sdk/master/docs/jsdoc/index.html).
+[JSDocs](https://rawgit.com/box/box-node-sdk/main/docs/jsdoc/index.html).
 These contain detailed information about which methods are available and
 how to use them.
 

package/lib/api-request-manager.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @fileoverview A library for making requests to the Box API.
+ */
+/// <reference types="node" />
+/// <reference types="bluebird" />
+import { EventEmitter } from 'events';
+declare type Config = any;
+/**
+ * A library for communicating with the Box API.
+ *
+ * @param {Config} config SDK configuration object instance.
+ * @param {EventEmitter} eventBus The event bus for SDK events
+ * @constructor
+ */
+declare class APIRequestManager {
+    config: Config;
+    eventBus: EventEmitter;
+    constructor(config: Config, eventBus: EventEmitter);
+    /**
+     * Make a request to the API, and get the response via callback.
+     *
+     * @param {Object} options The request options
+     * @returns {Promise<Response>} A promise resolving to the response object
+     */
+    makeRequest(options: any): import("bluebird")<unknown>;
+    /**
+     * Make a request to the API, and return a read stream for the response.
+     *
+     * @param {Object} options The request options
+     * @returns {Stream.Readable} The response stream
+     */
+    makeStreamingRequest(options: any): any;
+}
+/**
+ * @module box-node-sdk/lib/api-request-manager
+ * @see {@Link APIRequestManager}
+ */
+export = APIRequestManager;

package/lib/api-request-manager.js

@@ -1,24 +1,22 @@
+"use strict";
 /**
  * @fileoverview A library for making requests to the Box API.
  */
-
-'use strict';
-
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 // ------------------------------------------------------------------------------
 // Requirements
 // ------------------------------------------------------------------------------
-var APIRequest = require('./api-request'),
-	errors = require('./util/errors'),
-	Promise = require('bluebird');
-
+var bluebird_1 = require("bluebird");
+var errors_1 = __importDefault(require("./util/errors"));
+var APIRequest = require('./api-request');
 // ------------------------------------------------------------------------------
 // Private
 // ------------------------------------------------------------------------------
-
 // ------------------------------------------------------------------------------
 // Public
 // ------------------------------------------------------------------------------
-
 /**
  * A library for communicating with the Box API.
  *
@@ -26,50 +24,45 @@ var APIRequest = require('./api-request'),
  * @param {EventEmitter} eventBus The event bus for SDK events
  * @constructor
  */
-function APIRequestManager(config, eventBus) {
-
-	this.config = config;
-	this.eventBus = eventBus;
-}
-
-/**
- * Make a request to the API, and get the response via callback.
- *
- * @param {Object} options The request options
- * @returns {Promise<Response>} A promise resolving to the response object
- */
-APIRequestManager.prototype.makeRequest = function(options) {
-	// Add default APIRequestManager options to each request
-	var requestConfig = this.config.extend({
-		request: options
-	});
-
-	// Make the request
-	var apiRequest = new APIRequest(requestConfig, this.eventBus);
-	return Promise.fromCallback(callback => apiRequest.execute(callback))
-		.catch(err => errors.unwrapAndThrow(err));
-};
-
-/**
- * Make a request to the API, and return a read stream for the response.
- *
- * @param {Object} options The request options
- * @returns {Stream.Readable} The response stream
- */
-APIRequestManager.prototype.makeStreamingRequest = function(options) {
-	// Add default APIRequestManager options to each request
-	var requestConfig = this.config.extend({
-		request: options
-	});
-
-	// Make the request
-	var apiRequest = new APIRequest(requestConfig, this.eventBus);
-	apiRequest.execute();
-	return apiRequest.getResponseStream();
-};
-
-/**
- * @module box-node-sdk/lib/api-request-manager
- * @see {@Link APIRequestManager}
- */
+var APIRequestManager = /** @class */ (function () {
+    function APIRequestManager(config, eventBus) {
+        this.config = config;
+        this.eventBus = eventBus;
+    }
+    /**
+     * Make a request to the API, and get the response via callback.
+     *
+     * @param {Object} options The request options
+     * @returns {Promise<Response>} A promise resolving to the response object
+     */
+    APIRequestManager.prototype.makeRequest = function (options /* FIXME */) {
+        // Add default APIRequestManager options to each request
+        var requestConfig = this.config.extend({
+            request: options,
+        });
+        // Make the request
+        var apiRequest = new APIRequest(requestConfig, this.eventBus);
+        return bluebird_1.Promise.fromCallback(function (callback) {
+            return apiRequest.execute(callback);
+        }).catch(function (err) { return errors_1.default.unwrapAndThrow(err); });
+    };
+    /**
+     * Make a request to the API, and return a read stream for the response.
+     *
+     * @param {Object} options The request options
+     * @returns {Stream.Readable} The response stream
+     */
+    APIRequestManager.prototype.makeStreamingRequest = function (options /* FIXME */) {
+        // Add default APIRequestManager options to each request
+        var requestConfig = this.config.extend({
+            request: options,
+        });
+        // Make the request
+        var apiRequest = new APIRequest(requestConfig, this.eventBus);
+        apiRequest.execute();
+        return apiRequest.getResponseStream();
+    };
+    return APIRequestManager;
+}());
 module.exports = APIRequestManager;
+//# sourceMappingURL=api-request-manager.js.map

package/lib/api-request-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-request-manager.js","sourceRoot":"","sources":["../src/api-request-manager.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;AAEH,iFAAiF;AACjF,eAAe;AACf,iFAAiF;AAEjF,qCAAmC;AAEnC,yDAAmC;AAEnC,IAAM,UAAU,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;AAQ5C,iFAAiF;AACjF,UAAU;AACV,iFAAiF;AAEjF,iFAAiF;AACjF,SAAS;AACT,iFAAiF;AAEjF;;;;;;GAMG;AACH;IAIC,2BAAY,MAAc,EAAE,QAAsB;QACjD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC1B,CAAC;IAED;;;;;OAKG;IACH,uCAAW,GAAX,UAAY,OAAY,CAAC,WAAW;QACnC,wDAAwD;QACxD,IAAI,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;YACtC,OAAO,EAAE,OAAO;SAChB,CAAC,CAAC;QAEH,mBAAmB;QACnB,IAAI,UAAU,GAAG,IAAI,UAAU,CAAC,aAAa,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9D,OAAO,kBAAO,CAAC,YAAY,CAAC,UAAC,QAAQ;YACpC,OAAA,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC;QAA5B,CAA4B,CAC5B,CAAC,KAAK,CAAC,UAAC,GAAG,IAAK,OAAA,gBAAM,CAAC,cAAc,CAAC,GAAG,CAAC,EAA1B,CAA0B,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;OAKG;IACH,gDAAoB,GAApB,UAAqB,OAAY,CAAC,WAAW;QAC5C,wDAAwD;QACxD,IAAI,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;YACtC,OAAO,EAAE,OAAO;SAChB,CAAC,CAAC;QAEH,mBAAmB;QACnB,IAAI,UAAU,GAAG,IAAI,UAAU,CAAC,aAAa,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9D,UAAU,CAAC,OAAO,EAAE,CAAC;QACrB,OAAO,UAAU,CAAC,iBAAiB,EAAE,CAAC;IACvC,CAAC;IACF,wBAAC;AAAD,CAAC,AA7CD,IA6CC;AAMD,iBAAS,iBAAiB,CAAC"}

package/lib/api-request.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview A Box API Request
+ */
+/// <reference types="node" />
+import { EventEmitter } from 'events';
+import request from 'request';
+import Config from './util/config';
+/**
+ * The API response object includes information about the request made and its response. The information attached is a subset
+ * of the information returned by the request module, which is too large and complex to be safely handled (contains circular
+ * references, errors on serialization, etc.)
+ *
+ * @typedef {Object} APIRequest~ResponseObject
+ * @property {APIRequest~RequestObject} request Information about the request that generated this response
+ * @property {int} statusCode The response HTTP status code
+ * @property {Object} headers A collection of response headers
+ * @property {Object|Buffer|string} [body] The response body. Encoded to JSON by default, but can be a buffer
+ *  (if encoding fails or if json encoding is disabled) or a string (if string encoding is enabled). Will be undefined
+ *  if no response body is sent.
+ */
+declare type APIRequestResponseObject = {
+    request: APIRequestRequestObject;
+    statusCode: number;
+    headers: Record<string, string>;
+    body?: object | Buffer | string;
+};
+/**
+ * The API request object includes information about the request made. The information attached is a subset of the information
+ * of a request module instance, which is too large and complex to be safely handled (contains circular references, errors on
+ * serialization, etc.).
+ *
+ * @typedef {Object} APIRequest~RequestObject
+ * @property {Object} uri Information about the request, including host, path, and the full 'href' url
+ * @property {string} method The request method (GET, POST, etc.)
+ * @property {Object} headers A collection of headers sent with the request
+ */
+declare type APIRequestRequestObject = {
+    uri: Record<string, any>;
+    method: string;
+    headers: Record<string, string>;
+};
+/**
+ * The error returned by APIRequest callbacks, which includes any relevent, available information about the request
+ * and response. Note that these properties do not exist on stream errors, only errors retuned to the callback.
+ *
+ * @typedef {Error} APIRequest~Error
+ * @property {APIRequest~RequestObject} request Information about the request that generated this error
+ * @property {APIRequest~ResponseObject} [response] Information about the response related to this error, if available
+ * @property {int} [statusCode] The response HTTP status code
+ * @property {boolean} [maxRetriesExceeded] True iff the max number of retries were exceeded. Otherwise, undefined.
+ */
+declare type APIRequestError = {
+    request: APIRequestRequestObject;
+    response?: APIRequestResponseObject;
+    statusCode?: number;
+    maxRetriesExceeded?: boolean;
+};
+/**
+ * Callback invoked when an APIRequest request is complete and finalized. On success,
+ * propagates the relevent response information. An err will indicate an unresolvable issue
+ * with the request (permanent failure or temp error response from the server, retried too many times).
+ *
+ * @callback APIRequest~Callback
+ * @param {?APIRequest~Error} err If Error object, API request did not get back the data it was supposed to. This
+ *  could be either because of a temporary error, or a more serious error connecting to the API.
+ * @param {APIRequest~ResponseObject} response The response returned by an APIRequestManager request
+ */
+declare type APIRequestCallback = (err?: APIRequestError | null, response?: APIRequestResponseObject) => void;
+/**
+ * APIRequest helps to prepare and execute requests to the Box API. It supports
+ * retries, multipart uploads, and more.
+ *
+
+ * @param {Config} config Request-specific Config object
+ * @param {EventEmitter} eventBus Event bus for the SDK instance
+ * @constructor
+ */
+declare class APIRequest {
+    config: Config;
+    eventBus: EventEmitter;
+    isRetryable: boolean;
+    _callback?: APIRequestCallback;
+    request?: request.Request;
+    stream?: request.Request;
+    numRetries?: number;
+    constructor(config: Config, eventBus: EventEmitter);
+    /**
+     * Executes the request with the given options. If a callback is provided, we'll
+     * handle the response via callbacks. Otherwise, the response will be streamed to
+     * via the stream property. You can access this stream with the getResponseStream()
+     * method.
+     *
+     * @param {APIRequest~Callback} [callback] Callback for handling the response
+     * @returns {void}
+     */
+    execute(callback?: APIRequestCallback): void;
+    /**
+     * Return the response read stream for a request. This will be undefined until
+     * a stream-based request has been started.
+     *
+     * @returns {?ReadableStream} The response stream
+     */
+    getResponseStream(): request.Request | undefined;
+    /**
+     * Handle the request response in the callback case.
+     *
+     * @param {?Error} err An error, if one occurred
+     * @param {Object} [response] The full response object, returned by the request module.
+     *  Contains information about the request & response, including the response body itself.
+     * @returns {void}
+     * @private
+     */
+    _handleResponse(err?: any, response?: any): void;
+    /**
+     * Attempt a retry. If the request hasn't exceeded it's maximum number of retries,
+     * re-execute the request (after the retry interval). Otherwise, propagate a new error.
+     *
+     * @param {?Error} err An error, if one occurred
+     * @returns {void}
+     * @private
+     */
+    _retry(err?: any): void;
+    /**
+     * Propagate the response to the provided callback.
+     *
+     * @param {?Error} err An error, if one occurred
+     * @param {APIRequest~ResponseObject} response Information about the request & response
+     * @returns {void}
+     * @private
+     */
+    _finish(err?: any, response?: APIRequestResponseObject): void;
+}
+/**
+ * @module box-node-sdk/lib/api-request
+ * @see {@Link APIRequest}
+ */
+export = APIRequest;