@mimik/api-helper 2.0.7 → 2.0.8

package/index.js

@@ -44,7 +44,7 @@ import { securityLib } from './lib/securityHandlers.js';
  * @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 +59,12 @@ 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 +77,29 @@ 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 lodash.difference
+ * @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.<string>} 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 +137,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);
     }
@@ -161,7 +156,7 @@ export const apiSetup = (setup, registeredOperations, securityHandlers, extraFor
     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 +167,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 store it in the given PATH location.
  *
  * @function getAPIFile
  * @category async
@@ -192,11 +243,10 @@ export const apiSetup = (setup, registeredOperations, securityHandlers, extraFor
  * @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 {UUID.<string>} 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 +256,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 for 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 +282,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 +319,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 +358,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 +372,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.<string>} 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 +394,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
@@ -407,9 +404,9 @@ export const validateSecuritySchemes = (apiDefinition, correlationId) => {
  * @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 {UUID.<string>} 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 = {};
@@ -493,11 +490,10 @@ export const extractProperties = (apiDefinition, controllersDirectory, buildDire
  * @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 {UUID.<string>} 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) => {

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

@@ -93,7 +93,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;

package/package.json

@@ -1,23 +1,17 @@
 {
   "name": "@mimik/api-helper",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "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 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,40 @@
   ],
   "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.13",
+    "@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", 
+    "js-base64": "3.7.8",
+    "js-yaml": "4.1.1",
+    "jsonwebtoken": "9.0.3",
+    "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"
+    "openapi-backend": "5.16.1",
+    "swagger-client": "3.36.2"
   },
   "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": "10.1.3",
+    "chai": "6.2.2",
     "eslint": "9.32.0",
     "eslint-plugin-import": "2.32.0",
+    "esmock": "2.7.3",
+    "globals": "17.3.0",
     "husky": "9.1.7",
-    "jsdoc-to-markdown": "9.1.2"
+    "jsdoc-to-markdown": "9.1.3",
+    "mocha": "11.7.5"
   }
 }

package/test/ajvHelpers.test.js

@@ -0,0 +1,159 @@
+import esmock from 'esmock';
+import { expect } from 'chai';
+
+let ajvFormats;
+let addedLibFormats;
+let addedCustomFormats;
+
+describe('ajvHelpers', () => {
+  before(async () => {
+    const mod = await esmock('../lib/ajvHelpers.js', {
+      'ajv-formats': {
+        default: (ajv, formats) => {
+          addedLibFormats = formats;
+        },
+      },
+    });
+
+    ({ ajvFormats } = mod);
+  });
+
+  beforeEach(() => {
+    addedLibFormats = null;
+    addedCustomFormats = {};
+  });
+
+  const createMockAjv = () => ({
+    addFormat: (name, format) => {
+      addedCustomFormats[name] = format;
+    },
+  });
+
+  describe('with no extra formats', () => {
+    it('should add default library formats', () => {
+      const ajv = createMockAjv();
+      const configurer = ajvFormats();
+
+      configurer(ajv);
+      expect(addedLibFormats).to.deep.equal(['date', 'time', 'date-time', 'byte', 'uuid', 'uri', 'email', 'ipv4', 'ipv6']);
+    });
+
+    it('should add built-in semver and ip custom formats', () => {
+      const ajv = createMockAjv();
+      const configurer = ajvFormats();
+
+      configurer(ajv);
+      expect(addedCustomFormats).to.have.property('semver');
+      expect(addedCustomFormats.semver.type).to.equal('string');
+      expect(addedCustomFormats).to.have.property('ip');
+      expect(addedCustomFormats.ip.type).to.equal('string');
+    });
+
+    it('should return the ajv instance', () => {
+      const ajv = createMockAjv();
+      const configurer = ajvFormats();
+      const result = configurer(ajv);
+
+      expect(result).to.equal(ajv);
+    });
+  });
+
+  describe('with null extra formats', () => {
+    it('should treat null as no extra formats', () => {
+      const ajv = createMockAjv();
+      const configurer = ajvFormats(null);
+
+      configurer(ajv);
+      expect(addedLibFormats).to.deep.equal(['date', 'time', 'date-time', 'byte', 'uuid', 'uri', 'email', 'ipv4', 'ipv6']);
+    });
+  });
+
+  describe('with extra library formats (string-only)', () => {
+    it('should append format names to the library formats list', () => {
+      const ajv = createMockAjv();
+      const configurer = ajvFormats({ hostname: {} });
+
+      configurer(ajv);
+      expect(addedLibFormats).to.include('hostname');
+      expect(addedLibFormats).to.have.lengthOf(10);
+    });
+  });
+
+  describe('with extra custom formats (with type)', () => {
+    it('should add custom format via ajv.addFormat', () => {
+      const customFormat = { type: 'string', validate: /^[A-Z]+$/u };
+      const ajv = createMockAjv();
+      const configurer = ajvFormats({ uppercase: customFormat });
+
+      configurer(ajv);
+      expect(addedCustomFormats).to.have.property('uppercase');
+      expect(addedCustomFormats.uppercase).to.equal(customFormat);
+      expect(addedLibFormats).to.not.include('uppercase');
+    });
+  });
+
+  describe('semver validation', () => {
+    it('should accept valid semver strings', () => {
+      const ajv = createMockAjv();
+
+      ajvFormats()(ajv);
+      const { validate } = addedCustomFormats.semver;
+
+      expect(validate.test('1.0.0')).to.equal(true);
+      expect(validate.test('0.1.0')).to.equal(true);
+      expect(validate.test('1.2.3-alpha.1')).to.equal(true);
+      expect(validate.test('1.2.3+build.123')).to.equal(true);
+      expect(validate.test('1.2.3-beta+build')).to.equal(true);
+    });
+
+    it('should reject invalid semver strings', () => {
+      const ajv = createMockAjv();
+
+      ajvFormats()(ajv);
+      const { validate } = addedCustomFormats.semver;
+
+      expect(validate.test('1.0')).to.equal(false);
+      expect(validate.test('abc')).to.equal(false);
+      expect(validate.test('1.0.0.0')).to.equal(false);
+    });
+  });
+
+  describe('ip validation', () => {
+    it('should accept valid IPv4 addresses', () => {
+      const ajv = createMockAjv();
+
+      ajvFormats()(ajv);
+      const { validate } = addedCustomFormats.ip;
+
+      expect(validate.test('192.168.1.1')).to.equal(true);
+      expect(validate.test('10.0.0.1')).to.equal(true);
+      expect(validate.test('255.255.255.255')).to.equal(true);
+    });
+
+    it('should accept valid IPv6 addresses', () => {
+      const ajv = createMockAjv();
+
+      ajvFormats()(ajv);
+      const { validate } = addedCustomFormats.ip;
+
+      expect(validate.test('::1')).to.equal(true);
+      expect(validate.test('2001:0db8:85a3:0000:0000:8a2e:0370:7334')).to.equal(true);
+    });
+  });
+
+  describe('DEFAULT_FORMATS isolation', () => {
+    it('should not mutate DEFAULT_FORMATS between calls', () => {
+      const ajv1 = createMockAjv();
+      const ajv2 = createMockAjv();
+
+      ajvFormats({ extra1: {} })(ajv1);
+      const firstCallLength = addedLibFormats.length;
+
+      ajvFormats()(ajv2);
+      const secondCallLength = addedLibFormats.length;
+
+      expect(secondCallLength).to.equal(9);
+      expect(firstCallLength).to.equal(10);
+    });
+  });
+});