@mimik/api-helper 2.0.10 → 3.0.1

package/README.md

@@ -1,94 +1,86 @@
+## Modules
+
+<dl>
+<dt><a href="#module_api-helper">api-helper</a></dt>
+<dd></dd>
+</dl>
+
+## Typedefs
+
+<dl>
+<dt><a href="#UUID">UUID</a> : <code>string</code></dt>
+<dd><p>UUID string in RFC 4122 format.</p>
+</dd>
+<dt><a href="#PATH">PATH</a> : <code>string</code></dt>
+<dd><p>File system path string.</p>
+</dd>
+</dl>
+
 <a name="module_api-helper"></a>
 
 ## api-helper
 **Example**  
 ```js
 import apiHelper from '@mimik/api-helper';
-or
+// or
 import { apiSetup, securityLib, getAPIFile, validateSecuritySchemes, extractProperties, setupServerFiles } from '@mimik/api-helper';
 ```
 
 * [api-helper](#module_api-helper)
     * _async_
-        * [~securityLib(config)](#module_api-helper..securityLib)
-        * [~apiSetup(setup, registeredOperations, securityHandlers, extraFormats, config, correlationId)](#module_api-helper..apiSetup) ⇒ <code>Promise</code>
-        * [~getAPIFile(apiFilename, correlationId, options)](#module_api-helper..getAPIFile) ⇒ <code>Promise</code>
-        * [~setupServerFiles(apiFilename, controllersDirectory, buildDirectory, correlationId, options)](#module_api-helper..setupServerFiles) ⇒ <code>Promise</code>
+        * [~apiSetup(setup, registeredOperations, securityHandlers, extraFormats, config, correlationId)](#module_api-helper..apiSetup) ⇒ <code>Promise.&lt;object&gt;</code>
+        * [~getAPIFile(apiFilename, correlationId, options)](#module_api-helper..getAPIFile) ⇒ <code>Promise.&lt;object&gt;</code>
+        * [~setupServerFiles(apiFilename, controllersDirectory, buildDirectory, correlationId, options)](#module_api-helper..setupServerFiles) ⇒ <code>Promise.&lt;object&gt;</code>
     * _sync_
-        * [~validateSecuritySchemes(apiDefinition, correlationId)](#module_api-helper..validateSecuritySchemes) ⇒
-        * [~extractProperties(apiDefinition, controllersDirectory, buildDirectory, correlationId)](#module_api-helper..extractProperties) ⇒
-
-<a name="module_api-helper..securityLib"></a>
-
-### api-helper~securityLib(config)
-Implement the security flows for the API.
-
-**Kind**: inner method of [<code>api-helper</code>](#module_api-helper)  
-**Category**: async  
-**Throws**:
-
-- <code>Promise</code> An error is thrown if the initiatilization failed.
-
-This function is used to setup the following security handlers for the API:
-- `SystemSecurity` - used for the system operations, like /system, /onbehalf
-- `AdminSecurity` - used for the admin operations, like /admin,
-- `UserSecurity` - used for the user operations, like /user,
-- `ApiKeySecurity` - used for the API key operations, like /apikey,
-The security handlers are used to validate the tokens and scopes for the API operations.
-
-**Requires**: <code>module:@mimik/swagger-helper</code>, <code>module:jsonwebtoken</code>, <code>module:lodash</code>  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| config | <code>object</code> | Configuration of the service. &fulfil {object} The API file itself. |
+        * [~securityLib(config)](#module_api-helper..securityLib) ⇒ <code>object</code>
+        * [~validateSecuritySchemes(apiDefinition, correlationId)](#module_api-helper..validateSecuritySchemes) ⇒ <code>Array.&lt;string&gt;</code>
+        * [~extractProperties(apiDefinition, controllersDirectory, buildDirectory, correlationId)](#module_api-helper..extractProperties) ⇒ <code>void</code>
 
 <a name="module_api-helper..apiSetup"></a>
 
-### api-helper~apiSetup(setup, registeredOperations, securityHandlers, extraFormats, config, correlationId) ⇒ <code>Promise</code>
-Setup the API to be use for a service
+### api-helper~apiSetup(setup, registeredOperations, securityHandlers, extraFormats, config, correlationId) ⇒ <code>Promise.&lt;object&gt;</code>
+Setup the API to be used for a service
 
 **Kind**: inner method of [<code>api-helper</code>](#module_api-helper)  
-**Returns**: <code>Promise</code> - .
-&fulfil {object} The API file itself.  
+**Returns**: <code>Promise.&lt;object&gt;</code> - The API file itself.  
 **Category**: async  
 **Throws**:
 
-- <code>Promise</code> An error is thrown if the initiatilization failed.
+- <code>Promise</code> An error is thrown if the initialization failed.
 
 The following scheme names are reserved: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`, `ApiKeySecurity`.
 The following security schemes can be defaulted: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `ApiKeySecurity`.
 The secOptions in the options property passed when using `init` allows the following operations:
 - introduce a customer security scheme, in this case secOptions contains: { newSecurityScheme: {function}newSecurityHandler },
 - disable a security scheme that is defined in the swagger API, in this case secOptions contains: { securitySchemeToDisable: { {boolean}notEnabled: true } },
-- overwite an existing security scheme, in this case secOptions contains: { securitySchemeToOverwrite: {function}newSecurityHandler }.
+- overwrite an existing security scheme, in this case secOptions contains: { securitySchemeToOverwrite: {function}newSecurityHandler }.
 If the secOptions is not present either to introduce, disable or overwrite a security scheme that is present in the swagger API file an error is generated.
 If the secOptions contains unused security schemes, an error is generated.
 
 The default formats for validation are: `date`, `time`, `date-time`, `byte`, `uuid`, `uri`, `email`, `ipv4`, `ipv6`, `semver`, `ip`.
 
-**Requires**: <code>module:@mimik/response-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>, <code>module:@mimik/swagger-helper</code>, <code>module:ajv-formats</code>, <code>module:fs</code>, <code>module:jsonwebtoken</code>, <code>module:lodash</code>  
+**Requires**: <code>module:@mimik/response-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>, <code>module:openapi-backend</code>  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| setup | <code>object</code> | Object containing the apiFilename and the exisiting security schemes in the API definition. |
+| setup | <code>object</code> | Object containing the apiFilename and the existing security schemes in the API definition. |
 | registeredOperations | <code>object</code> | List of the operation to register for the API. |
 | securityHandlers | <code>object</code> | List of the security handlers to add for the service. |
-| extraFormats | <code>object</code> | list of the formats to add for validatng properties. |
+| extraFormats | <code>object</code> | list of the formats to add for validating properties. |
 | config | <code>object</code> | Configuration of the service. |
-| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |
+| correlationId | [<code>UUID</code>](#UUID) | CorrelationId when logging activities. |
 
 <a name="module_api-helper..getAPIFile"></a>
 
-### api-helper~getAPIFile(apiFilename, correlationId, options) ⇒ <code>Promise</code>
-Gets the API file from swaggerhub and store it in the give PATH location.
+### api-helper~getAPIFile(apiFilename, correlationId, options) ⇒ <code>Promise.&lt;object&gt;</code>
+Gets the API file from swaggerhub and stores it in the given PATH location.
 
 **Kind**: inner method of [<code>api-helper</code>](#module_api-helper)  
-**Returns**: <code>Promise</code> - .
-&fulfil {object} The API file itself.  
+**Returns**: <code>Promise.&lt;object&gt;</code> - The API file itself.  
 **Category**: async  
 **Throws**:
 
-- <code>Promise</code> An error is  thrown if the apiFilename resolution generates an error or the request to the API provider fails or the file connot be saved.
+- <code>Promise</code> An error is thrown if the apiFilename resolution generates an error or the request to the API provider fails or the file cannot be saved.
 
 `apiInfo` options has the following format:
 ``` javascript
@@ -98,77 +90,109 @@ Gets the API file from swaggerhub and store it in the give PATH location.
      "username": "username for bitbucket",
      "password": "password for bitbucket"
    },
-   "apiApiKey": "apiKey for access private API on swaggerhub, can be optional if the API is accessible publically"
+   "apiApiKey": "apiKey to access private API on swaggerhub, can be optional if the API is accessible publicly"
 }
+```
 
 **Requires**: <code>module:@mimik/request-retry</code>, <code>module:@mimik/response-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>, <code>module:fs</code>, <code>module:js-yaml</code>, <code>module:path</code>  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| apiFilename | <code>PATH.&lt;string&gt;</code> | Name of the file where the API file will be stored. |
-| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |
+| apiFilename | [<code>PATH</code>](#PATH) | Name of the file where the API file will be stored. |
+| correlationId | [<code>UUID</code>](#UUID) | CorrelationId when logging activities. |
 | options | <code>object</code> | Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiInfo` to access the api file in the api provider. |
 
 <a name="module_api-helper..setupServerFiles"></a>
 
-### api-helper~setupServerFiles(apiFilename, controllersDirectory, buildDirectory, correlationId, options) ⇒ <code>Promise</code>
+### api-helper~setupServerFiles(apiFilename, controllersDirectory, buildDirectory, correlationId, options) ⇒ <code>Promise.&lt;object&gt;</code>
 Setup and validates files for the server
 
 **Kind**: inner method of [<code>api-helper</code>](#module_api-helper)  
-**Returns**: <code>Promise</code> - .
-&fulfil {object} The API file, the API filename, the existing known security schemes and the defined security schemes.  
+**Returns**: <code>Promise.&lt;object&gt;</code> - The API file, the API filename, the existing known security schemes and the defined security schemes.  
 **Category**: async  
 **Throws**:
 
-- <code>Promise</code> An error is thrown for many reasons assocated with getAPIFile or validateSecuritySchemes or extractProperties.
+- <code>Promise</code> An error is thrown for many reasons associated with getAPIFile or validateSecuritySchemes or extractProperties.
 
 **Requires**: <code>module:@mimik/request-retry</code>, <code>module:@mimik/response-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>, <code>module:fs</code>, <code>module:js-yaml</code>, <code>module:path</code>  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| apiFilename | <code>PATH.&lt;string&gt;</code> | Name of the file where the API file will be stored. |
-| controllersDirectory | <code>PATH.&lt;string&gt;</code> | Directory to find the controller files. |
-| buildDirectory | <code>PATH.&lt;string&gt;</code> | Directory where the register file will be stored. |
-| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |
-| options | <code>object</code> | Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiKey`` to access private API. |
+| apiFilename | [<code>PATH</code>](#PATH) | Name of the file where the API file will be stored. |
+| controllersDirectory | [<code>PATH</code>](#PATH) | Directory to find the controller files. |
+| buildDirectory | [<code>PATH</code>](#PATH) | Directory where the register file will be stored. |
+| correlationId | [<code>UUID</code>](#UUID) | CorrelationId when logging activities. |
+| options | <code>object</code> | Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiKey` to access private API. |
+
+<a name="module_api-helper..securityLib"></a>
+
+### api-helper~securityLib(config) ⇒ <code>object</code>
+Implement the security flows for the API.
+
+**Kind**: inner method of [<code>api-helper</code>](#module_api-helper)  
+**Returns**: <code>object</code> - An object containing `SystemSecurity`, `AdminSecurity`, `UserSecurity`, and `ApiKeySecurity` handlers.
+
+This function is used to setup the following security handlers for the API:
+- `SystemSecurity` - used for the system operations, like /system, /onbehalf
+- `AdminSecurity` - used for the admin operations, like /admin,
+- `UserSecurity` - used for the user operations, like /user,
+- `ApiKeySecurity` - used for the API key operations, like /apikey,
+The security handlers are used to validate the tokens and scopes for the API operations.  
+**Category**: sync  
+**Requires**: <code>module:@mimik/swagger-helper</code>, <code>module:jsonwebtoken</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| config | <code>object</code> | Configuration of the service. |
 
 <a name="module_api-helper..validateSecuritySchemes"></a>
 
-### api-helper~validateSecuritySchemes(apiDefinition, correlationId) ⇒
+### api-helper~validateSecuritySchemes(apiDefinition, correlationId) ⇒ <code>Array.&lt;string&gt;</code>
 Validates the known SecuritySchemes: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`, `ApiKeySecurity`.
 
 **Kind**: inner method of [<code>api-helper</code>](#module_api-helper)  
-**Returns**: An array of the known securitySchemes that are in the API definition.  
+**Returns**: <code>Array.&lt;string&gt;</code> - An array of the known securitySchemes that are in the API definition.  
 **Category**: sync  
 **Throws**:
 
-- An error is thrown for the first validation fails.
+- An error is thrown if a validation fails.
 
 **Requires**: <code>module:@mimik/sumologic-winston-logger</code>, <code>module:@mimik/response-helper</code>  
 
 | Param | Type | Description |
 | --- | --- | --- |
 | apiDefinition | <code>object</code> | JSON object containing the API definition. |
-| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |
+| correlationId | [<code>UUID</code>](#UUID) | CorrelationId when logging activities. |
 
 <a name="module_api-helper..extractProperties"></a>
 
-### api-helper~extractProperties(apiDefinition, controllersDirectory, buildDirectory, correlationId) ⇒
-Extracts the properties from API definiton and creates a file binding the handler with the controller operations.
+### api-helper~extractProperties(apiDefinition, controllersDirectory, buildDirectory, correlationId) ⇒ <code>void</code>
+Extracts the properties from API definition and creates a file binding the handler with the controller operations.
 
 **Kind**: inner method of [<code>api-helper</code>](#module_api-helper)  
-**Returns**: null  
 **Category**: sync  
 **Throws**:
 
-- An error is thrown for many reasons, like operationId does not exist in controllers, controller dies not exist...
+- An error is thrown for many reasons, like operationId does not exist in controllers, controller does not exist...
 
 **Requires**: <code>module:@mimik/response-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>, <code>module:fs</code>  
 
 | Param | Type | Description |
 | --- | --- | --- |
 | apiDefinition | <code>object</code> | JSON object containing the API definition. |
-| controllersDirectory | <code>PATH.&lt;string&gt;</code> | Directory to find the controller files. |
-| buildDirectory | <code>PATH.&lt;string&gt;</code> | Directory where the register file will be stored. |
-| correlationId | <code>UUID.&lt;string&gt;</code> | CorrelationId when logging activites. |
+| controllersDirectory | [<code>PATH</code>](#PATH) | Directory to find the controller files. |
+| buildDirectory | [<code>PATH</code>](#PATH) | Directory where the register file will be stored. |
+| correlationId | [<code>UUID</code>](#UUID) | CorrelationId when logging activities. |
+
+<a name="UUID"></a>
+
+## UUID : <code>string</code>
+UUID string in RFC 4122 format.
+
+**Kind**: global typedef  
+<a name="PATH"></a>
+
+## PATH : <code>string</code>
+File system path string.
 
+**Kind**: global typedef  

package/index.js

@@ -30,8 +30,6 @@ import { OpenAPIBackend } from 'openapi-backend';
 import SwaggerClient from 'swagger-client';
 import { ajvFormats } from './lib/ajvHelpers.js';
 import baseHandlers from './lib/baseHandlers.js';
-import compact from 'lodash.compact';
-import difference from 'lodash.difference';
 import fs from 'fs';
 import { getRichError } from '@mimik/response-helper';
 import { load } from 'js-yaml';
@@ -40,11 +38,19 @@ import pathLib from 'path';
 import { rpRetry } from '@mimik/request-retry';
 import { saveProperties } from './lib/extract-helper.js';
 import { securityLib } from './lib/securityHandlers.js';
+/**
+ * UUID string in RFC 4122 format.
+ * @typedef {string} UUID
+ */
+/**
+ * File system path string.
+ * @typedef {string} PATH
+ */
 /**
  * @module api-helper
  * @example
  * import apiHelper from '@mimik/api-helper';
- * or
+ * // or
  * import { apiSetup, securityLib, getAPIFile, validateSecuritySchemes, extractProperties, setupServerFiles } from '@mimik/api-helper';
  */
 const EMPTY = 0;
@@ -59,13 +65,11 @@ const POSTFIX_INDEX = 3;
  * Implement the security flows for the API.
  *
  * @function securityLib
- * @category async
+ * @category sync
  * @requires @mimik/swagger-helper
  * @requires jsonwebtoken
- * @requires lodash
  * @param {object} config - Configuration of the service.
- * &fulfil {object} The API file itself.
- * @throws {Promise} An error is thrown if the initiatilization failed.
+ * @return {object} An object containing `SystemSecurity`, `AdminSecurity`, `UserSecurity`, and `ApiKeySecurity` handlers.
  *
  * This function is used to setup the following security handlers for the API:
  * - `SystemSecurity` - used for the system operations, like /system, /onbehalf
@@ -78,33 +82,28 @@ export { securityLib };
 
 /**
  *
- * Setup the API to be use for a service
+ * Setup the API to be used for a service
  *
  * @function apiSetup
  * @category async
  * @requires @mimik/response-helper
  * @requires @mimik/sumologic-winston-logger
- * @requires @mimik/swagger-helper
- * @requires ajv-formats
- * @requires fs
- * @requires jsonwebtoken
- * @requires lodash
- * @param {object} setup -  Object containing the apiFilename and the exisiting security schemes in the API definition.
+ * @requires openapi-backend
+ * @param {object} setup -  Object containing the apiFilename and the existing security schemes in the API definition.
  * @param {object} registeredOperations - List of the operation to register for the API.
  * @param {object} securityHandlers - List of the security handlers to add for the service.
- * @param {object} extraFormats - list of the formats to add for validatng properties.
+ * @param {object} extraFormats - list of the formats to add for validating properties.
  * @param {object} config - Configuration of the service.
- * @param {UUID.<string>} correlationId - CorrelationId when logging activites.
- * @return {Promise}.
- * &fulfil {object} The API file itself.
- * @throws {Promise} An error is thrown if the initiatilization failed.
+ * @param {UUID} correlationId - CorrelationId when logging activities.
+ * @return {Promise.<object>} The API file itself.
+ * @throws {Promise} An error is thrown if the initialization failed.
  *
  * The following scheme names are reserved: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `PeerSecurity`, `ApiKeySecurity`.
  * The following security schemes can be defaulted: `SystemSecurity`, `AdminSecurity`, `UserSecurity`, `ApiKeySecurity`.
  * The secOptions in the options property passed when using `init` allows the following operations:
  * - introduce a customer security scheme, in this case secOptions contains: { newSecurityScheme: {function}newSecurityHandler },
  * - disable a security scheme that is defined in the swagger API, in this case secOptions contains: { securitySchemeToDisable: { {boolean}notEnabled: true } },
- * - overwite an existing security scheme, in this case secOptions contains: { securitySchemeToOverwrite: {function}newSecurityHandler }.
+ * - overwrite an existing security scheme, in this case secOptions contains: { securitySchemeToOverwrite: {function}newSecurityHandler }.
  * If the secOptions is not present either to introduce, disable or overwrite a security scheme that is present in the swagger API file an error is generated.
  * If the secOptions contains unused security schemes, an error is generated.
  *
@@ -142,7 +141,7 @@ export const apiSetup = (setup, registeredOperations, securityHandlers, extraFor
   }
   const appliedSecurities = [];
   const registerDefault = (securitySchemeName, securityHandler) => {
-    if (existingSecuritySchemes.includes(securitySchemeName) && (!securityHandlers || (securityHandlers && !securityHandlers[securitySchemeName]))) {
+    if (existingSecuritySchemes.includes(securitySchemeName) && (!securityHandlers || !securityHandlers[securitySchemeName])) {
       api.registerSecurityHandler(securitySchemeName, securityHandler);
       appliedSecurities.push(securitySchemeName);
     }
@@ -152,16 +151,16 @@ export const apiSetup = (setup, registeredOperations, securityHandlers, extraFor
   registerDefault(ADMIN_SECURITY, AdminSecurity[mode]);
   registerDefault(USER_SECURITY, UserSecurity[mode]);
   registerDefault(API_KEY_SECURITY, ApiKeySecurity[mode]);
-  const remainingSecurities = difference(definedSecuritySchemes, appliedSecurities);
+  const remainingSecurities = definedSecuritySchemes.filter(sec => !appliedSecurities.includes(sec));
 
   if (securityHandlers) {
     const securityHandlerNames = Object.keys(securityHandlers);
-    const unusedSecuritySchemes = difference(securityHandlerNames, definedSecuritySchemes);
+    const unusedSecuritySchemes = securityHandlerNames.filter(sec => !definedSecuritySchemes.includes(sec));
 
     if (unusedSecuritySchemes.length !== EMPTY) throw getRichError('System', 'unused handlers for security schemes', { unusedSecuritySchemes });
 
     remainingSecurities.forEach((securityScheme) => {
-      if (!securityHandlerNames.includes(securityScheme) && !securityHandlers[securityScheme].notEnabled) {
+      if (!securityHandlerNames.includes(securityScheme) && !securityHandlers[securityScheme]?.notEnabled) {
         throw getRichError('System', 'missing handler for security scheme', { securityScheme });
       }
     });
@@ -172,16 +171,72 @@ export const apiSetup = (setup, registeredOperations, securityHandlers, extraFor
     });
   }
   else if (remainingSecurities.length !== EMPTY) throw getRichError('System', 'missing handlers for security schemes', { missingSecuritySchemes: remainingSecurities });
-  api.init()
+  return api.init()
     .catch((err) => {
       throw getRichError('System', 'could not initialize the api', { api }, err);
-    });
-  return api;
+    })
+    .then(() => api);
+};
+
+const swaggerOptions = spec => ({
+  spec,
+  allowMetaPatches: false,
+  skipNormalization: true,
+  mode: 'strict',
+});
+
+const saveResolvedSpec = (apiDefinitionResult, apiFilename, correlationId) => {
+  if (apiDefinitionResult.errors.length !== EMPTY) {
+    logger.error('errors while resolving definition', { errors: apiDefinitionResult.errors }, correlationId);
+    throw getRichError('Parameter', 'errors while resolving definition', { apiFilename, errors: apiDefinitionResult.errors });
+  }
+  try {
+    fs.writeFileSync(apiFilename, JSON.stringify(apiDefinitionResult.spec, null, TAB));
+  }
+  catch (err) {
+    throw getRichError('System', 'file system error', { apiFilename }, err);
+  }
+  return apiDefinitionResult.spec;
+};
+
+const buildProviderRequest = (params, apiInfo, apiFilename) => {
+  const provider = apiInfo.provider || BITBUCKET;
+
+  switch (provider) {
+    case SWAGGERHUB: {
+      const result = {
+        url: `${API_PROVIDER_SWAGGERHUB}/${params[CUSTOMER_INDEX]}/${params[API_NAME_INDEX]}/${params[API_VERSION_INDEX]}?${RESOLVED}`,
+      };
+
+      if (apiInfo.apiApiKey) result.authorization = apiInfo.apiApiKey;
+      return result;
+    }
+    case BITBUCKET: {
+      if (!apiInfo.apiBasicAuth || !apiInfo.apiBasicAuth.username || !apiInfo.apiBasicAuth.password) {
+        throw getRichError('Parameter', 'missing username/password for accessing Bitbucket', { apiFilename });
+      }
+      if (apiInfo.apiBasicAuth.username === DEFAULT_BITBUCKET_USERNAME || apiInfo.apiBasicAuth.password === DEFAULT_BITBUCKET_PASSWORD) {
+        throw getRichError('Parameter', 'missing username/password for accessing Bitbucket', { apiFilename });
+      }
+      try {
+        return {
+          url: `${API_PROVIDER_BITBUCKET}/${params[CUSTOMER_INDEX]}/${params[API_NAME_INDEX]}${API_SOURCE}/${params[API_VERSION_INDEX]}/${SWAGGER}${EXTENSION_YML}`,
+          authorization: `Basic ${Base64.encode(`${apiInfo.apiBasicAuth.username}:${apiInfo.apiBasicAuth.password}`)}`,
+        };
+      }
+      catch (err) {
+        throw getRichError('System', 'could not create basicAuth', { apiFilename }, err);
+      }
+    }
+    default: {
+      throw getRichError('Parameter', 'invalid API provider', { provider, apiFilename });
+    }
+  }
 };
 
 /**
  *
- * Gets the API file from swaggerhub and store it in the give PATH location.
+ * Gets the API file from swaggerhub and stores it in the given PATH location.
  *
  * @function getAPIFile
  * @category async
@@ -191,12 +246,11 @@ export const apiSetup = (setup, registeredOperations, securityHandlers, extraFor
  * @requires fs
  * @requires js-yaml
  * @requires path
- * @param {PATH.<string>} apiFilename -  Name of the file where the API file will be stored.
- * @param {UUID.<string>} correlationId - CorrelationId when logging activites.
+ * @param {PATH} apiFilename -  Name of the file where the API file will be stored.
+ * @param {UUID} correlationId - CorrelationId when logging activities.
  * @param {object} options - Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiInfo` to access the api file in the api provider.
- * @return {Promise}.
- * &fulfil {object} The API file itself.
- * @throws {Promise} An error is  thrown if the apiFilename resolution generates an error or the request to the API provider fails or the file connot be saved.
+ * @return {Promise.<object>} The API file itself.
+ * @throws {Promise} An error is thrown if the apiFilename resolution generates an error or the request to the API provider fails or the file cannot be saved.
  *
  * `apiInfo` options has the following format:
  * ``` javascript
@@ -206,17 +260,11 @@ export const apiSetup = (setup, registeredOperations, securityHandlers, extraFor
  *      "username": "username for bitbucket",
  *      "password": "password for bitbucket"
  *    },
- *    "apiApiKey": "apiKey for access private API on swaggerhub, can be optional if the API is accessible publically"
+ *    "apiApiKey": "apiKey to access private API on swaggerhub, can be optional if the API is accessible publicly"
  * }
+ * ```
  */
 export const getAPIFile = (apiFilename, correlationId, options) => {
-  const swaggerOptions = spec => ({
-    spec,
-    allowMetaPatches: false,
-    skipNormalization: true,
-    mode: 'strict',
-  });
-
   logger.info('getting API definition', correlationId);
   let apiDefinition;
 
@@ -238,24 +286,12 @@ export const getAPIFile = (apiFilename, correlationId, options) => {
     }
     return SwaggerClient.resolve(swaggerOptions(apiDefinition))
       .catch((err) => {
-        throw getRichError('System', 'could not resolve apiDefiniton', { apiFilename }, err);
+        throw getRichError('System', 'could not resolve apiDefinition', { apiFilename }, err);
       })
-      .then((apiDefinitionResult) => {
-        if (apiDefinitionResult.errors.length !== EMPTY) {
-          logger.error('errors while resolving definition', { errors: apiDefinitionResult.errors }, correlationId);
-          throw getRichError('Parameter', 'errors while resolving definition', { apiFilename, errors: apiDefinitionResult.errors });
-        }
-        try {
-          fs.writeFileSync(apiFilename, JSON.stringify(apiDefinitionResult.spec, null, TAB));
-        }
-        catch (err) {
-          throw getRichError('System', 'file system error', { apiFilename }, err);
-        }
-        return apiDefinitionResult.spec;
-      });
+      .then(result => saveResolvedSpec(result, apiFilename, correlationId));
   }
   if (!options) {
-    return Promise.reject(getRichError('Paremater', 'no options', { apiFilename }));
+    return Promise.reject(getRichError('Parameter', 'no options', { apiFilename }));
   }
   const { apiInfo } = options;
 
@@ -287,56 +323,33 @@ export const getAPIFile = (apiFilename, correlationId, options) => {
   catch (err) {
     return Promise.reject(getRichError('System', 'file system error', { apiDirectory }, err));
   }
+  let providerResult;
+
+  try {
+    providerResult = buildProviderRequest(params, apiInfo, apiFilename);
+  }
+  catch (err) {
+    return Promise.reject(err);
+  }
   const opts = {
     method: 'GET',
+    url: providerResult.url,
     headers: {
       'x-correlation-id': correlationId,
     },
+    retry: {
+      logLevel: {
+        response: 'debug',
+        responseDetails: 'type',
+        request: 'debug',
+      },
+    },
   };
-  const provider = apiInfo.provider || BITBUCKET;
 
-  try {
-    switch (provider) {
-      case SWAGGERHUB: {
-        opts.url = `${API_PROVIDER_SWAGGERHUB}/${params[CUSTOMER_INDEX]}/${params[API_NAME_INDEX]}/${params[API_VERSION_INDEX]}?${RESOLVED}`;
-        if (apiInfo.apiApiKey) opts.headers.Authorization = apiInfo.apiApiKey;
-        break;
-      }
-      case BITBUCKET: {
-        if (!apiInfo.apiBasicAuth || !apiInfo.apiBasicAuth.username || !apiInfo.apiBasicAuth.password) {
-          throw getRichError('Parameter', 'missing username/password for accessing Bitbucket', { apiFilename });
-        }
-        if (apiInfo.apiBasicAuth.username === DEFAULT_BITBUCKET_USERNAME || apiInfo.apiBasicAuth.password === DEFAULT_BITBUCKET_PASSWORD) {
-          throw getRichError('Parameter', 'missing username/password for accessing Bitbucket', { apiFilename });
-        }
-        try {
-          opts.headers.Authorization = `Basic ${Base64.encode(`${apiInfo.apiBasicAuth.username}:${apiInfo.apiBasicAuth.password}`)}`;
-        }
-        catch (err) {
-          throw getRichError('System', 'could not create basicAuth', { apiFilename }, err);
-        }
-        opts.url = `${API_PROVIDER_BITBUCKET}/${params[CUSTOMER_INDEX]}/${params[API_NAME_INDEX]}${API_SOURCE}/${params[API_VERSION_INDEX]}/${SWAGGER}${EXTENSION_YML}`;
-        break;
-      }
-      default: {
-        throw getRichError('Parameter', 'invalid API provider', { provider, apiFilename });
-      }
-    }
-  }
-  catch (err) {
-    return Promise.reject(err);
-  }
+  if (providerResult.authorization) opts.headers.Authorization = providerResult.authorization;
   if (options.metrics) {
-    opts.metrics = options.metrics;
-    opts.metrics.url = opts.url;
+    opts.metrics = { ...options.metrics, url: opts.url };
   }
-  opts.retry = {
-    logLevel: {
-      response: 'debug',
-      responseDetails: 'type',
-      request: 'debug',
-    },
-  };
   logger.debug('API file does not exist, retrieving it', { url: opts.url }, correlationId);
   return rpRetry(opts)
     .then((result) => {
@@ -349,21 +362,9 @@ export const getAPIFile = (apiFilename, correlationId, options) => {
       if (err.statusCode) {
         throw err;
       }
-      throw getRichError('System', 'could not resolve apiDefiniton', { apiFilename }, err);
+      throw getRichError('System', 'could not resolve apiDefinition', { apiFilename }, err);
     })
-    .then((apiDefinitionResult) => {
-      if (apiDefinitionResult.errors.length !== EMPTY) {
-        logger.error('errors while resolving definition', { errors: apiDefinitionResult.errors }, correlationId);
-        throw getRichError('Parameter', 'errors while resolving definition', { apiFilename, errors: apiDefinitionResult.errors });
-      }
-      try {
-        fs.writeFileSync(apiFilename, JSON.stringify(apiDefinitionResult.spec, null, TAB));
-      }
-      catch (err) {
-        throw getRichError('System', 'file system error', { apiFilename }, err);
-      }
-      return apiDefinitionResult.spec;
-    });
+    .then(result => saveResolvedSpec(result, apiFilename, correlationId));
 };
 
 /**
@@ -375,9 +376,9 @@ export const getAPIFile = (apiFilename, correlationId, options) => {
  * @requires @mimik/sumologic-winston-logger
  * @requires @mimik/response-helper
  * @param {object} apiDefinition - JSON object containing the API definition.
- * @param {UUID.<string>} correlationId - CorrelationId when logging activites.
- * @return An array of the known securitySchemes that are in the API definition.
- * @throws An error is thrown for the first validation fails.
+ * @param {UUID} correlationId - CorrelationId when logging activities.
+ * @return {Array.<string>} An array of the known securitySchemes that are in the API definition.
+ * @throws An error is thrown if a validation fails.
  */
 export const validateSecuritySchemes = (apiDefinition, correlationId) => {
   const existingSecuritySchemes = [];
@@ -397,7 +398,7 @@ export const validateSecuritySchemes = (apiDefinition, correlationId) => {
 
 /**
  *
- * Extracts the properties from API definiton and creates a file binding the handler with the controller operations.
+ * Extracts the properties from API definition and creates a file binding the handler with the controller operations.
  *
  * @function extractProperties
  * @category sync
@@ -405,11 +406,11 @@ export const validateSecuritySchemes = (apiDefinition, correlationId) => {
  * @requires @mimik/sumologic-winston-logger
  * @requires fs
  * @param {object} apiDefinition - JSON object containing the API definition.
- * @param {PATH.<string>} controllersDirectory - Directory to find the controller files.
- * @param {PATH.<string>} buildDirectory - Directory where the register file will be stored.
- * @param {UUID.<string>} correlationId - CorrelationId when logging activites.
- * @return null
- * @throws An error is thrown for many reasons, like operationId does not exist in controllers, controller dies not exist...
+ * @param {PATH} controllersDirectory - Directory to find the controller files.
+ * @param {PATH} buildDirectory - Directory where the register file will be stored.
+ * @param {UUID} correlationId - CorrelationId when logging activities.
+ * @return {void}
+ * @throws An error is thrown for many reasons, like operationId does not exist in controllers, controller does not exist...
  */
 export const extractProperties = (apiDefinition, controllersDirectory, buildDirectory, correlationId) => {
   const result = {};
@@ -490,18 +491,17 @@ export const extractProperties = (apiDefinition, controllersDirectory, buildDire
  * @requires fs
  * @requires js-yaml
  * @requires path
- * @param {PATH.<string>} apiFilename -  Name of the file where the API file will be stored.
- * @param {PATH.<string>} controllersDirectory - Directory to find the controller files.
- * @param {PATH.<string>} buildDirectory - Directory where the register file will be stored.
- * @param {UUID.<string>} correlationId - CorrelationId when logging activites.
- * @param {object} options - Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiKey`` to access private API.
- * @return {Promise}.
- * &fulfil {object} The API file, the API filename, the existing known security schemes and the defined security schemes.
- * @throws {Promise} An error is thrown for many reasons assocated with getAPIFile or validateSecuritySchemes or extractProperties.
+ * @param {PATH} apiFilename -  Name of the file where the API file will be stored.
+ * @param {PATH} controllersDirectory - Directory to find the controller files.
+ * @param {PATH} buildDirectory - Directory where the register file will be stored.
+ * @param {UUID} correlationId - CorrelationId when logging activities.
+ * @param {object} options - Options associated with the call. Use to pass `metrics` to `rpRetry` and `apiKey` to access private API.
+ * @return {Promise.<object>} The API file, the API filename, the existing known security schemes and the defined security schemes.
+ * @throws {Promise} An error is thrown for many reasons associated with getAPIFile or validateSecuritySchemes or extractProperties.
  */
 export const setupServerFiles = (apiFilename, controllersDirectory, buildDirectory, correlationId, options) => getAPIFile(apiFilename, correlationId, options)
   .then((apiDefinition) => {
-    const existingSecuritySchemes = compact(validateSecuritySchemes(apiDefinition, correlationId));
+    const existingSecuritySchemes = validateSecuritySchemes(apiDefinition, correlationId).filter(Boolean);
 
     extractProperties(apiDefinition, controllersDirectory, buildDirectory, correlationId);
     const schemes = apiDefinition.components?.securitySchemes;

package/lib/ajvHelpers.js

@@ -14,7 +14,7 @@ const ajvFormats = origFormats => (ajv) => {
       validate: /((^\s*((([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5]))\s*$)|(^\s*((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6}(:[0-9A-Fa-f]{1,4}|((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){5}(((:[0-9A-Fa-f]{1,4}){1,2})|:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3})|:))|(([0-9A-Fa-f]{1,4}:){4}(((:[0-9A-Fa-f]{1,4}){1,3})|((:[0-9A-Fa-f]{1,4})?:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){3}(((:[0-9A-Fa-f]{1,4}){1,4})|((:[0-9A-Fa-f]{1,4}){0,2}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){2}(((:[0-9A-Fa-f]{1,4}){1,5})|((:[0-9A-Fa-f]{1,4}){0,3}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(([0-9A-Fa-f]{1,4}:){1}(((:[0-9A-Fa-f]{1,4}){1,6})|((:[0-9A-Fa-f]{1,4}){0,4}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:))|(:(((:[0-9A-Fa-f]{1,4}){1,7})|((:[0-9A-Fa-f]{1,4}){0,5}:((25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}))|:)))(%.+)?\s*$))/u,
     },
   };
-  const libFormats = DEFAULT_FORMATS;
+  const libFormats = [...DEFAULT_FORMATS];
   let formats = origFormats;
 
   if (!formats) formats = {};

package/lib/baseHandlers.js

@@ -34,9 +34,8 @@ const unauthorizedHandler = (con, req, res) => {
   let error = new Error('Unauthorized');
 
   error.statusCode = UNAUTHORIZED_ERROR;
-  const schemes = Object.keys(con.security);
+  const schemes = Object.keys(con.security).filter(key => key !== 'authorized');
 
-  delete schemes.authorized;
   schemes.forEach((scheme) => {
     const { error: schemeError } = con.security[scheme] || {};
     if (schemeError) {
@@ -49,7 +48,7 @@ const unauthorizedHandler = (con, req, res) => {
 const notImplemented = (con, req, res) => {
   const { method } = req;
   const path = req.url;
-  const error = new Error(`${req.method} ${path} defined in Swagger specification, but no implemented`);
+  const error = new Error(`${method} ${path} defined in Swagger specification, but not implemented`);
 
   error.statusCode = NOT_IMPLEMENTED_ERROR;
   error.info = {

package/lib/oauthValidation-helper.js

@@ -13,7 +13,7 @@ const validateOauth2 = (securitySchemes, securityType, flow) => {
       if (security.type !== OAUTH2) {
         throw getRichError('System', `auth type is not ${OAUTH2}`, { securityType, receivedAuth: security.type, expectedAuth: OAUTH2 });
       }
-      if (!security.flows[flow]) {
+      if (!security.flows || !security.flows[flow]) {
         throw getRichError('System', 'no flow type available', { securityType, flow });
       }
       return securityType;

package/lib/securityHandlers.js

@@ -19,8 +19,6 @@ import {
   USER_SECURITY,
 } from './common.js';
 import { TOKEN_PARAMS } from '@mimik/swagger-helper';
-import difference from 'lodash.difference';
-import intersection from 'lodash.intersection';
 import jwt from 'jsonwebtoken';
 
 const UNAUTHORIZED_ERROR = 401;
@@ -93,7 +91,7 @@ const checkHeaders = (headers) => {
 
 const checkScopes = (tokenScopes, defScopes, definition) => {
   if (!tokenScopes) {
-    throw new Error('no scope in authorization token');
+    throw getError('no scope in authorization token', UNAUTHORIZED_ERROR);
   }
   let claims = [];
   let onBehalf = false;
@@ -126,10 +124,10 @@ const checkScopes = (tokenScopes, defScopes, definition) => {
           }
           const includedClaims = analyzedScope[CLAIMS_INDEX].split(CLAIMS_SEPARATOR);
           const definitionClaims = Object.keys(includedDefinition);
-          const claimsIntersects = intersection(includedClaims, definitionClaims);
+          const claimsIntersects = includedClaims.filter(cla => definitionClaims.includes(cla));
 
           if (claimsIntersects.length !== includedClaims.length) {
-            throw getError(`incorrect claims included: ${difference(includedClaims, claimsIntersects)}`, FORBIDDEN_ERROR);
+            throw getError(`incorrect claims included: ${includedClaims.filter(cla => !claimsIntersects.includes(cla))}`, FORBIDDEN_ERROR);
           }
           claims = claims.concat(claimsIntersects);
         }

package/package.json

@@ -1,23 +1,17 @@
 {
   "name": "@mimik/api-helper",
-  "version": "2.0.10",
+  "version": "3.0.1",
   "description": "helper for openAPI backend and mimik service",
   "main": "./index.js",
-  "type": "module",  
+  "type": "module",
   "scripts": {
     "lint": "eslint . --no-error-on-unmatched-pattern",
     "docs": "jsdoc2md index.js > README.md",
-    "test": "echo \"Error: no test specified\" && exit 0",
-    "test-ci": "echo \"Error: no test specified\" && exit 0",
+    "test": "mocha --reporter mochawesome test/ --recursive",
+    "test-ci": "c8 --reporter=lcov --reporter=text npm test",
     "prepublishOnly": "npm run docs && npm run lint && npm run test-ci",
     "commit-ready": "npm run docs && npm run lint && npm run test-ci"
   },
-  "husky": {
-    "hooks": {
-      "pre-commit": "npm run commit-ready",
-      "pre-push": "npm run test"
-    }
-  },
   "keywords": [
     "mimik",
     "microservice",
@@ -25,33 +19,38 @@
   ],
   "author": "mimik technology inc <support@mimik.com> (https://developer.mimik.com/)",
   "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
   "repository": {
     "type": "git",
     "url": "https://bitbucket.org/mimiktech/api-helper"
   },
   "dependencies": {
-    "@mimik/request-helper":"^2.0.2",
-    "@mimik/request-retry": "^4.0.3",
-    "@mimik/response-helper": "^4.0.4",
-    "@mimik/sumologic-winston-logger": "^2.0.3",
-    "@mimik/swagger-helper": "^5.0.2",
+    "@mimik/request-retry": "^4.0.9",
+    "@mimik/response-helper": "^4.0.10",
+    "@mimik/sumologic-winston-logger": "^2.1.14",
+    "@mimik/swagger-helper": "^5.0.3",
     "ajv-formats": "3.0.1",
-    "js-base64": "3.7.7",
-    "js-yaml":"4.1.0",
-    "jsonwebtoken": "9.0.2",
-    "lodash.compact": "3.0.1", 
-    "lodash.difference": "4.5.0",
-    "lodash.intersection": "4.4.0",
-    "openapi-backend": "5.13.0",
-    "swagger-client": "3.35.6"
+    "js-base64": "3.7.8",
+    "js-yaml": "4.1.1",
+    "jsonwebtoken": "9.0.3",
+    "openapi-backend": "5.16.1",
+    "swagger-client": "3.37.0"
   },
   "devDependencies": {
     "@eslint/js": "9.32.0",
     "@mimik/eslint-plugin-document-env": "^2.0.8",
-    "@stylistic/eslint-plugin": "5.2.2",
+    "@stylistic/eslint-plugin": "5.9.0",
+    "c8": "11.0.0",
+    "chai": "6.2.2",
     "eslint": "9.32.0",
     "eslint-plugin-import": "2.32.0",
+    "esmock": "2.7.3",
+    "globals": "17.4.0",
     "husky": "9.1.7",
-    "jsdoc-to-markdown": "9.1.2"
+    "jsdoc-to-markdown": "9.1.3",
+    "mocha": "11.7.5",
+    "mochawesome": "7.1.4"
   }
 }

package/.nycrc

@@ -1,4 +0,0 @@
-{
-  "exclude": ["gulpfile.js"],
-  "reporter": ["lcov", "text"]
-}

package/eslint.config.js

@@ -1,63 +0,0 @@
-import importPlugin from 'eslint-plugin-import';
-import js from '@eslint/js';
-import processDoc from '@mimik/eslint-plugin-document-env';
-import stylistic from '@stylistic/eslint-plugin';
-
-const MAX_LENGTH_LINE = 180;
-const MAX_FUNCTION_PARAMETERS = 6;
-const MAX_LINES_IN_FILES = 600;
-const MAX_LINES_IN_FUNCTION = 150;
-const MAX_STATEMENTS_IN_FUNCTION = 45;
-const MIN_KEYS_IN_OBJECT = 10;
-const MAX_COMPLEXITY = 30;
-
-export default [
-  {
-    ignores: ['mochawesome-report/**', 'node_modules/**', 'dist/**'],
-  },
-  importPlugin.flatConfigs.recommended,
-  stylistic.configs.recommended,
-  js.configs.all,
-  {
-    plugins: {
-      processDoc,
-    },
-    languageOptions: {
-      ecmaVersion: 2022,
-      globals: {
-        console: 'readonly',
-        describe: 'readonly',
-        it: 'readonly',
-        require: 'readonly',
-      },
-      sourceType: 'module',
-    },
-    rules: {
-      '@stylistic/brace-style': ['warn', 'stroustrup', { allowSingleLine: true }],
-      '@stylistic/line-comment-position': ['off'],
-      '@stylistic/semi': ['error', 'always'],
-      'capitalized-comments': ['off'],
-      'complexity': ['error', MAX_COMPLEXITY],
-      'curly': ['off'],
-      'id-length': ['error', { exceptions: ['x', 'y', 'z', 'i', 'j', 'k'] }],
-      'import/no-extraneous-dependencies': ['error', { devDependencies: true }],
-      'import/no-unresolved': ['error', { amd: true, caseSensitiveStrict: true, commonjs: true }],
-      'init-declarations': ['off'],
-      'linebreak-style': ['off'],
-      'max-len': ['warn', MAX_LENGTH_LINE, { ignoreComments: true }],
-      'max-lines': ['warn', { max: MAX_LINES_IN_FILES, skipComments: true }],
-      'max-lines-per-function': ['warn', { max: MAX_LINES_IN_FUNCTION, skipComments: true }],
-      'max-params': ['error', MAX_FUNCTION_PARAMETERS],
-      'max-statements': ['warn', MAX_STATEMENTS_IN_FUNCTION],
-      'no-confusing-arrow': ['off'], // arrow isnt confusing
-      'no-inline-comments': ['off'],
-      'no-process-env': ['error'],
-      'no-ternary': ['off'],
-      'no-undefined': ['off'],
-      'one-var': ['error', 'never'],
-      'processDoc/validate-document-env': ['error'],
-      'quotes': ['warn', 'single'],
-      'sort-keys': ['error', 'asc', { caseSensitive: true, minKeys: MIN_KEYS_IN_OBJECT, natural: false }],
-    },
-  },
-];