@machinemetrics/mm-erp-sdk 0.2.0-beta.0 → 0.2.0-beta.1

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

@@ -1,37 +1,8 @@
 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 LOGGER_ERROR_PREFIX = "[mm-erp-sdk logger]";
-
-const serializeLoggerError = (error: unknown): string => {
-  if (error instanceof Error) {
-    return error.stack ?? error.message;
-  }
-  if (typeof error === "string") {
-    return error;
-  }
-  try {
-    return JSON.stringify(error);
-  } catch {
-    return String(error);
-  }
-};
-
-const handleLoggerError = (error: unknown) => {
-  const serialized = serializeLoggerError(error);
-  try {
-    // eslint-disable-next-line no-console
-    console.error(`${LOGGER_ERROR_PREFIX} transport error: ${serialized}`);
-  } catch {
-    /* ignore failures when reporting logger errors */
-  }
-};
 
 const MSG_MAX_LEN = 60;
 const MSG_MAX_CHARS = 2048;
@@ -52,8 +23,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;
@@ -89,31 +97,25 @@ const logFormat = format.combine(
   baseFormat
 );
 
-const createConsoleTransport = () => {
-  const consoleTransport = new transports.Console({
-    format: format.combine(
-      format.timestamp(),
-      format.splat(),
-      baseFormat,
-      format.colorize({ all: true })
-    ),
-  });
-  consoleTransport.on("error", handleLoggerError);
-  return consoleTransport;
-};
-
 // Create a basic logger with default configuration
 const logger = createLogger({
-  level: initialLogLevel,
+  level: process.env.LOG_LEVEL || "info",
   format: logFormat,
-  transports: [createConsoleTransport()],
+  transports: [
+    new transports.Console({
+      format: format.combine(
+        format.timestamp(),
+        format.splat(),
+        baseFormat,
+        format.colorize({ all: true })
+      ),
+    }),
+  ],
 });
 
-logger.on("error", handleLoggerError);
-
 // Helper function to create a file transport with shared configuration
 const createFileTransport = (): DailyRotateFile => {
-  const transport = new DailyRotateFile({
+  return new DailyRotateFile({
     filename: path.join(logDirectory, "%DATE%.log"),
     datePattern: "YYYY-MM-DD",
     zippedArchive: true,
@@ -121,8 +123,6 @@ const createFileTransport = (): DailyRotateFile => {
     maxFiles: "14d",
     format: logFormat,
   });
-  transport.on("error", handleLoggerError);
-  return transport;
 };
 
 // Rotate mitigation helper: attaches rotate handler to transport and recursively attaches to replacements
@@ -136,76 +136,35 @@ function attachRotateMitigation(
     if (isRefreshing) return;
     isRefreshing = true;
     let removalTimer: NodeJS.Timeout | null = null;
-    let next: DailyRotateFile | null = null;
 
-    const cleanupRefresh = () => {
+    // Create replacement first to avoid any logging gap
+    const next = createFileTransport();
+    // When the new file is created, remove the old transport
+    next.on("new", () => {
       if (removalTimer) {
         clearTimeout(removalTimer);
         removalTimer = null;
       }
+      try {
+        logger.remove(transport);
+      } catch {}
       isRefreshing = false;
-    };
-
-    try {
-      // Create replacement first to avoid any logging gap
-      next = createFileTransport();
-      // When the new file is created, remove the old transport
-      next.on("new", () => {
-        if (removalTimer) {
-          clearTimeout(removalTimer);
-          removalTimer = null;
-        }
-        try {
-          logger.remove(transport);
-        } catch (error) {
-          handleLoggerError(error);
-        }
-        cleanupRefresh();
-      });
-      attachRotateMitigation(next, opts);
+    });
+    attachRotateMitigation(next, opts);
+    logger.add(next);
+
+    // Fallback: if the "new" event doesn't fire, remove the old transport after a grace period
+    const REMOVAL_GRACE_MS = 30000;
+    removalTimer = setTimeout(() => {
       try {
-        logger.add(next);
-      } catch (error) {
-        handleLoggerError(error);
-        cleanupRefresh();
-        try {
-          logger.remove(next);
-        } catch {}
-        try {
-          if (typeof next.close === "function") {
-            next.close();
-          }
-        } catch {}
-        return;
-      }
+        logger.remove(transport);
+      } catch {}
+      isRefreshing = false;
+      removalTimer = null;
+    }, REMOVAL_GRACE_MS);
 
-      // Fallback: if the "new" event doesn't fire, remove the old transport after a grace period
-      const REMOVAL_GRACE_MS = 30000;
-      removalTimer = setTimeout(() => {
-        try {
-          logger.remove(transport);
-        } catch (error) {
-          handleLoggerError(error);
-        }
-        cleanupRefresh();
-      }, REMOVAL_GRACE_MS);
-
-      // Keep console and other transports intact; do not silence or clear
-      logger.level = logLevel;
-    } catch (error) {
-      cleanupRefresh();
-      handleLoggerError(error);
-      if (next) {
-        try {
-          logger.remove(next);
-        } catch {}
-        try {
-          if (typeof next.close === "function") {
-            next.close();
-          }
-        } catch {}
-      }
-    }
+    // Keep console and other transports intact; do not silence or clear
+    logger.level = logLevel;
   });
 }
 
@@ -235,16 +194,22 @@ export const configureLogger = (logLevel: string, nodeEnv: string) => {
 
   // Add console transport in non-production environments
   if (nodeEnv !== "production") {
-    logger.add(createConsoleTransport());
+    logger.add(
+      new transports.Console({
+        format: format.combine(
+          format.timestamp(),
+          format.splat(),
+          baseFormat,
+          format.colorize({ all: true })
+        ),
+      })
+    );
   }
 
   // Set the log level
   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/services/sql-server-erp-service/index.ts

@@ -1,6 +1,6 @@
-import { SqlServerService } from "./sql-server-service.js";
-import { SqlServerHelper } from "./sql-server-helpers.js";
-import { SQLInput } from "./types/sql-input-param.js";
+import { SqlServerService } from "./sql-server-service";
+import { SqlServerHelper } from "./sql-server-helpers";
+import { SQLInput } from "./types/sql-input-param";
 
 /**
  * A class to manage interactions with SQL Server

package/src/services/sql-server-erp-service/internal/sql-labor-ticket-operations.ts

@@ -1,6 +1,6 @@
 import sql from "mssql";
-import { SQLInput } from "../types/sql-input-param.js";
-import { SQLTransactionOperation } from "./sql-transaction-manager.js";
+import { SQLInput } from "../types/sql-input-param";
+import { SQLTransactionOperation } from "./sql-transaction-manager";
 
 /**
  * Insert a new labor ticket into the database.

package/src/services/sql-server-erp-service/internal/sql-transaction-manager.ts

@@ -1,5 +1,5 @@
 import sql from "mssql";
-import logger from "../../reporting-service/logger.js";
+import logger from "../../reporting-service/logger";
 
 export interface SQLTransactionConfig {
   isolationLevel?: sql.IIsolationLevel;

package/src/services/sql-server-erp-service/sql-server-helpers.ts

@@ -1,12 +1,12 @@
-import { SQLTransactionManager } from "./internal/sql-transaction-manager.js";
+import { SQLTransactionManager } from "./internal/sql-transaction-manager";
 import {
   SQLLaborTicketInsertOperation,
   SQLLaborTicketUpdateOperation,
-} from "./internal/sql-labor-ticket-operations.js";
-import { MMReceiveLaborTicket } from "../mm-api-service/types/receive-types.js";
-import { SqlServerService } from "./sql-server-service.js";
-import logger from "../reporting-service/logger.js";
-import { SQLInput } from "./types/sql-input-param.js";
+} from "./internal/sql-labor-ticket-operations";
+import { MMReceiveLaborTicket } from "../mm-api-service/types/receive-types";
+import { SqlServerService } from "./sql-server-service";
+import logger from "../reporting-service/logger";
+import { SQLInput } from "./types/sql-input-param";
 
 export class SqlServerHelper {
   /**

package/src/services/sql-server-erp-service/sql-server-service.ts

@@ -1,8 +1,8 @@
 import sql, { ConnectionPool, IRecordSet } from "mssql";
-import { SQLServerConfigSchema } from "./internal/sql-server-config.js";
-import logger from "../reporting-service/logger.js";
-import { ERPResponse } from "../../types/erp-types.js";
-import { SQLServerConfiguration } from "./configuration.js";
+import { SQLServerConfigSchema } from "./internal/sql-server-config";
+import logger from "../reporting-service/logger";
+import { ERPResponse } from "../../types/erp-types";
+import { SQLServerConfiguration } from "./configuration";
 
 type PagingParams = {
   limit?: number;

package/src/services/sqlite-service/index.ts

@@ -1 +1 @@
-export { SQLiteCoordinator } from "./sqlite-coordinator.js";
+export { SQLiteCoordinator } from "./sqlite-coordinator";

package/src/services/sqlite-service/sqlite-coordinator.ts

@@ -2,8 +2,8 @@ import {
   acquireDatabaseLock,
   releaseDatabaseLock,
   getDatabaseLock,
-} from "../../utils/local-data-store/database-lock.js";
-import { logger } from "../reporting-service/index.js";
+} from "../../utils/local-data-store/database-lock";
+import { logger } from "../reporting-service";
 
 export class SQLiteCoordinator {
   private static readonly LOCK_TIMEOUT_MS = 30_000; // 30 seconds

package/src/types/erp-connector.ts

@@ -1,4 +1,4 @@
-import { MMReceiveLaborTicket } from "../services/mm-api-service/types/receive-types.js";
+import { MMReceiveLaborTicket } from "../services/mm-api-service/types/receive-types";
 
 /**
  * Interface for ERP connectors.
@@ -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

@@ -3,18 +3,10 @@
  * This file re-exports all type definitions that are part of the public API.
  */
 
-export type { IERPConnector } from "./erp-connector.js";
+export type { IERPConnector } from "./erp-connector";
 export type {
   ERPObjType,
   ERPPagination,
   ERPResponse,
   ERPObject,
-} from "./erp-types.js";
-export type {
-  FlattenedWorkOrderRow,
-  FlattenedWorkOrderRowBase,
-  FlattenedWorkOrderPartFields,
-  FlattenedWorkOrderPartOperationFields,
-  FlattenedWorkOrderFields,
-  FlattenedWorkOrderOperationFields,
-} from "./flattened-work-order.js";
+} from "./erp-types";

package/src/utils/application-initializer.ts

@@ -1,9 +1,9 @@
-import logger from "../services/reporting-service/logger.js";
-import { CoreConfiguration } from "../services/data-sync-service/configuration-manager.js";
-import { SQLiteCoordinator } from "../services/sqlite-service/index.js";
-import { getTimezoneOffsetAndPersist } from "./time-utils.js";
+import logger from "../services/reporting-service/logger";
+import { CoreConfiguration } from "../services/data-sync-service/configuration-manager";
+import { SQLiteCoordinator } from "../services/sqlite-service";
+import { getTimezoneOffsetAndPersist } from "./time-utils";
 import knex from "knex";
-import config from "../knexfile.js";
+import config from "../knexfile";
 
 /**
  * Utility class to handle application initialization tasks

package/src/utils/connector-factory.ts

@@ -1,5 +1,5 @@
-import { IERPConnector } from "../types/erp-connector.js";
-import logger from "../services/reporting-service/logger.js";
+import { IERPConnector } from "../types/erp-connector";
+import logger from "../services/reporting-service/logger";
 import { pathToFileURL } from "url";
 
 /**

package/src/utils/connector-log/log-deduper.ts

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import path from 'path';
-import logger from '../../services/reporting-service/logger.js';
-import type { LogEntry, LogLevelString } from './mm-connector-logger.js';
+import logger from '../../services/reporting-service/logger';
+import type { LogEntry, LogLevelString } from './mm-connector-logger';
 
 /**
  * Implement a custom LogDeduper or use the provided FileLogDeduper

package/src/utils/connector-log/mm-connector-logger.ts

@@ -1,6 +1,6 @@
-import { MMApiClient } from '../../services/mm-api-service/mm-api-service.js';
-import logger from '../../services/reporting-service/logger.js';
-import type { LogDeduper } from './log-deduper.js';
+import { MMApiClient } from '../../services/mm-api-service/mm-api-service';
+import logger from '../../services/reporting-service/logger';
+import type { LogDeduper } from './log-deduper';
 
 export type LogLevelString = 'info' | 'warn' | 'error';
 

package/src/utils/erp-type-from-entity.ts

@@ -1,4 +1,4 @@
-import { ERPObjType } from "../types/erp-types.js";
+import { ERPObjType } from "../types/erp-types";
 
 export function getERPAPITypeFromEntity(
   entity: string,

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

@@ -1,5 +1,5 @@
 import axios, { AxiosError, AxiosInstance, AxiosRequestConfig } from "axios";
-import logger from "../services/reporting-service/logger.js";
+import logger from "../services/reporting-service/logger";
 
 export class HTTPError extends Error {
   constructor(
@@ -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",
       },