@machinemetrics/mm-erp-sdk 0.1.1-beta.1

package/src/utils/standard-process-drivers/error-processor.ts

@@ -0,0 +1,417 @@
+import { ERPObjType } from "../../types/erp-types";
+import { BatchCacheManager } from "../../services/caching-service/batch-cache-manager";
+import {
+  IToRESTApiObject,
+  MM207NonLaborTicketResponse,
+  MM207LaborTicketResponse,
+} from "../../services/mm-api-service";
+import { EntityTransformer } from "../../services/mm-api-service/types/entity-transformer";
+import logger from "../../services/reporting-service/logger";
+
+/**
+ * Handles error processing and record management utilities for MM API operations
+ */
+export class ErrorProcessor {
+  /**
+   * Creates a set of primary keys for all failed records from batch errors
+   * @param entityType The type of entity being processed
+   * @param batchErrors Array of batch errors containing failed entities
+   * @returns Set of primary keys for failed records
+   */
+  static createFailedRecordKeySet(
+    entityType: ERPObjType,
+    batchErrors: Array<{
+      message: string;
+      errorEntities: IToRESTApiObject[];
+    }>
+  ): Set<string> {
+    const failedKeySet = new Set<string>();
+
+    batchErrors.forEach((batchError) => {
+      batchError.errorEntities.forEach((errorEntity) => {
+        try {
+          const primaryKey = EntityTransformer.extractPrimaryKey(
+            entityType,
+            errorEntity
+          );
+          failedKeySet.add(primaryKey);
+        } catch (error) {
+          logger.warn(
+            `Failed to extract primary key from error entity: ${error}`
+          );
+          // Continue processing other records even if one fails
+        }
+      });
+    });
+
+    return failedKeySet;
+  }
+
+  /**
+   * Filters out failed records, returning only successful ones
+   * @param entityType The type of entity being processed
+   * @param allRecords All records (typed objects) that were sent to the API
+   * @param failedKeySet Set of primary keys for records that failed
+   * @returns Array of records that succeeded
+   */
+  static filterSuccessfulRecords(
+    entityType: ERPObjType,
+    allRecords: IToRESTApiObject[],
+    failedKeySet: Set<string>
+  ): IToRESTApiObject[] {
+    const successfulRecords: IToRESTApiObject[] = [];
+
+    allRecords.forEach((record) => {
+      try {
+        const primaryKey = EntityTransformer.extractPrimaryKey(
+          entityType,
+          record
+        );
+        if (!failedKeySet.has(primaryKey)) {
+          successfulRecords.push(record);
+        }
+      } catch (error) {
+        logger.warn(
+          `Failed to extract primary key from record during filtering: ${error}`
+        );
+        // If we can't extract the key, we can't determine if it failed, so skip it
+      }
+    });
+
+    return successfulRecords;
+  }
+
+  /**
+   * Orchestrates the caching of successful records on partial failure
+   * @param entityType The type of entity being processed
+   * @param toProcess All records that were sent to the API (all are now guaranteed to be typed objects)
+   * @param batchErrors Array of batch errors containing failed entities
+   * @param batchCacheManager The cache manager instance
+   */
+  static async cacheSuccessfulRecordsOnPartialFailure(
+    entityType: ERPObjType,
+    toProcess: IToRESTApiObject[],
+    batchErrors: Array<{
+      message: string;
+      errorEntities: IToRESTApiObject[];
+    }>,
+    batchCacheManager: BatchCacheManager
+  ): Promise<void> {
+    // Create a set of failed record keys for efficient lookup
+    const failedKeySet = this.createFailedRecordKeySet(entityType, batchErrors);
+
+    // Filter to get only successful records
+    const successfulRecords = this.filterSuccessfulRecords(
+      entityType,
+      toProcess,
+      failedKeySet
+    );
+
+    logger.info(
+      `Caching ${successfulRecords.length} successful records out of ${toProcess.length} total records`
+    );
+
+    // All records are now guaranteed to be typed objects, so we can cache them directly
+    if (successfulRecords.length > 0) {
+      await batchCacheManager.storeBatch(entityType, successfulRecords);
+    }
+  }
+
+  /**
+   * Extracts error count and batch errors from MM API response for partial failures (HTTP 207)
+   * This supports all entities, including the slightly different format for labor tickets.
+   * In case of labor tickets, the updateErrors and insertErrors arrays are combined into errorEntities.
+   * @param mmApiResponse The full MM API response object
+   * @param entityType The type of entity being processed (determines response structure)
+   * @returns Object containing errorCount and batchErrors
+   * See MM207NonLaborTicketResponse and MM207LaborTicketResponse for response structure details
+   */
+  static extractErrorDetails(
+    mmApiResponse: MM207NonLaborTicketResponse | MM207LaborTicketResponse,
+    entityType: ERPObjType
+  ): {
+    errorCount: number;
+    batchErrors: Array<{
+      message: string;
+      errorEntities: IToRESTApiObject[];
+    }>;
+  } {
+    // Type the data property with the expected structure for HTTP 207 responses
+    const data = mmApiResponse.data as
+      | {
+          errors?: Array<{
+            message: string;
+            batchData?: (IToRESTApiObject | Record<string, string | null>)[];
+          }>;
+          updateErrors?: Array<{
+            message: string;
+            batchData?: (IToRESTApiObject | Record<string, string | null>)[];
+          }>;
+          insertErrors?: Array<{
+            message: string;
+            batchData?: (IToRESTApiObject | Record<string, string | null>)[];
+          }>;
+        }
+      | undefined;
+
+    let allErrors: Array<{
+      message: string;
+      batchData?: (IToRESTApiObject | Record<string, string | null>)[];
+    }> = [];
+
+    if (entityType === ERPObjType.LABOR_TICKETS) {
+      // Labor tickets: combine updateErrors and insertErrors
+      const updateErrors = data?.updateErrors || [];
+      const insertErrors = data?.insertErrors || [];
+
+      // Defensive validation with actionable warnings
+      if (!data?.updateErrors && !data?.insertErrors) {
+        logger.warn(
+          "Labor tickets partial success response missing both updateErrors and insertErrors arrays"
+        );
+      }
+
+      allErrors = [...updateErrors, ...insertErrors];
+    } else {
+      // Regular entities: use errors array
+      const errors = data?.errors || [];
+
+      // Defensive validation
+      if (!data?.errors) {
+        logger.warn(
+          `${entityType} partial success response missing errors array`
+        );
+      }
+
+      allErrors = errors;
+    }
+
+    const batchErrors = allErrors
+      .filter(
+        (error: {
+          message: string;
+          batchData?: (IToRESTApiObject | Record<string, string | null>)[];
+        }) => {
+          return error.batchData && error.batchData.length > 0;
+        }
+      )
+      .map(
+        (error: {
+          message: string;
+          batchData?: (IToRESTApiObject | Record<string, string | null>)[];
+        }) => {
+          // Reconstruct typed objects from plain data
+          const typedErrorEntities = (error.batchData || []).map((entity) => {
+            if (
+              typeof entity === "object" &&
+              entity !== null &&
+              "toRESTApiObject" in entity &&
+              typeof entity.toRESTApiObject === "function"
+            ) {
+              // It's already a typed object, return as-is
+              return entity as IToRESTApiObject;
+            } else {
+              // It's plain data, reconstruct as typed object
+              return EntityTransformer.reconstructFromPlainData(
+                entityType,
+                entity as Record<string, string | null>
+              );
+            }
+          });
+
+          return {
+            message: error.message,
+            errorEntities: typedErrorEntities,
+          };
+        }
+      );
+
+    const errorCount = batchErrors.reduce((total: number, batchError) => {
+      return total + batchError.errorEntities.length;
+    }, 0);
+
+    return {
+      errorCount,
+      batchErrors,
+    };
+  }
+
+  /**
+   * Extracts error details from a 500 HTTP exception when it contains structured error data
+   * @param exception The caught exception from MM API call
+   * @param entityType The type of entity being processed
+   * @returns Object containing errorCount and batchErrors, or null if not a structured 500 error
+   * See MM500NonLaborTicketException and MM500LaborTicketException for exception structure details
+   */
+  static extractErrorDetailsFrom500Exception(
+    exception: unknown,
+    entityType: ERPObjType
+  ): {
+    errorCount: number;
+    batchErrors: Array<{
+      message: string;
+      errorEntities: IToRESTApiObject[];
+    }>;
+  } | null {
+    try {
+      // Cast exception to expected structure for easier access
+      const ex = exception as Record<string, unknown>;
+      const data = ex?.data as Record<string, unknown>;
+
+      // Add diagnostic logging to understand the 500 error structure
+      logger.info(
+        "writeEntitiesToMM: Analyzing 500 exception structure for diagnostic purposes",
+        {
+          status: ex?.status,
+          code: ex?.code,
+          hasResponseData: !!data,
+          responseDataKeys: data ? Object.keys(data) : [],
+          errorMessage: data?.error,
+          hasMessageObject: !!data?.message,
+          messageObjectKeys: data?.message
+            ? Object.keys(data.message as Record<string, unknown>)
+            : [],
+          entityType,
+          exceptionType: typeof exception,
+          exceptionKeys: ex ? Object.keys(ex) : [],
+        }
+      );
+
+      // Check if this is a structured 500 error
+      if (
+        ex?.status !== 500 ||
+        typeof data?.error !== "string" ||
+        !data.error.startsWith("Failed to import")
+      ) {
+        logger.info(
+          "writeEntitiesToMM: Not a structured 500 error - will re-throw exception as-is",
+          {
+            status: ex?.status,
+            errorMessage: data?.error,
+            expectedStatus: 500,
+            expectedMessagePrefix: "Failed to import",
+          }
+        );
+        return null;
+      }
+
+      logger.info(
+        "writeEntitiesToMM: Detected structured 500 error - extracting error details"
+      );
+
+      const messageObject = data?.message as Record<string, unknown>;
+      if (!messageObject) {
+        logger.warn(
+          "writeEntitiesToMM: Structured 500 error missing message object"
+        );
+        return null;
+      }
+
+      let allErrors: unknown[] = [];
+
+      if (entityType === ERPObjType.LABOR_TICKETS) {
+        // Labor tickets: combine updateErrors and insertErrors
+        const updateErrors = Array.isArray(messageObject?.updateErrors)
+          ? messageObject.updateErrors
+          : [];
+        const insertErrors = Array.isArray(messageObject?.insertErrors)
+          ? messageObject.insertErrors
+          : [];
+
+        logger.info("writeEntitiesToMM: Processing labor tickets 500 error", {
+          updateErrorsCount: updateErrors.length,
+          insertErrorsCount: insertErrors.length,
+        });
+
+        if (updateErrors.length === 0 && insertErrors.length === 0) {
+          logger.warn(
+            "writeEntitiesToMM: Labor tickets 500 error missing both updateErrors and insertErrors arrays"
+          );
+        }
+
+        allErrors = [...updateErrors, ...insertErrors];
+      } else {
+        // Regular entities: use errors array
+        const errors = Array.isArray(messageObject?.errors)
+          ? messageObject.errors
+          : [];
+
+        logger.info("writeEntitiesToMM: Processing regular entity 500 error", {
+          errorsCount: errors.length,
+        });
+
+        if (errors.length === 0) {
+          logger.warn(
+            `writeEntitiesToMM: ${entityType} 500 error missing errors array`
+          );
+        }
+
+        allErrors = errors;
+      }
+
+      const batchErrors = allErrors
+        .filter((error) => {
+          const err = error as Record<string, unknown>;
+          return Array.isArray(err?.batchData) && err.batchData.length > 0;
+        })
+        .map((error) => {
+          const err = error as Record<string, unknown>;
+          const batchData = err?.batchData as (
+            | IToRESTApiObject
+            | Record<string, string | null>
+          )[];
+
+          // Reconstruct typed objects from plain data
+          const typedErrorEntities = (batchData || []).map((entity) => {
+            if (
+              typeof entity === "object" &&
+              entity !== null &&
+              "toRESTApiObject" in entity &&
+              typeof entity.toRESTApiObject === "function"
+            ) {
+              // It's already a typed object, return as-is
+              return entity as IToRESTApiObject;
+            } else {
+              // It's plain data, reconstruct as typed object
+              return EntityTransformer.reconstructFromPlainData(
+                entityType,
+                entity as Record<string, string | null>
+              );
+            }
+          });
+
+          return {
+            message:
+              typeof err?.message === "string" ? err.message : "Unknown error",
+            errorEntities: typedErrorEntities,
+          };
+        });
+
+      const errorCount = batchErrors.reduce((total: number, batchError) => {
+        return total + batchError.errorEntities.length;
+      }, 0);
+
+      logger.info("writeEntitiesToMM: Extracted 500 error details", {
+        batchErrorsCount: batchErrors.length,
+        totalErrorCount: errorCount,
+        entityType,
+      });
+
+      return {
+        errorCount,
+        batchErrors,
+      };
+    } catch (error) {
+      // If we can't even parse the structure safely, log what we can and return null
+      logger.error(
+        "writeEntitiesToMM: Failed to parse 500 exception structure safely",
+        {
+          error: error instanceof Error ? error.message : String(error),
+          exceptionType: typeof exception,
+          entityType,
+        }
+      );
+      return null;
+    }
+  }
+}

package/src/utils/standard-process-drivers/index.ts

@@ -0,0 +1,6 @@
+// Public exports for standard-process-drivers
+export { StandardProcessDrivers } from "./standard-process-drivers";
+export type {
+  WriteEntitiesToMMResult,
+  MMBatchValidationError,
+} from "./standard-process-drivers";

package/src/utils/standard-process-drivers/labor-ticket-erp-synchronizer.ts

@@ -0,0 +1,261 @@
+import { ERPType } from "../../types/erp-types";
+import { IERPLaborTicketHandler } from "../../types/erp-connector";
+import { MMApiClient } from "../../services/mm-api-service/mm-api-service";
+import { MMReceiveLaborTicket } from "../../services/mm-api-service/types/receive-types";
+import { convertLaborTicketToLocalTimezone } from "../mm-labor-ticket-helpers";
+import { getCachedTimezoneOffset } from "../local-data-store/jobs-shared-data";
+import logger from "../../services/reporting-service/logger";
+
+/**
+ * Handles synchronization of labor tickets between MachineMetrics and ERP systems
+ */
+export class LaborTicketERPSynchronizer {
+  /**
+   * Synchronizes updated labor tickets from MachineMetrics to an ERP system
+   */
+  static async syncToERP(
+    connectorType: ERPType,
+    connector: IERPLaborTicketHandler
+  ): Promise<void> {
+    try {
+      const mmApiClient = new MMApiClient();
+      const failedLaborTicketRefs: string[] = [];
+
+      await mmApiClient.initializeCheckpoint({
+        system: connectorType,
+        table: "labor_tickets",
+        checkpointType: "export",
+        checkpointValue: {
+          timestamp: new Date().toISOString(),
+        },
+      });
+
+      const fallbackTimestamp = new Date().toISOString();
+      const laborTicketsUpdates = await mmApiClient.fetchLaborTicketUpdates({
+        system: connectorType,
+        checkpointType: "export",
+      });
+
+      if (laborTicketsUpdates.length === 0) {
+        logger.info("syncLaborTicketsToERP:No updated labor tickets found");
+        return;
+      }
+
+      logger.info(
+        `ToERP: Found ${laborTicketsUpdates.length} Labor Ticket Ids and Refs to process`,
+        {
+          laborTickets: laborTicketsUpdates.map(
+            (ticket: MMReceiveLaborTicket) => ({
+              ref: ticket.laborTicketRef,
+              id: ticket.laborTicketId,
+            })
+          ),
+        }
+      );
+
+      // Find the most recent updatedAt timestamp from labor tickets. This will be used to update
+      // the checkpoint to ensure there is no gap of time for the next sync.
+      const mostRecentUpdate = laborTicketsUpdates.reduce(
+        (latest: string | null, ticket: MMReceiveLaborTicket) => {
+          if (!latest || !ticket.updatedAt) return latest;
+          return new Date(ticket.updatedAt) > new Date(latest)
+            ? ticket.updatedAt
+            : latest;
+        },
+        null as string | null
+      );
+
+      await Promise.all(
+        laborTicketsUpdates.map(async (laborTicket: MMReceiveLaborTicket) => {
+          if (!laborTicket.laborTicketRef) {
+            logger.error(
+              "syncLaborTicketsToERP: laborTicketRef is not set for laborTicket pulled from MM:",
+              { laborTicket }
+            );
+            return undefined;
+          }
+
+          try {
+            return await this.processLaborTicket(
+              connector,
+              mmApiClient,
+              laborTicket
+            );
+          } catch (error) {
+            failedLaborTicketRefs.push(laborTicket.laborTicketRef);
+            logger.error(
+              `syncLaborTicketsToERP: Error processing laborTicketRef ${laborTicket.laborTicketRef}:`,
+              { error }
+            );
+            return undefined;
+          }
+        })
+      );
+
+      logger.info(
+        `syncLaborTicketsToERP: ${failedLaborTicketRefs.length} failed labor ticket ids`
+      );
+      if (failedLaborTicketRefs.length > 0) {
+        logger.info(
+          `syncLaborTicketsToERP: Reporting ${failedLaborTicketRefs.length} labor ticket failures:`,
+          {
+            failedLaborTicketRefs,
+          }
+        );
+        const addFailedResult = await mmApiClient.addFailedLaborTicketRefs(
+          connectorType,
+          failedLaborTicketRefs
+        );
+        logger.info("syncLaborTicketsToERP: addFailedResult:", {
+          addFailedResult,
+        });
+      }
+
+      mmApiClient.saveCheckpoint({
+        system: connectorType,
+        table: "labor_tickets",
+        checkpointType: "export",
+        checkpointValue: {
+          timestamp: mostRecentUpdate || fallbackTimestamp,
+        },
+      });
+    } catch (error) {
+      logger.error("syncLaborTicketsToERP: Error:", error);
+    }
+  }
+
+  /**
+   * Retries labor tickets that have failed to be created or updated in the ERP during the sync
+   */
+  static async retryFailed(
+    connectorType: ERPType,
+    connector: IERPLaborTicketHandler
+  ): Promise<void> {
+    try {
+      const mmApiClient = new MMApiClient();
+      const successLaborTicketIds: string[] = [];
+
+      const laborTickets =
+        await mmApiClient.fetchFailedLaborTickets(connectorType);
+      if (laborTickets.length === 0) {
+        logger.info("retryFailedLaborTickets: No failed labor tickets found");
+        return;
+      }
+      logger.info(
+        "retryFailedLaborTickets: Failed Labor Tickets count:" +
+          laborTickets.length
+      );
+
+      await Promise.all(
+        laborTickets.map(async (laborTicket: MMReceiveLaborTicket) => {
+          if (!laborTicket.laborTicketRef) {
+            logger.error(
+              "retryFailedLaborTickets: laborTicketRef is not set for laborTicket pulled from MM:",
+              { laborTicket }
+            );
+            return undefined;
+          }
+
+          try {
+            const laborTicketResult = await this.processLaborTicket(
+              connector,
+              mmApiClient,
+              laborTicket
+            );
+            successLaborTicketIds.push(laborTicket.laborTicketRef);
+            return laborTicketResult;
+          } catch (error) {
+            logger.error(
+              "retryFailedLaborTickets: Error processing laborTicketRef:",
+              { laborTicketRef: laborTicket.laborTicketRef, error }
+            );
+            return undefined;
+          }
+        })
+      );
+
+      if (successLaborTicketIds.length > 0) {
+        logger.info("Deleting failed labor ticket ids:", {
+          successLaborTicketIds,
+        });
+        const deleteFailedResult = await mmApiClient.deleteFailedLaborTicketIds(
+          connectorType,
+          successLaborTicketIds
+        );
+        logger.info("deleteFailedResult:", { deleteFailedResult });
+      }
+    } catch (error) {
+      logger.error("retryFailedLaborTickets: Error:", error);
+    }
+  }
+
+  // ============================================================================
+  // PRIVATE HELPER METHODS
+  // ============================================================================
+
+  private static async writeLaborTicketIdToMM(
+    mmApiClient: MMApiClient,
+    laborTicket: MMReceiveLaborTicket,
+    laborTicketResult: MMReceiveLaborTicket
+  ): Promise<void> {
+    const updateRefAPIResponse = await mmApiClient.updateLaborTicketIdByRef(
+      laborTicket.laborTicketRef,
+      laborTicketResult.laborTicketId
+    );
+    logger.info(
+      `Updated laborTicketId ${laborTicketResult.laborTicketId} for laborTicketRef ${laborTicket.laborTicketRef} in MM:`,
+      { updateRefAPIResponse }
+    );
+  }
+
+  private static async processLaborTicket(
+    connector: IERPLaborTicketHandler,
+    mmApiClient: MMApiClient,
+    laborTicket: MMReceiveLaborTicket
+  ): Promise<MMReceiveLaborTicket> {
+    let laborTicketResult: MMReceiveLaborTicket;
+
+    laborTicketResult = convertLaborTicketToLocalTimezone(
+      laborTicket,
+      getCachedTimezoneOffset()
+    );
+
+    logger.info(
+      `processing laborTicket, id=${laborTicket.laborTicketId}, ref=${laborTicket.laborTicketRef}`
+    );
+    logger.debug({ laborTicket });
+
+    // MLW TODO: Should we always swap out the resource ID for the machine group ID if it is found?
+    // Or use a flag? What about the default resource ID as used by syteline? A Rutherford consultation is in order.
+    /**
+     * Swapping out the resource ID for the group id corresponding to the
+     * resource ID in the ERP would be done like so:
+     * const machineGroupId = await mmApiClient.getResourceERPGroupId(laborTicket.resourceId);
+     *   if(machineGroupId) {
+     *   laborTicket.resourceId = machineGroupId;
+     * }
+     */
+
+    if (!laborTicket.laborTicketId) {
+      const { laborTicket: laborTicketResult, erpUid } =
+        await connector.createLaborTicketInERP(laborTicket);
+      laborTicketResult.laborTicketId = erpUid;
+      await this.writeLaborTicketIdToMM(
+        mmApiClient,
+        laborTicket,
+        laborTicketResult
+      );
+    } else {
+      laborTicketResult = await connector.updateLaborTicketInERP(laborTicket);
+    }
+
+    logger.info("ToERP: laborTicket update result:", {
+      laborTicketResult:
+        laborTicketResult || "Failed to create/update labor ticket",
+      laborTicketRef: laborTicket.laborTicketRef,
+      operation: laborTicket.laborTicketId ? "update" : "create",
+    });
+
+    return laborTicketResult;
+  }
+}