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

package/src/utils/standard-process-drivers/mm-entity-processor.ts

@@ -0,0 +1,265 @@
+import { ERPObjType } from "../../types/erp-types";
+import { BatchCacheManager } from "../../services/caching-service/batch-cache-manager";
+import {
+  IToRESTApiObject,
+  MMSendPerson,
+  MMSendResource,
+  MMSendPart,
+  MMSendPartOperation,
+  MMSendWorkOrder,
+  MMSendWorkOrderOperation,
+  MMSendLaborTicket,
+  MMSendReason,
+  MMApiBaseResponse,
+  MM200NonLaborTicketResponse,
+  MM200LaborTicketResponse,
+  MM207NonLaborTicketResponse,
+  MM207LaborTicketResponse,
+} from "../../services/mm-api-service";
+import { MMApiClient } from "../../services/mm-api-service/mm-api-service";
+import { HTTPError } from "../http-client";
+import {
+  WriteEntitiesToMMResult,
+  MMBatchValidationError,
+} from "./standard-process-drivers";
+import { ErrorProcessor } from "./error-processor";
+
+/**
+ * Handles processing of entities to the MachineMetrics API
+ */
+export class MMEntityProcessor {
+  /**
+   * Writes entities to MM API with deduplication and caching
+   */
+  static async writeEntities(
+    entityType: ERPObjType,
+    mmRecords: IToRESTApiObject[],
+    batchCacheManager: BatchCacheManager | null
+  ): Promise<WriteEntitiesToMMResult> {
+    const { toProcess, result } = await this._prepareAndDedupe(
+      entityType,
+      mmRecords,
+      batchCacheManager
+    );
+
+    if (toProcess.length === 0) {
+      result.message =
+        "All records were deduplicated locally - no records sent to MM API";
+      return result;
+    }
+
+    let mmApiResponse: MMApiBaseResponse;
+    try {
+      mmApiResponse = await this._sendToAPI(entityType, toProcess);
+    } catch (exception) {
+      this._handleException(exception, entityType, result);
+    }
+
+    return await this._handleResponse(
+      mmApiResponse,
+      entityType,
+      toProcess,
+      result,
+      batchCacheManager
+    );
+  }
+
+  // ============================================================================
+  // PRIVATE HELPER METHODS
+  // ============================================================================
+
+  /**
+   * Deduplicates records against cache
+   * Returns the records to process and the result object
+   * If the batchCacheManager is provided, the records are deduplicated against the cache
+   * If the batchCacheManager is not provided, the records are not deduplicated
+   */
+  private static async _prepareAndDedupe(
+    entityType: ERPObjType,
+    mmRecords: IToRESTApiObject[],
+    batchCacheManager: BatchCacheManager | null
+  ): Promise<{
+    toProcess: IToRESTApiObject[];
+    result: WriteEntitiesToMMResult;
+  }> {
+    let toProcess: IToRESTApiObject[] = [];
+    const result: WriteEntitiesToMMResult = {
+      message: "",
+      upsertedEntities: 0,
+      localDedupeCount: 0,
+      apiDedupeCount: 0,
+    };
+
+    if (batchCacheManager) {
+      const { nonDuplicates, duplicates } =
+        (await batchCacheManager.dedupeBatch(entityType, mmRecords)) as {
+          nonDuplicates: IToRESTApiObject[];
+          duplicates: IToRESTApiObject[];
+        };
+      toProcess = nonDuplicates;
+      result.localDedupeCount = duplicates.length;
+    } else {
+      toProcess = mmRecords;
+    }
+
+    return { toProcess, result };
+  }
+
+  /**
+   * Sends records to MM API
+   */
+  private static async _sendToAPI(
+    entityType: ERPObjType,
+    toProcess: IToRESTApiObject[]
+  ): Promise<MMApiBaseResponse> {
+    const mmApiClient = new MMApiClient();
+
+    switch (entityType) {
+      case ERPObjType.PERSONS:
+        return await mmApiClient.sendPersonsToMM(toProcess as MMSendPerson[]);
+      case ERPObjType.RESOURCES:
+        return await mmApiClient.sendResourcesToMM(
+          toProcess as MMSendResource[]
+        );
+      case ERPObjType.PARTS:
+        return await mmApiClient.sendPartsToMM(toProcess as MMSendPart[]);
+      case ERPObjType.PART_OPERATION:
+        return await mmApiClient.sendPartOperationsToMM(
+          toProcess as MMSendPartOperation[]
+        );
+      case ERPObjType.WORK_ORDERS:
+        return await mmApiClient.sendWorkOrdersToMM(
+          toProcess as MMSendWorkOrder[]
+        );
+      case ERPObjType.WORK_ORDER_OPERATIONS:
+        return await mmApiClient.sendWorkOrderOperationsToMM(
+          toProcess as MMSendWorkOrderOperation[]
+        );
+      case ERPObjType.LABOR_TICKETS:
+        return await mmApiClient.sendLaborTicketsToMM(
+          toProcess as MMSendLaborTicket[]
+        );
+      case ERPObjType.REASONS:
+        return await mmApiClient.sendReasonsToMM(toProcess as MMSendReason[]);
+      default:
+        throw new Error(`Unknown entity type: ${entityType}`);
+    }
+  }
+
+  /**
+   * Handles exceptions from API calls, converting structured 500 errors to MMBatchValidationError
+   * @throws MMBatchValidationError for structured 500 errors
+   * @throws The original exception for all other errors
+   */
+  private static _handleException(
+    exception: unknown,
+    entityType: ERPObjType,
+    result: WriteEntitiesToMMResult
+  ): never {
+    // Handle structured 500 errors that may be appropriate for partial failure
+    const structuredCompleteErrorSet =
+      ErrorProcessor.extractErrorDetailsFrom500Exception(exception, entityType);
+
+    if (structuredCompleteErrorSet) {
+      const ex = exception as Record<string, unknown>;
+      const data = ex?.data as Record<string, unknown>;
+      const errorMessage =
+        typeof data?.error === "string"
+          ? data.error
+          : "All entities failed to import";
+
+      throw new MMBatchValidationError({
+        message: errorMessage,
+        upsertedEntities: 0,
+        localDedupeCount: result.localDedupeCount,
+        apiDedupeCount: 0,
+        errorCount: structuredCompleteErrorSet.errorCount,
+        httpStatus: (exception as HTTPError).status,
+        batchErrors: structuredCompleteErrorSet.batchErrors,
+      });
+    }
+
+    // For all other exceptions, re-throw as-is
+    throw exception;
+  }
+
+  /**
+   * Handles the MM API response based on HTTP status code, caching successful records
+   * and throwing exceptions for partial failures
+   *
+   * @returns The final result for success cases
+   * @throws MMBatchValidationError for partial success cases
+   * @throws Error for unknown status codes
+   */
+  private static async _handleResponse(
+    mmApiResponse: MMApiBaseResponse,
+    entityType: ERPObjType,
+    toProcess: IToRESTApiObject[],
+    result: WriteEntitiesToMMResult,
+    batchCacheManager: BatchCacheManager | null
+  ): Promise<WriteEntitiesToMMResult> {
+    if (mmApiResponse.httpStatus === 200) {
+      // Complete success - cache all records
+      if (batchCacheManager) {
+        await batchCacheManager.storeBatch(entityType, toProcess);
+      }
+
+      if (entityType === ERPObjType.LABOR_TICKETS) {
+        const success = mmApiResponse as MM200LaborTicketResponse;
+        result.message = success.message || "Entities processed successfully";
+        result.upsertedEntities =
+          (success.updated || 0) + (success.inserted || 0);
+      } else {
+        const success = mmApiResponse as MM200NonLaborTicketResponse;
+        result.message = success.message || "Entities processed successfully";
+        result.upsertedEntities = success.affectedRows || 0;
+      }
+      result.apiDedupeCount = toProcess.length - result.upsertedEntities;
+
+      return result;
+    } else if (mmApiResponse.httpStatus === 207) {
+      // Partial success - cache only successful records before throwing exception
+      const partialResponse = mmApiResponse as
+        | MM207NonLaborTicketResponse
+        | MM207LaborTicketResponse;
+      const { errorCount, batchErrors } = ErrorProcessor.extractErrorDetails(
+        partialResponse,
+        entityType
+      );
+
+      if (batchCacheManager) {
+        await ErrorProcessor.cacheSuccessfulRecordsOnPartialFailure(
+          entityType,
+          toProcess,
+          batchErrors,
+          batchCacheManager
+        );
+      }
+
+      let upsertedEntities = 0;
+      if (entityType === ERPObjType.LABOR_TICKETS) {
+        const partial = partialResponse as MM207LaborTicketResponse;
+        upsertedEntities =
+          (partial.data.updated || 0) + (partial.data.inserted || 0);
+      } else {
+        const partial = partialResponse as MM207NonLaborTicketResponse;
+        upsertedEntities = partial.data.affectedRows || 0;
+      }
+
+      throw new MMBatchValidationError({
+        message:
+          partialResponse.message || "Entities processed with partial failures",
+        upsertedEntities: upsertedEntities,
+        localDedupeCount: result.localDedupeCount,
+        apiDedupeCount: toProcess.length - upsertedEntities - errorCount,
+        errorCount: errorCount,
+        httpStatus: mmApiResponse.httpStatus,
+        batchErrors: batchErrors,
+      });
+    } else {
+      throw new Error(
+        `writeEntitiesToMM: Unknown HTTP status code: ${mmApiResponse.httpStatus}. An exception was expected.`
+      );
+    }
+  }
+}