Source: util/errors.ts

/**
 * @fileoverview Errors Helper
 */
import * as qs from 'querystring';
// ------------------------------------------------------------------------------
// Requirements
// ------------------------------------------------------------------------------
const httpStatusCodes = require('http-status');
const TRACE_ID_HEADER_NAME = 'box-request-id';
// ------------------------------------------------------------------------------
// Typedefs and Callbacks
// ------------------------------------------------------------------------------
/**
 * An generic error propagated when the response has caused an error.
 * @typedef {Error} Errors~ResponseError
 * @property {APIRequest~ResponseObject} response The response object that generated the error
 * @property {int} statusCode A shortcut to the status code of the response
 */
/**
 * Error propagated whenever the SDK is unable to successfully complete an action
 * due to an expired access token (and refresh token, if one was provided).
 * @typedef {Errors~ResponseError} Errors~AuthError
 * @property {boolean} authExpired - always true
 */
/**
 * Request structure for error objects
 * @param {Object} req The request object
 * @constructor
 * @private
 */
class Request {
	method: any /* FIXME */;
	url: any /* FIXME */;
	httpVersion: any /* FIXME */;
	headers: any /* FIXME */;
	body: any /* FIXME */;
	constructor(req: any /* FIXME */) {
		this.method = req.method;
		if (req.uri) {
			this.url = {
				protocol: req.uri.protocol,
				host: req.uri.host,
				path: req.uri.pathname,
				query: qs.parse(req.uri.query),
				fragment: req.uri.hash,
			};
		} else {
			this.url = null;
		}
		this.httpVersion = req.response ? req.response.httpVersion : null;
		this.headers = req.headers;
		this.body = req.body;
	}
}
// ------------------------------------------------------------------------------
// Public
// ------------------------------------------------------------------------------
/**
 * A Helper for building errors across the SDK. Makes sure that easily-forgotten
 * fields aren't missed, and that everything is formatted properly to return to the
 * consumer.
 *
 * @name Errors
 * @module box-node-sdk/lib/util/errors
 */
export = {
	/**
	 * Build a response error with the given message, and attaching meta data from the
	 * response data.
	 *
	 * @param {?APIRequest~ResponseObject} response - The response returned by an APIRequestManager request
	 * @param {string} message - the response error message
	 * @returns {Errors~ResponseError} an error describing the response error
	 */
	buildResponseError(response: any /* FIXME */, message?: string) {
		response = response || {};
		message = message || 'API Response Error';
		var statusCode = response.statusCode;
		var statusMessage = httpStatusCodes[statusCode];
		var debugID = ''; // Of the form <requestID>.<traceID>, both parts optional
		var errorCode;
		var errorDescription;
		if (response.headers && response.headers[TRACE_ID_HEADER_NAME]) {
			// Append trace ID with dot separator — if not present, the dot should be omitted
			debugID += `.${response.headers[TRACE_ID_HEADER_NAME]}`;
		}
		if (response.body) {
			if (response.body.request_id) {
				// Prepend request ID
				debugID = response.body.request_id + debugID;
			}
			errorCode = response.body.code || response.body.error;
			errorDescription =
				response.body.message || response.body.error_description;
		}
		var errorMessage;
		if (debugID) {
			errorMessage = `${message} [${statusCode} ${statusMessage} | ${debugID}]`;
		} else {
			errorMessage = `${message} [${statusCode} ${statusMessage}]`;
		}
		if (errorCode) {
			errorMessage += ` ${errorCode}`;
		}
		if (errorDescription) {
			errorMessage += ` - ${errorDescription}`;
		}
		var responseError: any /* FIXME */ = new Error(errorMessage);
		responseError.statusCode = response.statusCode;
		responseError.response = response;
		responseError.request = response.request
			? new Request(response.request)
			: {};
		return responseError;
	},
	/**
	 * Build an authentication error. {@see Errors~AuthError}
	 *
	 * @param {?APIRequest~ResponseObject} response - The response returned by an APIRequestManager request
	 * @param {string} [message] - Optional message for the error
	 * @returns {Errors~AuthError} A properly formatted authentication error
	 */
	buildAuthError(response: any /* FIXME */, message?: string) {
		message = message || 'Expired Auth: Auth code or refresh token has expired';
		var responseError = this.buildResponseError(response, message);
		responseError.authExpired = true;
		return responseError;
	},
	/**
	 * Build the error for an "Unexpected Response" from the API. This is a shortcut for
	 * responseError built specifically for the 401 UNEXPECTED response case. It
	 * should be called and the error should be propogated to the consumer
	 * whenever an unexpected response was recieved from the API.
	 *
	 * @param {?APIRequest~ResponseObject} response - The response returned by an APIRequestManager request
	 * @returns {Errors~ResponseError} an error describing the response error
	 */
	buildUnexpectedResponseError(response: any /* FIXME */) {
		return this.buildResponseError(response, 'Unexpected API Response');
	},
	/**
	 * Unwrap a Bluebird error and throw it, or just re-throw if the error
	 * is not a Bluebird error.  This is necessary to preserve errors when
	 * a function is promisified.
	 * @param {Error} error The error to unwrap
	 * @returns {void}
	 * @throws {Error} The unwrapped error
	 */
	unwrapAndThrow(error: any /* FIXME */) {
		if (error.cause) {
			throw error.cause;
		}
		throw error;
	},
};