@machinemetrics/mm-erp-sdk 0.3.0-beta.0 → 0.3.0-beta.2

package/src/services/reporting-service/logger.ts

@@ -1,11 +1,9 @@
 import { createLogger, format, transports } from "winston";
 import DailyRotateFile from "winston-daily-rotate-file";
 import path from "path";
-import { getEnvString } from "../../utils/env.js"; // Utility function to get environment variables with default values and validation
 
 const logDirectory = "logs";
-const initialLogLevel = getEnvString("LOG_LEVEL", "info");
-const initialNodeEnv = getEnvString("NODE_ENV", "development");
+const initialLogLevel = process.env.LOG_LEVEL || "info";
 
 const LOGGER_ERROR_PREFIX = "[mm-erp-sdk logger]";
 
@@ -52,8 +50,45 @@ const truncateString = (str: string): string => {
   return result;
 };
 
+/**
+ * Safe JSON serializer that handles circular references and extracts meaningful error data
+ */
+const safeStringify = (obj: any, indent: number = 2): string => {
+  const seen = new WeakSet();
+  
+  return JSON.stringify(
+    obj,
+    (key, value) => {
+      // Handle Error objects specially
+      if (value instanceof Error) {
+        return {
+          message: value.message,
+          name: value.name,
+          stack: value.stack,
+          ...(value.constructor.name === 'HTTPError' || value.constructor.name === 'AxiosError' ? {
+            status: (value as any).status,
+            code: (value as any).code,
+            data: (value as any).data,
+          } : {}),
+        };
+      }
+      
+      // Handle circular references
+      if (typeof value === "object" && value !== null) {
+        if (seen.has(value)) {
+          return "[Circular]";
+        }
+        seen.add(value);
+      }
+      
+      return value;
+    },
+    indent
+  );
+};
+
 const baseFormat = format.printf(({ timestamp, level, message, ...rest }) => {
-  let restString = JSON.stringify(rest, undefined, 2);
+  let restString = safeStringify(rest, 2);
   restString = restString === "{}" ? "" : restString;
 
   let formattedMessage: string;
@@ -242,9 +277,6 @@ export const configureLogger = (logLevel: string, nodeEnv: string) => {
   logger.level = logLevel;
 };
 
-// Ensure file logging is configured as soon as the module loads
-configureLogger(initialLogLevel, initialNodeEnv);
-
 // Add fatal method for Graceful compatibility
 (logger as any).fatal = (err: any, meta?: any) => logger.error(err, meta);
 

package/src/types/erp-connector.ts

@@ -14,10 +14,6 @@ export interface IERPConnector {
 
   /**
    * Sync data from the ERP system to MM.
-   * Timezone expectations:
-   * - When sending ERP data to MachineMetrics (e.g., via StandardProcessDrivers or MMEntityProcessor),
-   *   connectors MUST convert all datetime fields to ISO-8601 UTC strings (trailing `Z` or explicit offset)
-   *   before invoking SDK helpers. The SDK validates/forwards these values but does not apply timezone shifts.
    */
   syncFromERP(): Promise<void>;
   syncFromERPCompleted(): Promise<void>;
@@ -35,16 +31,13 @@ export interface IERPConnector {
   retryFailedLaborTicketsCompleted(): Promise<void>;
 
   /**
-   * Start the connector. Typically a connector should delegate control to the data-sync-service via runDataSyncService().
+   * Start the connector. Typically a connector should delegate control to the data-sync-service.
    */
   startUp(): Promise<void>;
 }
 
 /**
  * Interface for standard process methods that call ERP connectors back to create or update labor tickets.
- *
- * Timestamp fields on `MMReceiveLaborTicket` objects have already been converted by the SDKfrom MM's
- * UTC API responses into the ERP's local timezone, based on the company's timezone setting.
  */
 export interface IERPLaborTicketHandler {
   createLaborTicketInERP(

package/src/types/index.ts

@@ -10,11 +10,3 @@ export type {
   ERPResponse,
   ERPObject,
 } from "./erp-types.js";
-export type {
-  FlattenedWorkOrderRow,
-  FlattenedWorkOrderRowBase,
-  FlattenedWorkOrderPartFields,
-  FlattenedWorkOrderPartOperationFields,
-  FlattenedWorkOrderFields,
-  FlattenedWorkOrderOperationFields,
-} from "./flattened-work-order.js";

package/src/utils/error-formatter.ts

@@ -0,0 +1,205 @@
+/**
+ * Error formatter utility for standardizing error messages across connectors
+ * Extracts human-readable messages from various error types (axios, custom errors, etc.)
+ */
+
+export interface FormattedError {
+  message: string;
+  code: string;
+  httpStatus?: number;
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Extract meaningful error message from various error types
+ */
+export function formatError(error: any): FormattedError {
+  if (!error) {
+    return {
+      message: 'Unknown error occurred',
+      code: 'UNKNOWN_ERROR',
+    };
+  }
+
+  // Handle axios errors FIRST (before checking for FormattedError)
+  // because axios errors also have message and code properties
+  if (error.isAxiosError || error.name === 'AxiosError') {
+    return formatAxiosError(error);
+  }
+
+  // If it's already a FormattedError, return as-is
+  // Check for httpStatus or metadata to distinguish from axios errors
+  if (error.message && error.code && typeof error.message === 'string' && typeof error.code === 'string' && !error.config) {
+    return error as FormattedError;
+  }
+
+  // Handle standard Error objects
+  if (error instanceof Error) {
+    return {
+      message: error.message || 'An error occurred',
+      code: 'ERROR',
+      metadata: {
+        name: error.name,
+      },
+    };
+  }
+
+  // Handle string errors
+  if (typeof error === 'string') {
+    return {
+      message: error,
+      code: 'ERROR',
+    };
+  }
+
+  // Last resort: try to extract any useful info
+  const message = error.message || error.toString?.() || 'Unknown error occurred';
+  return {
+    message: typeof message === 'string' ? message : JSON.stringify(message),
+    code: error.code || 'UNKNOWN_ERROR',
+  };
+}
+
+/**
+ * Format axios-specific errors with detailed context
+ */
+function formatAxiosError(error: any): FormattedError {
+  const httpStatus = error.response?.status;
+  const method = error.config?.method?.toUpperCase();
+  const url = error.config?.url;
+  
+  // First check if connector already extracted the message
+  let message = error._extractedMessage;
+  
+  // If not, try to extract from response data
+  if (!message) {
+    const extractedMessage = extractErrorMessage(error.response?.data);
+    message = extractedMessage || error.response?.statusText || error.message || 'Request failed';
+  }
+
+  // Determine error code based on status
+  const code = categorizeHttpError(httpStatus);
+
+  const metadata: Record<string, any> = {
+    method,
+    url,
+  };
+
+  // Add additional context for specific error types
+  if (httpStatus === 401 || httpStatus === 403) {
+    metadata.hint = 'Check authentication credentials';
+  } else if (httpStatus === 404) {
+    metadata.hint = 'Resource not found - check endpoint URL';
+  } else if (httpStatus && httpStatus >= 500) {
+    metadata.hint = 'ERP system may be temporarily unavailable';
+  }
+
+  return {
+    message,
+    code,
+    httpStatus,
+    metadata,
+  };
+}
+
+/**
+ * Extract meaningful error message from response data
+ * Handles various ERP-specific response formats
+ */
+function extractErrorMessage(data: any): string | null {
+  if (!data) return null;
+
+  // Common error message fields across different ERPs
+  const possibleFields = [
+    'ErrorMessage',        // Epicor
+    'error.message',       // Common REST format
+    'error',               // Simple format
+    'Message',             // .NET style
+    'message',             // JavaScript style
+    'errorMessage',        // Camel case
+    'error_message',       // Snake case
+    'errors[0].message',   // Array of errors
+    'title',               // Problem details format
+    'detail',              // Problem details format
+  ];
+
+  for (const field of possibleFields) {
+    const value = getNestedValue(data, field);
+    if (value && typeof value === 'string') {
+      return value;
+    }
+  }
+
+  // If data is a string, return it
+  if (typeof data === 'string') {
+    // Try to parse as JSON first
+    try {
+      const parsed = JSON.parse(data);
+      return extractErrorMessage(parsed);
+    } catch {
+      return data;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get nested value from object using dot notation
+ */
+function getNestedValue(obj: any, path: string): any {
+  const parts = path.split('.');
+  let current = obj;
+
+  for (const part of parts) {
+    // Handle array notation like 'errors[0]'
+    const arrayMatch = part.match(/(\w+)\[(\d+)\]/);
+    if (arrayMatch) {
+      const [, key, index] = arrayMatch;
+      current = current?.[key]?.[parseInt(index, 10)];
+    } else {
+      current = current?.[part];
+    }
+
+    if (current === undefined || current === null) {
+      return null;
+    }
+  }
+
+  return current;
+}
+
+/**
+ * Categorize HTTP errors into standard codes
+ */
+function categorizeHttpError(status?: number): string {
+  if (!status) return 'NETWORK_ERROR';
+
+  if (status === 400) return 'VALIDATION_ERROR';
+  if (status === 401) return 'AUTHENTICATION_ERROR';
+  if (status === 403) return 'AUTHORIZATION_ERROR';
+  if (status === 404) return 'NOT_FOUND';
+  if (status === 409) return 'CONFLICT';
+  if (status === 422) return 'VALIDATION_ERROR';
+  if (status === 429) return 'RATE_LIMIT';
+  if (status >= 500) return 'ERP_SERVER_ERROR';
+  if (status >= 400) return 'CLIENT_ERROR';
+
+  return 'HTTP_ERROR';
+}
+
+/**
+ * Format error for logging (shorter, cleaner version)
+ */
+export function formatErrorForLogging(error: any): string {
+  const formatted = formatError(error);
+  
+  let message = `[${formatted.code}] ${formatted.message}`;
+  
+  if (formatted.httpStatus) {
+    message = `[${formatted.httpStatus}] ${message}`;
+  }
+  
+  return message;
+}
+

package/src/utils/http-client.ts

@@ -64,9 +64,10 @@ class AxiosClient implements HTTPClient {
    *   It can be convenient to set `baseURL` for an instance of axios to pass relative URLs to methods of that instance.
    */
   constructor(baseUrl: string, retryAttempts: number) {
+    const timeout = parseInt(process.env.MM_API_TIMEOUT || "30000");
     this.client = axios.create({
       baseURL: baseUrl,
-      timeout: 30000,
+      timeout: timeout,
       headers: {
         "Content-Type": "application/json",
       },
@@ -108,7 +109,7 @@ class AxiosClient implements HTTPClient {
       params: config.params,
       signal: controller.signal,
     };
-// MLW TODO
+
     logger.info("HTTP request starting", { 
       url: config.url, 
       method: config.method, 
@@ -127,10 +128,8 @@ class AxiosClient implements HTTPClient {
     try {
       for (let attempt = 0; attempt <= this.retryAttempts; attempt++) {
         try {
-          // MLW TODO
           logger.info(`HTTP request attempt ${attempt + 1}/${this.retryAttempts + 1}`);
           const response = await this.client.request<T>(axiosConfig);
-          // MLW TODO
           logger.info("HTTP request succeeded", { status: response.status });
           return {
             data: response.data,

package/src/utils/index.ts

@@ -17,11 +17,6 @@ export {
 export { getTimezoneOffsetAndPersist } from "./time-utils.js";
 export { formatDateWithTZOffset, convertToLocalTime, toISOWithOffset } from "./timezone.js";
 export { applyTimezoneOffsetsToFields } from "./time-utils.js";
-export {
-  convertUtcDateTimeToErpLocal,
-  convertErpLocalDateTimeToUtc,
-  getERPTimezone,
-} from "./erp-timezone-utils.js";
 export * from "./time-utils.js";
 
 /**
@@ -69,6 +64,12 @@ export type { HTTPClient, HTTPRequestConfig, HTTPResponse } from "./http-client.
 export * from "./mm-labor-ticket-helpers.js";
 export { getErrorType } from './error-utils.js';
 
+/**
+ * Error formatting utilities
+ */
+export { formatError, formatErrorForLogging } from './error-formatter.js';
+export type { FormattedError } from './error-formatter.js';
+
 /**
  * MM Connector Logger utilities
  */

package/src/utils/local-data-store/jobs-shared-data.ts

@@ -72,8 +72,6 @@ export const setInitialLoadComplete = (complete: boolean): void => {
 };
 
 /**
- * @deprecated The cached numeric offset cannot account for DST changes.
- * Prefer using the cached timezone name with Luxon helpers for conversions.
  * Gets the company's cached current timezone offset (e.g., -5)
  * @returns The cached timezone offset or 0 if not found
  */

package/src/utils/mm-labor-ticket-helpers.ts

@@ -1,13 +1,15 @@
+import { convertToLocalTime, toISOWithOffset } from "./timezone.js";
 import { MMReceiveLaborTicket } from "../services/mm-api-service/types/receive-types.js";
-import { convertUtcDateTimeToErpLocal, getERPTimezone } from "./erp-timezone-utils.js";
 
 /**
- * Converts key datetime fields from UTC (MachineMetrics API) to the ERP's local timezone.
- * All inputs/outputs are ISO-8601 strings, and invalid inputs throw errors.
+ * Apply timezone offsets to datetime fields specifically for the MMApiReceiveLaborTicket object from the Zulu-based MM API
+ * (presumably) before sending to the ERP
  * @param laborTicket The MMApiReceiveLaborTicket object to convert
+ * @param timezoneOffset The timezone offset to apply
  */
 export function convertLaborTicketToLocalTimezone(
-  laborTicket: MMReceiveLaborTicket
+  laborTicket: MMReceiveLaborTicket,
+  timezoneOffset: number
 ): MMReceiveLaborTicket {
   const timeFields = [
     "clockIn",
@@ -18,14 +20,9 @@ export function convertLaborTicketToLocalTimezone(
     "workOrderOperationClosedDate",
   ] as const;
 
-  const timezone = getERPTimezone();
   timeFields.forEach((field) => {
-    const value = laborTicket[field];
-    if (value) {
-      laborTicket[field] = convertUtcDateTimeToErpLocal(value, timezone);
-    } else {
-      laborTicket[field] = null;
-    }
+    const localTime = convertToLocalTime(laborTicket[field], timezoneOffset);
+    laborTicket[field] = localTime ? toISOWithOffset(localTime, timezoneOffset) : null;
   });
   return laborTicket;
 }