@itentialopensource/adapter-selector_ai 0.1.1

package/utils/methodDocumentor.js

@@ -0,0 +1,273 @@
+/* eslint global-require:warn */
+/* eslint import/no-dynamic-require:warn */
+/* eslint no-param-reassign:warn */
+
+const fs = require('fs-extra');
+const acorn = require('acorn');
+
+// Getting the base directory:
+let adaptdir = __dirname;
+if (adaptdir.endsWith('/utils')) {
+  adaptdir = adaptdir.substring(0, adaptdir.length - 6);
+}
+
+function createObjectForFunction(
+  funcName,
+  funcArgs,
+  entityPath,
+  description,
+  workflow
+) {
+  const funcObject = {};
+  // if the entity path is not set, then the object is not created.
+  if (entityPath !== undefined) {
+    funcObject.method_signature = `${funcName}(${funcArgs.join(', ')})`;
+    funcObject.path = entityPath;
+    if (description === undefined) {
+      funcObject.description = '';
+      funcObject.workflow = 'No';
+    } else {
+      funcObject.description = description;
+      funcObject.workflow = workflow;
+    }
+  }
+  return funcObject;
+}
+
+function getPathFromEntity(entity, funcName) {
+  let epath;
+  if (entity === undefined || entity === '.generic') {
+    epath = undefined;
+  } else {
+    // Access the action.js file for the certain entity to get the path
+    const entityPath = `${adaptdir}/entities/${entity}/action.json`;
+    const actionJSON = require(entityPath);
+    actionJSON.actions.forEach((action) => {
+      if (action.name === funcName) {
+        if (typeof action.entitypath === 'object') {
+          epath = '';
+          const keys = Object.keys(action.entitypath);
+          for (let k = 0; k < keys.length; k += 1) {
+            epath += `${keys[k]}:${action.entitypath[keys[k]]} <br /> `;
+          }
+          epath = epath.substring(0, epath.length - 8);
+        } else {
+          epath = action.entitypath;
+        }
+      }
+    });
+  }
+  return epath;
+}
+
+function recurseCallExpressions(statement, callList) {
+  // Recursively finds all CallExpressions in the syntax tree
+  if (statement.type === 'CallExpression') callList.push(statement);
+  const keys = Object.keys(statement);
+  for (let k = 0; k < keys.length; k += 1) {
+    if (typeof statement[keys[k]] === 'object' && statement[keys[k]] !== null) {
+      recurseCallExpressions(statement[keys[k]], callList);
+    }
+  }
+}
+
+function readFileUsingLib(filename, descriptionObj, workflowObj, functionList) {
+  // read the file
+  const aFile = fs.readFileSync(filename, 'utf8');
+  // parsing the file to get the function and class declarations.
+  const aFileFuncArgs = acorn.parse(aFile, { ecmaVersion: 2020 });
+
+  let callName = 'identifyRequest';
+  // Looping through all the declarations parsed:
+  aFileFuncArgs.body.forEach((e) => {
+    // Getting only the class declaration as it has our required functions.
+    if (e.type === 'ClassDeclaration') {
+      const methodDefinition = e.body;
+      methodDefinition.body.forEach((method) => {
+        // Getting method name and its params in the class.
+        const funcName = method.key.name;
+        const funcArgs = [];
+        method.value.params.forEach((param) => {
+          if (param.type === 'Identifier') {
+            funcArgs.push(param.name);
+          } else if (param.type === 'RestElement') {
+            funcArgs.push(`...${param.argument.name}`);
+          } else {
+            const args = `${param.left.name} = ${param.right.raw}`;
+            funcArgs.push(args);
+          }
+        });
+
+        // Getting the entity for the method:
+        const callList = [];
+        method.value.body.body.forEach((statement) => {
+          recurseCallExpressions(statement, callList);
+        });
+        const requests = [];
+        for (let i = 0; i < callList.length; i += 1) {
+          if (callList[i].callee.property && callList[i].callee.property.name === callName) {
+            requests.push(callList[i]);
+          }
+        }
+        if (requests.length > 0) {
+          const expr = requests[0];
+          if (expr.arguments.length < 2) {
+            throw new Error(`Bad inputs in method ${funcName}`);
+          }
+          const entity = expr.arguments[0].value;
+          const actionName = expr.arguments[1].value;
+          if (expr !== undefined && (expr.arguments[0].type !== 'Literal' || expr.arguments[1].type !== 'Literal')) {
+            const param1 = method.value.params[0];
+            const param2 = method.value.params[1];
+            if (param1.type !== 'Identifier' || param2.type !== 'Identifier'
+                || expr.arguments[0].type !== 'Identifier' || expr.arguments[1].type !== 'Identifier'
+                || param1.name !== expr.arguments[0].name || param2.name !== expr.arguments[1].name) {
+              throw new Error(`identifyRequest proxy method ${funcName} unknown format`);
+            } else if (callName !== 'identifyRequest') {
+              throw new Error(`MethodDocumentor not yet programmed to handle multiple helper methods: 1) ${callName}, 2) ${funcName}`);
+            }
+            callName = funcName;
+          }
+          const entityPath = getPathFromEntity(entity, actionName);
+
+          // Creating and storing the object for the method.
+          if (entityPath !== undefined) {
+            functionList.push(
+              createObjectForFunction(
+                funcName,
+                funcArgs,
+                entityPath,
+                descriptionObj[funcName],
+                workflowObj[funcName]
+              )
+            );
+          }
+        }
+      });
+    }
+  });
+}
+
+function readJSONFile(filename, descriptionObj, workflowObj) {
+  // Accessing the JSON file.
+  const phJSON = require(filename);
+  // Getting the methods array.
+  const methodArray = phJSON.methods;
+  methodArray.forEach((methodName) => {
+    // Getting the method description and workflow:
+    const funcName = methodName.name;
+    descriptionObj[funcName] = methodName.summary ? methodName.summary : methodName.description;
+    workflowObj[funcName] = methodName.task ? 'Yes' : 'No';
+  });
+}
+
+function readMDFile(filename, functionList) {
+  // Reading in the .md file and creating an array with each line as an element.
+  const mdFile = fs.readFileSync(filename, 'utf-8');
+  const fileSplit = mdFile.split('\n');
+  // Storing the data that should added later to the updated data.
+  const linesToAddLater = [];
+  let index = fileSplit.length - 1;
+
+  // Removing all the blank lines at the end of the file.
+  if (fileSplit[index] === '') {
+    while (fileSplit[index] === '') {
+      linesToAddLater.push(fileSplit.pop());
+      index -= 1;
+    }
+  }
+
+  // Checking if the last 2 lines are <br> and </table>. If not, the file is corrupted and the
+  // data at the end of the file should be fixed.
+  if (fileSplit[index] === '<br>' || fileSplit[index - 1] === '</table>') {
+    // Storing <br> and </table> to add later.
+    linesToAddLater.push(fileSplit.pop());
+    linesToAddLater.push(fileSplit.pop());
+    index -= 2;
+  } else {
+    console.log('The file has bad content at the end.');
+    return;
+  }
+  // if (fileSplit[index] !== '<br>' && fileSplit[index - 1] !== '</table>') {
+  //   console.log('The file has bad content at the end.');
+  //   return;
+  // } else {
+  //   // Storing <br> and </table> to add later.
+  //   linesToAddLater.push(fileSplit.pop());
+  //   linesToAddLater.push(fileSplit.pop());
+  //   index -= 2;
+  // }
+
+  // Removing all the lines until the header tags are reached.
+  while (!fileSplit[index].includes('<th')) {
+    fileSplit.pop();
+    index -= 1;
+  }
+  // Adding </tr> for the header row, because it got removed in the above loop.
+  fileSplit.push('  </tr>');
+
+  // Creating the tags for each method to be appended to the file.
+  const tdBeginTag = '    <td style="padding:15px">';
+  const tdEndTag = '</td>';
+
+  functionList.forEach((func) => {
+    const signCommand = `${tdBeginTag}${func.method_signature}${tdEndTag}`;
+    const descCommand = `${tdBeginTag}${func.description}${tdEndTag}`;
+    const pathCommand = `${tdBeginTag}${func.path}${tdEndTag}`;
+    const workflowCommand = `${tdBeginTag}${func.workflow}${tdEndTag}`;
+    fileSplit.push('  <tr>');
+    fileSplit.push(signCommand);
+    fileSplit.push(descCommand);
+    fileSplit.push(pathCommand);
+    fileSplit.push(workflowCommand);
+    fileSplit.push('  </tr>');
+  });
+
+  // Adding </table> and <br> at the end of the file to complete the table and the file.
+  while (linesToAddLater.length > 0) {
+    fileSplit.push(linesToAddLater.pop());
+  }
+
+  // Writing all the content back into the file.
+  fs.writeFileSync(filename, fileSplit.join('\n'), {
+    encoding: 'utf-8',
+    flag: 'w'
+  });
+}
+
+function getFileInfo() {
+  // If files don't exist:
+  if (!fs.existsSync(`${adaptdir}/adapter.js`)) {
+    console.log('Missing - utils/adapter.js');
+    return;
+  }
+  if (!fs.existsSync(`${adaptdir}/pronghorn.json`)) {
+    console.log('Missing - pronghorn.json');
+    return;
+  }
+  if (!fs.existsSync(`${adaptdir}/CALLS.md`)) {
+    console.log('Missing - CALLS.md');
+    return;
+  }
+
+  const descriptionObj = {};
+  const workflowObj = {};
+
+  // Get the method descriptions and the workflow values from pronghorn.json file.
+  readJSONFile(`${adaptdir}/pronghorn.json`, descriptionObj, workflowObj);
+
+  // Get the method signature, entity path and create an object that contains all the info regarding
+  // the method and push it to the functionList array.
+  const functionList = [];
+  readFileUsingLib(
+    `${adaptdir}/adapter.js`,
+    descriptionObj,
+    workflowObj,
+    functionList
+  );
+
+  // createMarkDown(functionList);
+  readMDFile(`${adaptdir}/CALLS.md`, functionList);
+}
+
+getFileInfo();

package/utils/modify.js

@@ -0,0 +1,153 @@
+const { execSync } = require('child_process');
+const fs = require('fs-extra');
+const rls = require('readline-sync');
+const { existsSync } = require('fs-extra');
+
+/**
+ * @summary Creates a backup zip file of current adapter
+ *
+ * @function backup
+ */
+function backup() {
+  // zip all files except node_modules and package-lock
+  const backupCmd = 'zip -r previousVersion.zip .';
+  execSync(backupCmd, { encoding: 'utf-8', maxBuffer: 1024 * 1024 * 2 });
+}
+
+/**
+ * @summary Archives previous modifications and removes the modification package
+ *
+ * @function archiveMod
+ * @param {String} modType - update(UPD) or migrate(MIG)
+ */
+function archiveMod(modType) {
+  if (!existsSync('./adapter_modifications/archive')) {
+    execSync('mkdir ./adapter_modifications/archive');
+  }
+  const zipFile = modType === 'UPD' ? 'updatePackage.zip' : 'migrationPackage.zip';
+  const now = new Date();
+  const archiveName = `${modType}-${now.toISOString()}`;
+  execSync(`mkdir adapter_modifications/archive/${archiveName}`);
+  const archiveCmd = 'mv adapter_modifications/archive .'
+    + ` && mv adapter_modifications/* archive/${archiveName}`
+    + ' && mv archive adapter_modifications'
+    + ` && rm ${zipFile}`;
+  execSync(archiveCmd, { encoding: 'utf-8' });
+}
+
+/**
+ * @summary Reverts modifications using backup zip file
+ *
+ * @function revertMod
+ */
+function revertMod() {
+  const files = fs.readdirSync('./');
+  // remove all files except previousVersion
+  files.forEach((file) => {
+    if (file !== 'previousVersion.zip') {
+      fs.removeSync(file);
+    }
+  });
+  // unzip previousVersion, reinstall dependencies and delete zipfile
+  execSync('unzip -o previousVersion.zip && rm -rf node_modules && rm package-lock.json && npm install', { maxBuffer: 1024 * 1024 * 2 });
+  execSync('rm previousVersion.zip');
+  console.log('Changes have been reverted');
+}
+
+/**
+ * @summary Handle migration logic
+ */
+function handleMigration() {
+  if (!existsSync('migrationPackage.zip')) {
+    throw new Error('Migration Package not found. Download and place migrationPackage in the adapter root directory');
+  }
+
+  backup();
+  console.log('Migrating adapter and running tests...');
+  const migrateCmd = 'unzip -o migrationPackage.zip'
+    + ' && cd adapter_modifications'
+    + ' && node migrate';
+  const migrateOutput = execSync(migrateCmd, { encoding: 'utf-8' });
+  console.log(migrateOutput);
+
+  if (migrateOutput.includes('Lint exited with code 1') || migrateOutput.includes('Tests exited with code 1')) {
+    if (rls.keyInYN('Adapter failed tests or lint after migrating. Would you like to revert the changes?')) {
+      console.log('Reverting changes...');
+      revertMod();
+      throw new Error('Adapter failed tests or lint after migrating. Changes reverted');
+    }
+    console.log('Adapter Migration will continue. If you want to revert the changes, run the command npm run adapter:revert');
+  }
+
+  console.log('Installing new dependencies..');
+  const updatePackageCmd = 'rm -rf node_modules && rm package-lock.json && npm install';
+  const updatePackageOutput = execSync(updatePackageCmd, { encoding: 'utf-8' });
+  console.log(updatePackageOutput);
+  console.log('New dependencies installed');
+  archiveMod('MIG');
+}
+
+/**
+ * @summary Handle update logic
+ */
+function handleUpdate() {
+  if (!existsSync('updatePackage.zip')) {
+    throw new Error('Update Package not found. Download and place updateAdapter.zip in the adapter root directory');
+  }
+
+  backup();
+  const updateCmd = 'unzip -o updatePackage.zip'
+    + ' && cd adapter_modifications'
+    + ' && node update.js updateFiles';
+  execSync(updateCmd, { encoding: 'utf-8' });
+  const updateOutput = execSync(updateCmd, { encoding: 'utf-8' });
+
+  if (updateOutput.includes('Lint exited with code 1') || updateOutput.includes('Tests exited with code 1')) {
+    if (rls.keyInYN('Adapter failed tests or lint after updating. Would you like to revert the changes?')) {
+      console.log('Reverting changes...');
+      revertMod();
+      throw new Error('Adapter failed tests or lint after updating. Changes reverted');
+    }
+    console.log('Adapter Update will continue. If you want to revert the changes, run the command npm run adapter:revert');
+  }
+
+  console.log(updateOutput);
+  console.log('Adapter Successfully Updated. Restart adapter in IAP to apply the changes');
+  archiveMod('UPD');
+}
+
+/**
+ * @summary Handle revert logic
+ */
+function handleRevert() {
+  if (!existsSync('previousVersion.zip')) {
+    throw new Error('Previous adapter version not found. There are no changes to revert');
+  }
+  revertMod();
+}
+
+/**
+ * @summary Entrypoint for the script
+ */
+function main() {
+  const flags = process.argv[2];
+
+  switch (flags) {
+    case '-m':
+      return handleMigration();
+    case '-u':
+      return handleUpdate();
+    case '-r':
+      return handleRevert();
+    default:
+      throw new Error('Invalid flag. Use -m for migrate, -u for update, or -r for revert.');
+  }
+}
+
+try {
+  main();
+  process.exit(0);
+} catch (error) {
+  console.error(error.message || error);
+  process.exit(1);
+}

package/utils/mongoDbConnection.js

@@ -0,0 +1,79 @@
+// Set globals
+/* global log */
+
+const { MongoClient } = require('mongodb');
+const MongoUtils = require('./mongoUtils');
+
+class MongoDBConnection {
+  constructor(properties) {
+    this.properties = properties;
+    this.initialize(properties);
+  }
+
+  initialize(properties) {
+    const {
+      url, database, maxPoolSize, appname
+    } = properties;
+
+    // Handle URL first - if provided, it takes precedence
+    if (url) {
+      const urlObj = new URL(url);
+      const urlDbName = urlObj.pathname.slice(1);
+      this.dbName = database || urlDbName;
+
+      // Update URL if database name is different
+      if (this.dbName !== urlDbName) {
+        urlObj.pathname = `${this.dbName}`;
+      }
+
+      this.url = urlObj.toString();
+    } else {
+      const connectionObj = MongoUtils.generateConnectionObj(properties);
+      this.url = MongoUtils.generateConnectionString(connectionObj);
+      this.dbName = database;
+    }
+
+    // Set options using generateTlsSettings
+    this.options = MongoUtils.generateTlsSettings(properties);
+
+    // Add maxPoolSize if configured
+    if (maxPoolSize > 0 && maxPoolSize <= 65535) {
+      this.options.maxPoolSize = maxPoolSize;
+    }
+
+    // Add application name if provided
+    if (appname) {
+      this.options.appname = appname;
+    }
+  }
+
+  async closeConnection() {
+    if (this.connection && this.connection.close) {
+      try {
+        await this.connection.close();
+      } catch (err) {
+        log.error(`Failed to close MongoDB connection - ${err.message}`);
+      }
+    }
+  }
+
+  async connect() {
+    const client = new MongoClient(this.url, this.options);
+
+    client.on('serverHeartbeatSucceeded', (msg) => log.info(`Connection established and heartbeat succeeded - ${JSON.stringify(msg)}`));
+    client.on('connectionClosed', (msg) => log.info(`Connection closed - ${JSON.stringify(msg)}`));
+    client.on('error', (msg) => log.error(`Connection error - ${JSON.stringify(msg)}`));
+    client.on('commandFailed', (msg) => log.error(`Command failed - ${JSON.stringify(msg)}`));
+    client.on('serverHeartbeatFailed', (msg) => log.error(`Connection timeout - ${JSON.stringify(msg)}`));
+
+    await client.connect().catch((error) => {
+      throw new Error(MongoUtils.resolveMongoError(error));
+    });
+
+    this.db = client.db(this.dbName);
+    this.connection = client;
+    return this;
+  }
+}
+
+module.exports = MongoDBConnection;

package/utils/mongoUtils.js

@@ -0,0 +1,162 @@
+const fs = require('fs-extra');
+
+class MongoUtils {
+  /**
+     * Parses a MongoDB connection string and extracts its components.
+     * @param {string} connectionString - The MongoDB connection string.
+     * @returns {object} Parsed connection details.
+     */
+  static parseConnectionString(connectionString) {
+    try {
+      const url = new URL(connectionString);
+      return {
+        protocol: url.protocol.replace(':', ''),
+        host: url.hostname,
+        port: url.port || '27017',
+        database: url.pathname.replace('/', ''),
+        username: url.username || null,
+        password: url.password || null,
+        options: Object.fromEntries(url.searchParams.entries())
+      };
+    } catch (error) {
+      throw new Error(`Invalid MongoDB URI: ${error.message}`);
+    }
+  }
+
+  /**
+     * Generates a MongoDB connection string from given properties.
+     * @param {object} config - MongoDB connection properties.
+     * @returns {string} A valid MongoDB connection string.
+     */
+  static generateConnectionString(config) {
+    // Determine protocol based on addSrv flag
+    const protocol = config.addSrv ? 'mongodb+srv' : 'mongodb';
+
+    // Build authentication part if credentials are provided and dbAuth is true
+    const authPart = (config.dbAuth && config.username && config.password)
+      ? `${encodeURIComponent(config.username)}:${encodeURIComponent(config.password)}@`
+      : '';
+
+    // Build host and port part
+    const hostPart = config.host;
+    const portPart = !config.addSrv && config.port ? `:${config.port}` : '';
+
+    // Build options part
+    let optionsPart = '';
+    if (config.options && Object.keys(config.options).length) {
+      optionsPart = `?${new URLSearchParams(config.options).toString()}`;
+    }
+
+    // Build database part
+    const dbPart = config.database ? `/${config.database}` : '';
+
+    return `${protocol}://${authPart}${hostPart}${portPart}${dbPart}${optionsPart}`;
+  }
+
+  /**
+     * Generates TLS settings for MongoDB connection
+     * @param {object} properties - Connection properties containing TLS configuration
+     * @returns {object} TLS settings object
+     */
+  static generateTlsSettings(properties) {
+    // Handle TLS properties
+    if (properties.tls) {
+      return {
+        tls: properties.tls.enabled,
+        tlsAllowInvalidCertificates: properties.tls.tlsAllowInvalidCertificates || false,
+        tlsCAFile: properties.tls.tlsCAFile
+      };
+    }
+
+    // Handle db_ssl properties (standard adapter format)
+    if (!properties.db_ssl) {
+      return { tls: false };
+    }
+
+    const tlsProperties = {
+      tls: properties.db_ssl.enabled || false,
+      tlsAllowInvalidCertificates: properties.db_ssl.accept_invalid_cert || false
+    };
+
+    const hasValidCaFile = properties.db_ssl.enabled && properties.db_ssl.ca_file && fs.existsSync(properties.db_ssl.ca_file);
+
+    if (hasValidCaFile) {
+      tlsProperties.tlsCAFile = properties.db_ssl.ca_file;
+    }
+
+    return tlsProperties;
+  }
+
+  /**
+     * Generates a connection object from properties
+     * @param {object} properties - Connection properties
+     * @returns {object} Connection object with host, port, database, and credentials
+     */
+  static generateConnectionObj(properties) {
+    try {
+      const connectionObj = {
+        host: properties.host,
+        port: properties.port,
+        database: properties.database,
+        addSrv: properties.addSrv || false,
+        dbAuth: properties.dbAuth || false,
+        options: properties.replSet && !properties.addSrv ? { replicaSet: properties.replSet } : undefined
+      };
+
+      // Only include credentials if dbAuth is true
+      if (properties.dbAuth) {
+        // Validate that both username and password are provided when dbAuth is true
+        if (!properties.username || !properties.password) {
+          throw new Error('Both username and password are required when dbAuth is enabled');
+        }
+        connectionObj.username = properties.username;
+        connectionObj.password = properties.password;
+      }
+
+      return connectionObj;
+    } catch (error) {
+      throw new Error(`Invalid MongoDB configuration: ${error.message}`);
+    }
+  }
+
+  /**
+     * Resolves MongoDB error messages to user-friendly format
+     * @param {object} mongoError - The MongoDB error object
+     * @returns {string} User-friendly error message
+     */
+  static resolveMongoError(mongoError) {
+    if (mongoError && mongoError.code === 13) {
+      return 'User unauthorized to perform the requested action: ';
+    }
+    if (mongoError && mongoError.code === 18) {
+      return `User Authentication failed. Username/Password combination is incorrect ${mongoError}`;
+    }
+    return mongoError;
+  }
+
+  /**
+     * Helper function to validate and process MongoDB connection properties
+     * @param {Object} mongoProps - MongoDB connection properties to validate
+     * @returns {Object|undefined} - Validated and processed MongoDB properties or undefined if invalid
+    */
+  static getAndValidateMongoProps(mongoProps) {
+    if (!mongoProps) return undefined;
+
+    // Handle URL-based connection
+    const url = mongoProps.url && mongoProps.url.trim();
+    if (!url) {
+      // Handle host-based connection
+      const hasHost = mongoProps.hostname || mongoProps.host;
+      const hasDatabase = mongoProps.database;
+      return (hasHost && hasDatabase) ? mongoProps : undefined;
+    }
+
+    // Process URL-based connection
+    const props = { ...mongoProps };
+    const { database } = props;
+    const urlHasDatabase = database && url.includes(`/${database}`);
+    return urlHasDatabase ? props : { ...props, url: `${url}/${database}` };
+  }
+}
+
+module.exports = MongoUtils;

package/utils/pre-commit.sh

@@ -0,0 +1,32 @@
+#!/bin/sh
+# @copyright Itential, LLC 2019
+
+#exit on any failure in the pipeline
+set -e
+
+# --------------------------------------------------
+# pre-commit
+# --------------------------------------------------
+# Contains the standard set of tasks to runbefore
+# committing changes to the repo. If any tasks fail
+# then the commit will be aborted.
+# --------------------------------------------------
+
+printf "%b" "Running pre-commit hooks...\\n"
+
+# verify testing script is stubbed and no credentials
+node utils/testRunner.js -r
+
+# update the adapter information file
+node utils/adapterInfo.js
+node utils/methodDocumentor.js
+git add CALLS.md report/adapterInfo.json
+
+# security audit on the code
+npm audit --registry=https://registry.npmjs.org --audit-level=moderate
+
+# lint the code
+npm run lint
+
+# test the code
+npm run test