polarity-integration-utils 0.1.0 → 2.0.8

package/dist/lib/errors/network-error.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NetworkError = void 0;
+const integration_error_1 = require("./integration-error");
+// The following is a list of NodeJS error codes that are related
+// to TLS/SSL certificate errors.  These can be encountered when attempting to connect
+// to a server/API/endpoint that has an invalid or untrusted TLS certificate.
+//
+// These codes were taken from this github issue:
+// https://github.com/nodejs/node/issues/29342
+const SSL_ERROR_CODES = new Set([
+    'UNABLE_TO_GET_ISSUER_CERT',
+    'UNABLE_TO_GET_CRL',
+    'UNABLE_TO_DECRYPT_CERT_SIGNATURE',
+    'UNABLE_TO_DECRYPT_CRL_SIGNATURE',
+    'UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY',
+    'CERT_SIGNATURE_FAILURE',
+    'CRL_SIGNATURE_FAILURE',
+    'CERT_NOT_YET_VALID',
+    'CERT_HAS_EXPIRED',
+    'CRL_NOT_YET_VALID',
+    'CRL_HAS_EXPIRED',
+    'ERROR_IN_CERT_NOT_BEFORE_FIELD',
+    'ERROR_IN_CERT_NOT_AFTER_FIELD',
+    'ERROR_IN_CRL_LAST_UPDATE_FIELD',
+    'ERROR_IN_CRL_NEXT_UPDATE_FIELD',
+    'OUT_OF_MEM',
+    'DEPTH_ZERO_SELF_SIGNED_CERT',
+    'SELF_SIGNED_CERT_IN_CHAIN',
+    'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+    'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+    'CERT_CHAIN_TOO_LONG',
+    'CERT_REVOKED',
+    'INVALID_CA',
+    'PATH_LENGTH_EXCEEDED',
+    'INVALID_PURPOSE',
+    'CERT_UNTRUSTED',
+    'CERT_REJECTED'
+]);
+// The following is a list of NodeJS error codes that are related to network connectivity issues
+const NETWORK_CONNECTION_ERROR_CODES = new Set([
+    'ECONNRESET',
+    'ENOTFOUND',
+    'ETIMEDOUT',
+    'ECONNREFUSED',
+    'EHOSTUNREACH'
+]);
+/**
+ * Generic network error for REST requests.
+ * https://betterstack.com/community/guides/scaling-nodejs/nodejs-errors/#4-econnrefused
+ *
+ * @public
+ */
+class NetworkError extends integration_error_1.IntegrationError {
+    constructor(message, properties = {}) {
+        super(message, properties);
+        // Check if we are wrapping an original error
+        if (properties.cause instanceof Error) {
+            const originalError = properties.cause;
+            const code = originalError.code?.toString();
+            if (code && SSL_ERROR_CODES.has(code)) {
+                // @ts-expect-error work around due to typescript preventing readonly properties from
+                // parent constructor from being modified in subclass constructor
+                this.help =
+                    'SSL errors are typically caused by an untrusted SSL certificate in the HTTPS request chain (e.g., ' +
+                        'an internal server that is being queried directly, or a web proxy for external requests). You can temporarily ' +
+                        'ignore SSL validation errors by enabling the integration setting "Allow Insecure TLS/SSL Connections". In most ' +
+                        'cases, you will need to add your organization\'s Certificate Authority to the Polarity Server to resolve the ' +
+                        'issue permanently.';
+            }
+            else if (code && code === 'ENOTFOUND') {
+                // @ts-expect-error work around due to typescript preventing readonly properties from
+                // parent constructor from being modified in subclass constructor
+                this.help =
+                    'The ENOTFOUND exception arises when the integration is unable to establish a connection to a domain due to a DNS error. It is commonly caused by incorrect host values or a typo in the domain name the integration is attempting to reach.  This error can also be caused by a misconfigured proxy or firewall rule';
+            }
+            else if (code && NETWORK_CONNECTION_ERROR_CODES.has(code)) {
+                // @ts-expect-error work around due to typescript preventing readonly properties from
+                // parent constructor from being modified in subclass constructor
+                this.help =
+                    'Network connection issues are typically caused by a misconfigured proxy or firewall rule. You may ' +
+                        'need to add a proxy configuration to the integration and/or confirm that connectivity between the Polarity ' +
+                        'Server and the intended host is available.';
+            }
+        }
+    }
+}
+exports.NetworkError = NetworkError;

package/dist/lib/errors/parse-error-to-readable-json.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseErrorToReadableJson = void 0;
+/**
+ * @public
+ * @param error - Error instance to parse into a plain old javascript object
+ */
+const parseErrorToReadableJson = (error) => JSON.parse(JSON.stringify(error, Object.getOwnPropertyNames(error)));
+exports.parseErrorToReadableJson = parseErrorToReadableJson;

package/dist/lib/errors/retry-request-error.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryRequestError = void 0;
+const integration_error_1 = require("./integration-error");
+/**
+ * Thrown by authenticated request method for any HTTP status codes where we want to allow
+ * the user to retry their lookup.
+ *
+ * @public
+ */
+class RetryRequestError extends integration_error_1.IntegrationError {
+    constructor(message, properties = {}) {
+        super(message, properties);
+    }
+}
+exports.RetryRequestError = RetryRequestError;

package/dist/lib/index.docs.js

@@ -0,0 +1,24 @@
+"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 });
+/**
+ * API Docs index. This is used by api-extractor given our package.json exports.
+ * Monitoring: https://github.com/microsoft/rushstack/issues/3557
+ */
+__exportStar(require("./errors"), exports);
+__exportStar(require("./requests"), exports);
+__exportStar(require("./logging"), exports);
+__exportStar(require("./types"), exports);

package/dist/lib/index.js

@@ -1,16 +1,42 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
+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;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.userOptions = exports.logging = exports.requests = exports.helpers = exports.errors = void 0;
-const errors_1 = __importDefault(require("./errors"));
-exports.errors = errors_1.default;
-const helpers_1 = __importDefault(require("./helpers"));
-exports.helpers = helpers_1.default;
-const requests_1 = __importDefault(require("./requests"));
-exports.requests = requests_1.default;
-const logging_1 = __importDefault(require("./logging"));
-exports.logging = logging_1.default;
-const user_options_1 = __importDefault(require("./user-options"));
-exports.userOptions = user_options_1.default;
+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;

package/dist/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/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/lib/logging/index.js

@@ -1,4 +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 });
-const logger_1 = require("./logger");
-exports.default = { getLogger: logger_1.getLogger, setLogger: logger_1.setLogger };
+__exportStar(require("./logger"), exports);

package/dist/lib/logging/logger.js

@@ -5,13 +5,49 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getLogger = exports.setLogger = void 0;
 const fs_1 = __importDefault(require("fs"));
-const fp_1 = require("lodash/fp");
 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));
-let logger = (0, fp_1.flow)((0, fp_1.reduce)((agg, level) => (Object.assign(Object.assign({}, agg), { [level]: writeToDevRunnerResults(level) })), {}))(loggingLevels);
-const setLogger = (_logger) => {
-    logger = _logger;
+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;
-const getLogger = () => logger;
+/**
+ * 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/lib/requests/index.js

@@ -1,11 +1,18 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
+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 });
-const createRequestWithDefaults_1 = __importDefault(require("./createRequestWithDefaults"));
-const createRequestsInParallel_1 = __importDefault(require("./createRequestsInParallel"));
-exports.default = {
-    createRequestWithDefaults: createRequestWithDefaults_1.default,
-    createRequestsInParallel: createRequestsInParallel_1.default
-};
+__exportStar(require("./polarity-request"), exports);
+__exportStar(require("./sanitize-request-options"), exports);