feature/IO-3255-simplified-parts-management -Cleanup / Docblocks

server/integrations/partsManagement/endpoints/partsManagementProvisioning.js

@@ -10,6 +10,11 @@ const {
   CREATE_USER
 } = require("../partsManagement.queries");
 
+/**
+ * Checks if the required fields are present in the payload.
+ * @param payload
+ * @param fields
+ */
 const requireFields = (payload, fields) => {
   for (const field of fields) {
     if (!payload[field]) {
@@ -18,6 +23,11 @@ const requireFields = (payload, fields) => {
   }
 };
 
+/**
+ * Ensures that the provided email is not already registered in Firebase.
+ * @param email
+ * @returns {Promise<void>}
+ */
 const ensureEmailNotRegistered = async (email) => {
   try {
     await admin.auth().getUserByEmail(email);
@@ -29,20 +39,41 @@ const ensureEmailNotRegistered = async (email) => {
   }
 };
 
+/**
+ * Creates a new Firebase user with the given email and optional password.
+ * @param email
+ * @param password
+ * @returns {Promise<UserRecord>}
+ */
 const createFirebaseUser = async (email, password = null) => {
   const userData = { email };
   if (password) userData.password = password;
   return admin.auth().createUser(userData);
 };
 
+/**
+ * Deletes a Firebase user by UID.
+ * @param uid
+ * @returns {Promise<void>}
+ */
 const deleteFirebaseUser = async (uid) => {
   return admin.auth().deleteUser(uid);
 };
 
+/**
+ * Generates a password reset link for the given email.
+ * @param email
+ * @returns {Promise<string>}
+ */
 const generateResetLink = async (email) => {
   return admin.auth().generatePasswordResetLink(email);
 };
 
+/**
+ * Ensures that the provided external shop ID is unique.
+ * @param externalId
+ * @returns {Promise<void>}
+ */
 const ensureExternalIdUnique = async (externalId) => {
   const resp = await client.request(CHECK_EXTERNAL_SHOP_ID, { key: externalId });
   if (resp.bodyshops.length) {
@@ -50,19 +81,41 @@ const ensureExternalIdUnique = async (externalId) => {
   }
 };
 
+/**
+ * Inserts a new bodyshop into the database.
+ * @param input
+ * @returns {Promise<*>}
+ */
 const insertBodyshop = async (input) => {
   const resp = await client.request(CREATE_SHOP, { bs: input });
   return resp.insert_bodyshops_one.id;
 };
 
+/**
+ * Deletes all vendors associated with a shop.
+ * @param shopId
+ * @returns {Promise<void>}
+ */
 const deleteVendorsByShop = async (shopId) => {
   await client.request(DELETE_VENDORS_BY_SHOP, { shopId });
 };
 
+/**
+ * Deletes a bodyshop from the database.
+ * @param shopId
+ * @returns {Promise<void>}
+ */
 const deleteBodyshop = async (shopId) => {
   await client.request(DELETE_SHOP, { id: shopId });
 };
 
+/**
+ * Inserts a new user association into the database.
+ * @param uid
+ * @param email
+ * @param shopId
+ * @returns {Promise<*>}
+ */
 const insertUserAssociation = async (uid, email, shopId) => {
   const vars = {
     u: {
@@ -78,6 +131,12 @@ const insertUserAssociation = async (uid, email, shopId) => {
   return resp.insert_users_one;
 };
 
+/**
+ * Handles provisioning a new shop for parts management.
+ * @param req
+ * @param res
+ * @returns {Promise<*>}
+ */
 const partsManagementProvisioning = async (req, res) => {
   const { logger } = req;
   const p = { ...req.body, userEmail: req.body.userEmail?.toLowerCase() };

server/integrations/partsManagement/endpoints/vehicleDamageEstimateAddRq.js

@@ -149,12 +149,6 @@ const extractJobData = (rq) => {
   };
 };
 
-/**
- * Extracts owner data from the XML request.
- * @param {object} rq - The VehicleDamageEstimateAddRq object.
- * @param {string} shopId - The bodyshop UUID.
- * @returns {object} Owner data for insertion and inline use.
- */
 /**
  * Extracts owner data from the XML request.
  * Falls back to Claimant if Owner is missing.

server/integrations/partsManagement/endpoints/vehicleDamageEstimateChgRq.js

@@ -11,6 +11,13 @@ const {
   DELETE_JOBLINES_BY_IDS
 } = require("../partsManagement.queries");
 
+/**
+ * Finds a job by shop ID and claim number.
+ * @param shopId
+ * @param claimNum
+ * @param logger
+ * @returns {Promise<*|null>}
+ */
 const findJob = async (shopId, claimNum, logger) => {
   try {
     const { jobs } = await client.request(GET_JOB_BY_CLAIM, { shopid: shopId, clm_no: claimNum });
@@ -21,6 +28,11 @@ const findJob = async (shopId, claimNum, logger) => {
   }
 };
 
+/**
+ * Extracts updated job data from the request payload.
+ * @param rq
+ * @returns {{comment: (number|((comment: Comment, helper: postcss.Helpers) => (Promise<void> | void))|string|null), clm_no: null, status: (*|null), policy_no: (*|null)}}
+ */
 const extractUpdatedJobData = (rq) => {
   const doc = rq.DocumentInfo || {};
   const claim = rq.ClaimInfo || {};
@@ -33,6 +45,12 @@ const extractUpdatedJobData = (rq) => {
   };
 };
 
+/**
+ * Extracts updated job lines from the request payload.
+ * @param addsChgs
+ * @param jobId
+ * @returns {{jobid: *, line_no: number, unq_seq: number, status, line_desc, part_type, part_qty: number, oem_partno, db_price: number, act_price: number, mod_lbr_ty, mod_lb_hrs: number, lbr_op, lbr_amt: number, notes, manual_line: boolean}[]}
+ */
 const extractUpdatedJobLines = (addsChgs = {}, jobId) => {
   const lines = Array.isArray(addsChgs.DamageLineInfo) ? addsChgs.DamageLineInfo : [addsChgs.DamageLineInfo || []];
 
@@ -56,12 +74,23 @@ const extractUpdatedJobLines = (addsChgs = {}, jobId) => {
   }));
 };
 
+/**
+ * Extracts deletion IDs from the deletions object.
+ * @param deletions
+ * @returns {number[]}
+ */
 const extractDeletions = (deletions = {}) => {
   const lines = Array.isArray(deletions.DamageLineInfo) ? deletions.DamageLineInfo : [deletions.DamageLineInfo || []];
 
   return lines.map((line) => parseInt(line.UniqueSequenceNum, 10)).filter((id) => !isNaN(id));
 };
 
+/**
+ * Handles VehicleDamageEstimateChgRq requests.
+ * @param req
+ * @param res
+ * @returns {Promise<*>}
+ */
 const partsManagementVehicleDamageEstimateChgRq = async (req, res) => {
   const { logger } = req;