polarity-integration-utils 0.1.0 → 3.1.3

package/dist/es/lib/index.js

@@ -0,0 +1,50 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.types = exports.context = exports.logging = exports.requests = exports.errors = void 0;
+const errors = __importStar(require("./errors"));
+exports.errors = errors;
+const requests = __importStar(require("./requests"));
+exports.requests = requests;
+const logging = __importStar(require("./logging"));
+exports.logging = logging;
+const context = __importStar(require("./context"));
+exports.context = context;
+const types = __importStar(require("./types"));
+exports.types = types;
+__exportStar(require("./types"), exports);

package/dist/es/lib/internal/helpers/parallel-limit.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parallelLimit = parallelLimit;
+const errors_1 = require("../../errors");
+/**
+ * Execute an array of async tasks while ensuring that no more than `limit`
+ * tasks are running at the same time.  Results preserve task order.
+ *
+ * @param tasks - Array of thunked async tasks (`() => Promise<T>`).
+ * @param limit - Maximum number of concurrent tasks (positive integer).
+ */
+async function parallelLimit(tasks, limit) {
+    // ─── Validation ──────────────────────────────────────────────────────────────
+    if (!Array.isArray(tasks)) {
+        throw new errors_1.LibraryUsageError('parallelLimit: `tasks` must be an array');
+    }
+    if (tasks.length === 0)
+        return [];
+    if (typeof limit !== 'number' ||
+        !Number.isInteger(limit) ||
+        limit <= 0) {
+        throw new errors_1.LibraryUsageError('parallelLimit: `limit` must be a positive integer');
+    }
+    const results = new Array(tasks.length);
+    let next = 0;
+    async function worker() {
+        while (true) {
+            const current = next++;
+            if (current >= tasks.length)
+                break;
+            results[current] = await tasks[current]();
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, tasks.length) }, () => worker()));
+    return results;
+}

package/dist/es/lib/internal/helpers/sanitize-object.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeObject = sanitizeObject;
+/** @internal */
+const set_js_1 = __importDefault(require("lodash/set.js"));
+const has_js_1 = __importDefault(require("lodash/has.js"));
+/**
+ * Sanitizes the specified paths in an object by setting their values to a mask.
+ * This function returns a **new** object (deep clone) and does **not** mutate the original.
+ *
+ * @param obj - An object to sanitize (or nullish, which is returned directly).
+ * @param paths - An array of dot/bracket-notation paths to mask.
+ * @param mask - A replacement string. Defaults to "******".
+ * @returns A new object that has specified paths overwritten by `mask`.
+ */
+function sanitizeObject(obj, paths = [], mask = '******') {
+    // If not an object (null, undefined, etc.), return as-is.
+    if (!obj || typeof obj !== 'object') {
+        return obj;
+    }
+    // If paths is not a valid array, return as-is.
+    if (!Array.isArray(paths)) {
+        return obj;
+    }
+    // Create a deep clone so we do NOT mutate the original object
+    const clonedObj = structuredClone(obj);
+    // Replace each path's value with `mask`
+    for (const path of paths) {
+        if (typeof path === 'string' && (0, has_js_1.default)(clonedObj, path)) {
+            (0, set_js_1.default)(clonedObj, path, mask);
+        }
+    }
+    return clonedObj;
+}

package/dist/es/lib/logging/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./logger"), exports);

package/dist/es/lib/logging/logger.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLogger = exports.setLogger = void 0;
+const fs_1 = __importDefault(require("fs"));
+const loggingLevels = ['info', 'debug', 'trace', 'warn', 'error', 'fatal'];
+const writeToDevRunnerResults = (loggingLevel) => (...content) => fs_1.default.appendFileSync('devRunnerResults.json', '\n' + JSON.stringify({ SOURCE: `Logger.${loggingLevel}`, content }, null, 2));
+const defaultLogger = loggingLevels.reduce((agg, level) => ({
+    ...agg,
+    [level]: writeToDevRunnerResults(level)
+}), {});
+let _logger = defaultLogger;
+/**
+ * Set the logger object used by the integration.
+ *
+ * @example
+ * Example of setting the logger within the integration's startup method:
+ * ```js
+ * const { setLogger } = require('polarity-integration-utils/logger');
+ *
+ * function startup(logger){
+ *   setLogger(logger);
+ * }
+ * ```
+ *
+ * You can now use {@link getLogger} to get the logger object anywhere within your integration codebase.
+ *
+ * @public
+ * @param logger - the integration logger object passed into the `startup` method
+ */
+const setLogger = (logger) => {
+    _logger = logger;
+};
+exports.setLogger = setLogger;
+/**
+ * return the logger object set via the {@link setLogger} method.
+ *
+ * @example
+ * Example of using the integration's logging object:
+ * ```js
+ * const { getLogger } = require('polarity-integration-utils/logger');
+ *
+ * const logger = getLogger();
+ * logger.trace('this is a trace message');
+ * ```
+ *
+ * @public
+ * @returns the integration's logger object
+ */
+const getLogger = () => _logger;
+exports.getLogger = getLogger;

package/dist/es/lib/requests/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./polarity-request"), exports);
+__exportStar(require("./sanitize-request-options"), exports);

package/dist/es/lib/requests/polarity-request.js

@@ -0,0 +1,426 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolarityRequest = void 0;
+const fs_1 = __importDefault(require("fs"));
+const util_1 = require("util");
+const bottleneck_1 = __importDefault(require("bottleneck"));
+const postman_request_1 = __importDefault(require("postman-request"));
+const parallel_limit_1 = require("../internal/helpers/parallel-limit");
+const node_util_1 = require("node:util");
+const get_js_1 = __importDefault(require("lodash/get.js"));
+const has_js_1 = __importDefault(require("lodash/has.js"));
+const errors_1 = require("../errors");
+const logging_1 = require("../logging");
+const sanitize_request_options_1 = require("./sanitize-request-options");
+/**
+ * A utility class for making HTTP requests
+ * @public
+ */
+class PolarityRequest {
+    bottleneckLimiter;
+    /**
+     * Instance of a Bunyan logger
+     */
+    logger;
+    internalThrottlingOptions;
+    /**
+     * postman-request library request object with default values set.  Used internally for
+     * making HTTP requests directly via the postman-request library
+     */
+    requestWithDefaults;
+    roundedSuccessStatusCodes = [200];
+    /**
+     * One or more HTTP response properties specified using JSON dot notation.  If the
+     * specified path exists within the `body` property of the HTTP Response, an
+     * ApiRequestError will be thrown.
+     *
+     * By default, this value is an empty array and response properties are not used to
+     * detect errors.
+     * @defaultValue []
+     */
+    httpResponseErrorProperties = [];
+    /**
+     * One or more HTTP response properties specified using JSON dot notation that
+     * point to an error message that should be displayed to the user in the event
+     * of an API error.
+     *
+     * The property should be a string value.  If the property does not exist or is not
+     * a string value, a default error message will be used instead.
+     */
+    httpResponseErrorMessageProperties = [];
+    /**
+     * Optional method that can be implemented to determine if an API error
+     * was encountered after an HTTP request is made.
+     *
+     * If the `isApiError` method is implemented
+     * the property `roundedSuccessStatusCodes` and `httpResponseErrorProperties` are not
+     * used to determine API errors.
+     *
+     * @returns An object indicating whether an API error was encountered and an optional message.
+     */
+    isApiError = null;
+    /**
+     * An array of JSON dot notation paths to omit from the request options when logging.
+     *
+     * This property can be used to sanitize sensitive request properties that should not
+     * appear in logging.
+     *
+     * Note that the `requestOptions` object is automatically sanitized to remove properties that
+     * typically contain sensitive API key and passwords.  For a list of properties that are
+     * automatically sanitized, see the {@link sanitizeRequestOptions} method.
+     */
+    requestOptionsToSanitize = [];
+    userOptions = null;
+    /**
+     * Optional middleware method for modifying {@link HttpRequestOptions} before a request is made
+     * via the {@link PolarityRequest.run} method or {@link PolarityRequest.runInParallel} method.
+     * The returned `requestOptions` object will be used for the request.  This method is passed
+     * a copy of the original `requestOptions` object so it can be modified without side effects.
+     *
+     * This method is typically used for adding authentication (e.g., auth headers, or basic auth) to every request.
+     * It can also be used to add headers that are required on every request or conditionally add headers based
+     * on the passed in `userOptions`.
+     *
+     * This method can be set as part of the {@link PolarityRequestOptions} when creating a new instance of the
+     * {@link PolarityRequest} class or can be set after the fact.
+     *
+     * @param requestOptions - A copy of the request options used for the request.  This object can be modified
+     * without side effects.
+     * @param userOptions - The user options passed into the `doLookup` method.
+     * @returns The modified request options to use for the request.
+     */
+    preprocessRequestOptions = async (requestOptions, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    userOptions) => requestOptions;
+    /**
+     * Optional middleware method for modifying the {@link HttpRequestResponse} after a successful request.
+     * The passed in {@link HttpRequestResponse} object is not a copy but can be safely modified without
+     * side effects.  The returned `HttpRequestResponse` object will be used for the response.
+     *
+     * @param response - The HTTP response from the request.
+     * @param requestOptions - The request options used for the request.
+     * @param userOptions - The user options passed into the `doLookup` method.
+     */
+    postprocessRequestSuccess = async (response, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    requestOptions, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    userOptions) => response;
+    /**
+     * Method that can be implemented to post-process the HTTP response after a failed request.
+     * This method is typically used to inspect the error thrown and either alter the error
+     * object (e.g., to change the error message property to something more specific), to ignore
+     * the error (by not rethrowing it), or to take a specific action based on the error (e.g.,
+     * in the case of a RetryRequestError you may want to retry the request or return a special
+     * payload to the integration front end).
+     *
+     * @param error - The error thrown during the request.
+     * @param requestOptions - The request options used for the request.
+     * @param userOptions - The user options passed into the `doLookup` method.
+     */
+    postprocessRequestFailure = (error, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    requestOptions, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    userOptions) => {
+        throw error;
+    };
+    get throttlingOptions() {
+        return this.internalThrottlingOptions;
+    }
+    // REVIEW: Do we want to tie our throttling specifically to Bottleneck or do we want to make
+    // it more generic and independent of Bottleneck?
+    set throttlingOptions(throttlingOptions) {
+        if ((0, node_util_1.isDeepStrictEqual)(this.internalThrottlingOptions, throttlingOptions))
+            return;
+        this.bottleneckLimiter = new bottleneck_1.default({
+            ...throttlingOptions,
+            maxConcurrent: typeof throttlingOptions.maxConcurrent === 'string'
+                ? Number.parseInt(throttlingOptions.maxConcurrent, 10)
+                : throttlingOptions.maxConcurrent,
+            minTime: typeof throttlingOptions.minTime === 'string'
+                ? Number.parseInt(throttlingOptions.minTime, 10)
+                : throttlingOptions.minTime,
+            highWater: throttlingOptions.highWater || 50,
+            strategy: throttlingOptions.strategy || bottleneck_1.default.strategy.OVERFLOW
+        });
+        this.internalThrottlingOptions = throttlingOptions;
+    }
+    constructor(options = {}) {
+        const defaults = options.defaults || {};
+        const { ca, cert, key, passphrase, proxy, rejectUnauthorized = true, json = true } = defaults;
+        if ((0, logging_1.getLogger)().child) {
+            this.logger = (0, logging_1.getLogger)().child({
+                lib: 'polarity-integration-utils',
+                module: 'PolarityRequest'
+            });
+        }
+        else {
+            this.logger = (0, logging_1.getLogger)();
+        }
+        if (options.isApiError) {
+            this.isApiError = options.isApiError;
+        }
+        if (options.roundedSuccessStatusCodes) {
+            this.roundedSuccessStatusCodes = options.roundedSuccessStatusCodes;
+        }
+        if (options.httpResponseErrorMessageProperties) {
+            this.httpResponseErrorMessageProperties =
+                options.httpResponseErrorMessageProperties;
+        }
+        if (options.httpResponseErrorProperties) {
+            this.httpResponseErrorProperties = options.httpResponseErrorProperties;
+        }
+        if (options.requestOptionsToSanitize) {
+            this.requestOptionsToSanitize = options.requestOptionsToSanitize;
+        }
+        if (options.postprocessRequestFailure) {
+            this.postprocessRequestFailure = options.postprocessRequestFailure;
+        }
+        if (options.postprocessRequestSuccess) {
+            this.postprocessRequestSuccess = options.postprocessRequestSuccess;
+        }
+        if (options.preprocessRequestOptions) {
+            this.preprocessRequestOptions = options.preprocessRequestOptions;
+        }
+        if (options.throttlingOptions) {
+            this.throttlingOptions = options.throttlingOptions;
+        }
+        const defaultRequestOptions = {
+            ...(this.configFieldIsValid(ca) && { ca: fs_1.default.readFileSync(ca) }),
+            ...(this.configFieldIsValid(cert) && { cert: fs_1.default.readFileSync(cert) }),
+            ...(this.configFieldIsValid(key) && { key: fs_1.default.readFileSync(key) }),
+            ...(this.configFieldIsValid(passphrase) && { passphrase }),
+            ...(this.configFieldIsValid(proxy) && { proxy }),
+            ...(typeof rejectUnauthorized === 'boolean' && { rejectUnauthorized }),
+            json
+        };
+        this.requestWithDefaults = (0, util_1.promisify)(postman_request_1.default.defaults(defaultRequestOptions));
+    }
+    configFieldIsValid = (field) => typeof field === 'string' && field.length > 0;
+    /**
+     * Makes a single HTTP request and returns the response or throws an error
+     *
+     * @param requestOptions - request options used to make the HTTP request
+     * @returns The HTTP response
+     */
+    async run(requestOptions) {
+        if (!this.userOptions) {
+            throw new errors_1.LibraryUsageError('PolarityRequest property `userOptions` must be set before calling `run` method');
+        }
+        // Note that we specifically pass a copy of requestOptions to `preprocessRequestOptions`
+        // which lets the user modify the requestOptions object without affecting the original
+        const postprocessedRequestOptions = await this.preprocessRequestOptions({
+            ...requestOptions
+        }, this.userOptions);
+        let postprocessRequestResults;
+        try {
+            const httpResponse = await (this.bottleneckLimiter
+                ? this.bottleneckLimiter.schedule(this.requestWithDefaults, postprocessedRequestOptions)
+                : this.requestWithDefaults(postprocessedRequestOptions));
+            if (this.bottleneckLimiter) {
+                this.logger.trace({ httpResponse }, 'HTTP Response via Bottleneck');
+            }
+            else {
+                this.logger.trace({ httpResponse }, 'HTTP Response');
+            }
+            this.maybeThrowApiRequestError(httpResponse, postprocessedRequestOptions);
+            postprocessRequestResults = await this.postprocessRequestSuccess(httpResponse, postprocessedRequestOptions, this.userOptions);
+        }
+        catch (requestError) {
+            let transformedError = requestError;
+            if (requestError instanceof errors_1.LibraryUsageError) {
+                throw requestError;
+            }
+            if (!(requestError instanceof errors_1.ApiRequestError)) {
+                transformedError = new errors_1.NetworkError('Network error encountered during request', {
+                    cause: requestError,
+                    requestOptions: postprocessedRequestOptions,
+                    requestOptionsToSanitize: this.requestOptionsToSanitize
+                });
+            }
+            if (requestError instanceof bottleneck_1.default.BottleneckError) {
+                transformedError = new errors_1.RetryRequestError('This request has been dropped for going over Integration Configured API Throttling Limits', {
+                    requestOptions: postprocessedRequestOptions,
+                    requestOptionsToSanitize: this.requestOptionsToSanitize
+                });
+            }
+            // Possibly throws an error
+            await this.postprocessRequestFailure(transformedError, postprocessedRequestOptions, this.userOptions);
+        }
+        return postprocessRequestResults;
+    }
+    /**
+     * Checks whether the HTTP response is an API error and throws an ApiRequestError if it is.
+     *
+     * @param httpResponse - The HTTP response from the Postman request.
+     * @param requestOptions - The options used for the request.
+     *
+     * @throws {@link ApiRequestError}
+     * Throws an error if the response indicates an API error.
+     */
+    maybeThrowApiRequestError(httpResponse, requestOptions) {
+        const { statusCode, body } = httpResponse;
+        const requestOptionsWithoutSensitiveData = (0, sanitize_request_options_1.sanitizeRequestOptions)(requestOptions, this.requestOptionsToSanitize);
+        this.logger.trace({
+            requestOptions: requestOptionsWithoutSensitiveData,
+            statusCode,
+            responseBody: body
+        }, 'Request ran, checking for status error');
+        let hasApiError;
+        let message;
+        if (this.isApiError) {
+            const result = this.isApiError(httpResponse, requestOptions, this.userOptions);
+            if (!result || typeof result.isApiError !== 'boolean') {
+                throw new errors_1.LibraryUsageError('PolarityRequest property `isApiError` must return an object containing an `isApiError` property with a boolean value.  It can also optionally include a `message` property with a custom error message.');
+            }
+            hasApiError = result.isApiError;
+            message = result.message
+                ? result.message
+                : this.getErrorMessageFromHttpResponse(body, 'Unexpected Error HTTP Response Received');
+        }
+        else if (this.isHttpStatusCodeError(statusCode)) {
+            hasApiError = true;
+            message = this.getErrorMessageFromHttpResponse(body, `Unexpected HTTP Status Code ${statusCode} Received`);
+        }
+        else if (this.hasHttpResponseErrorProperty(body)) {
+            hasApiError = true;
+            message = this.getErrorMessageFromHttpResponse(body, 'Unexpected Error HTTP Response Received');
+        }
+        if (hasApiError) {
+            throw new errors_1.ApiRequestError(message, {
+                status: statusCode.toString(),
+                requestOptions: requestOptionsWithoutSensitiveData,
+                requestOptionsToSanitize: this.requestOptionsToSanitize,
+                meta: {
+                    body
+                }
+            });
+        }
+    }
+    /**
+     * Returns true if the `httpStatusCode` is not one of the rounded HTTP status codes
+     * specified in the PolarityRequest `roundedSuccessStatusCodes` property.
+     *
+     * @param httpStatusCode - A numeric HTTP Status Code
+     * @returns true if the provided `httpStatusCode` is an error code
+     */
+    isHttpStatusCodeError(httpStatusCode) {
+        const roundedStatus = Math.round(httpStatusCode / 100) * 100;
+        const statusCodeNotSuccessful = !this.roundedSuccessStatusCodes.includes(roundedStatus);
+        return statusCodeNotSuccessful;
+    }
+    /**
+     * Returns true indicating that the API returned an error  if the `httpBody` contains
+     * one of the paths specified by the PolarityRequest `httpResponseErrorProperties`
+     * property.
+     *
+     * @param httpBody - body property from the HttpRequestResponse
+     * @returns `true` if the httpBody property contains properties specified in `httpResponseErrorProperties`
+     */
+    hasHttpResponseErrorProperty(httpBody) {
+        return this.httpResponseErrorProperties.some((property) => (0, has_js_1.default)(httpBody, property));
+    }
+    /**
+     * Returns an error message based on the `httpResponseErrorMessageProperties` first.  If no
+     * message is found, it then uses the `httpResponseErrorProperties` to attempt to find
+     * a suitable error message.  If no message is still found, the `defaultMessage` is returned.
+     *
+     * @param httpBody - JSON Object returned by an HTTP Request
+     * @param defaultMessage - A default error message to use if no specific error messages are found
+     * @returns An error message
+     */
+    getErrorMessageFromHttpResponse(httpBody, defaultMessage) {
+        let message = this.maybeGetStringPropertyValue(httpBody, this.httpResponseErrorMessageProperties);
+        if (!message) {
+            message = this.maybeGetStringPropertyValue(httpBody, this.httpResponseErrorProperties);
+        }
+        return message ? message : defaultMessage;
+    }
+    /**
+     * Given a list of `properties` which are strings representing JSON dot notation, this
+     * method returns the first string property found at the given JSON path
+     * in the given `object`.
+     *
+     * @param object - An object to find properties in
+     * @param properties - a list of JSON dot notation properties to look for within `object`
+     * @returns A string value of the property found within the given object or undefined if no value is found
+     */
+    maybeGetStringPropertyValue(object, properties) {
+        let message;
+        properties.some((property) => {
+            if ((0, has_js_1.default)(object, property)) {
+                const propertyValue = (0, get_js_1.default)(object, property);
+                if (typeof propertyValue === 'string') {
+                    message = propertyValue;
+                    return true;
+                }
+            }
+        });
+        return message;
+    }
+    /**
+     * Runs multiple requests in parallel with a limit on the maximum number of concurrent requests.
+     *
+     * When running multiple request at once it is often useful to be able to tie a specific request
+     * back to the entity the request is for.  To support this, the `HttpRequestOptions` object accepts
+     * an optional `entity` property which can be assigned to the Entity the request is being made for.
+     * The `HttpRequestResponse` object returned by this method will include the same `entity` property
+     * making it easy to match the response to the entity.
+     *
+     * Alternatively, for requests that are made for multiple entities at once (e.g., a query that can
+     * search multiple entities at a time), the `HttpRequestOptions` object also has an `entities`
+     * property which accept an array of entity objects.  Similar to the `entity`, the
+     * `entities` property will be set on the `HttpRequestResponse` object.
+     *
+     * Finally, if you are looking to pass through a custom request id you can do that using the
+     * `requestId` property.
+     *
+     * @param options - An array of request options for running requests in parallel.
+     * @returns A promise that resolves to an array of responses.  If the `returnErrors` property is set to `true`
+     * then the response objects will have their `error` property set to the thrown error.
+     */
+    async runInParallel(options) {
+        const allRequestOptions = options.allRequestOptions;
+        const returnErrors = options.returnErrors || false;
+        const maxConcurrentRequests = options.maxConcurrentRequests || 5;
+        if (!Array.isArray(allRequestOptions)) {
+            throw new errors_1.LibraryUsageError('Invalid or missing option for PolarityRequest.runInParallel(): `allRequestOptions` is a required option and must be an array of `HttpRequestOptions` with at least one `HttpRequestOptions` object in it.');
+        }
+        // REVIEW: We're currently supporting tying the entity to the request by using
+        // the `entity` property, the `entities` property, or the generic `requestId` property.
+        const tasks = allRequestOptions.map((requestOptions) => {
+            return async () => {
+                try {
+                    const response = await this.run(requestOptions);
+                    if (requestOptions.entity) {
+                        response.entity = requestOptions.entity;
+                    }
+                    else if (requestOptions.entities) {
+                        response.entities = requestOptions.entities;
+                    }
+                    else if (requestOptions.requestId) {
+                        response.requestId = requestOptions.requestId;
+                    }
+                    return response;
+                }
+                catch (requestError) {
+                    if (returnErrors) {
+                        return {
+                            error: requestError
+                        };
+                    }
+                    else {
+                        throw requestError;
+                    }
+                }
+            };
+        });
+        const results = await (0, parallel_limit_1.parallelLimit)(tasks, maxConcurrentRequests);
+        return results;
+    }
+}
+exports.PolarityRequest = PolarityRequest;