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

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

@@ -1,8 +1,37 @@
 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;
@@ -23,45 +52,8 @@ 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 = safeStringify(rest, 2);
+  let restString = JSON.stringify(rest, undefined, 2);
   restString = restString === "{}" ? "" : restString;
 
   let formattedMessage: string;
@@ -97,25 +89,31 @@ 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: process.env.LOG_LEVEL || "info",
+  level: initialLogLevel,
   format: logFormat,
-  transports: [
-    new transports.Console({
-      format: format.combine(
-        format.timestamp(),
-        format.splat(),
-        baseFormat,
-        format.colorize({ all: true })
-      ),
-    }),
-  ],
+  transports: [createConsoleTransport()],
 });
 
+logger.on("error", handleLoggerError);
+
 // Helper function to create a file transport with shared configuration
 const createFileTransport = (): DailyRotateFile => {
-  return new DailyRotateFile({
+  const transport = new DailyRotateFile({
     filename: path.join(logDirectory, "%DATE%.log"),
     datePattern: "YYYY-MM-DD",
     zippedArchive: true,
@@ -123,6 +121,8 @@ 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,35 +136,76 @@ function attachRotateMitigation(
     if (isRefreshing) return;
     isRefreshing = true;
     let removalTimer: NodeJS.Timeout | null = null;
+    let next: DailyRotateFile | null = null;
 
-    // Create replacement first to avoid any logging gap
-    const next = createFileTransport();
-    // When the new file is created, remove the old transport
-    next.on("new", () => {
+    const cleanupRefresh = () => {
       if (removalTimer) {
         clearTimeout(removalTimer);
         removalTimer = null;
       }
-      try {
-        logger.remove(transport);
-      } catch {}
       isRefreshing = false;
-    });
-    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 {
+      // 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);
       try {
-        logger.remove(transport);
-      } catch {}
-      isRefreshing = false;
-      removalTimer = null;
-    }, REMOVAL_GRACE_MS);
+        logger.add(next);
+      } catch (error) {
+        handleLoggerError(error);
+        cleanupRefresh();
+        try {
+          logger.remove(next);
+        } catch {}
+        try {
+          if (typeof next.close === "function") {
+            next.close();
+          }
+        } catch {}
+        return;
+      }
 
-    // Keep console and other transports intact; do not silence or clear
-    logger.level = logLevel;
+      // 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 {}
+      }
+    }
   });
 }
 
@@ -194,22 +235,16 @@ export const configureLogger = (logLevel: string, nodeEnv: string) => {
 
   // Add console transport in non-production environments
   if (nodeEnv !== "production") {
-    logger.add(
-      new transports.Console({
-        format: format.combine(
-          format.timestamp(),
-          format.splat(),
-          baseFormat,
-          format.colorize({ all: true })
-        ),
-      })
-    );
+    logger.add(createConsoleTransport());
   }
 
   // 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";
-import { SqlServerHelper } from "./sql-server-helpers";
-import { SQLInput } from "./types/sql-input-param";
+import { SqlServerService } from "./sql-server-service.js";
+import { SqlServerHelper } from "./sql-server-helpers.js";
+import { SQLInput } from "./types/sql-input-param.js";
 
 /**
  * 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";
-import { SQLTransactionOperation } from "./sql-transaction-manager";
+import { SQLInput } from "../types/sql-input-param.js";
+import { SQLTransactionOperation } from "./sql-transaction-manager.js";
 
 /**
  * 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";
+import logger from "../../reporting-service/logger.js";
 
 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";
+import { SQLTransactionManager } from "./internal/sql-transaction-manager.js";
 import {
   SQLLaborTicketInsertOperation,
   SQLLaborTicketUpdateOperation,
-} 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";
+} 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";
 
 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";
-import logger from "../reporting-service/logger";
-import { ERPResponse } from "../../types/erp-types";
-import { SQLServerConfiguration } from "./configuration";
+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";
 
 type PagingParams = {
   limit?: number;

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

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

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

@@ -2,8 +2,8 @@ import {
   acquireDatabaseLock,
   releaseDatabaseLock,
   getDatabaseLock,
-} from "../../utils/local-data-store/database-lock";
-import { logger } from "../reporting-service";
+} from "../../utils/local-data-store/database-lock.js";
+import { logger } from "../reporting-service/index.js";
 
 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";
+import { MMReceiveLaborTicket } from "../services/mm-api-service/types/receive-types.js";
 
 /**
  * Interface for ERP connectors.
@@ -14,6 +14,10 @@ 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>;
@@ -31,13 +35,16 @@ export interface IERPConnector {
   retryFailedLaborTicketsCompleted(): Promise<void>;
 
   /**
-   * Start the connector. Typically a connector should delegate control to the data-sync-service.
+   * Start the connector. Typically a connector should delegate control to the data-sync-service via runDataSyncService().
    */
   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/flattened-work-order.ts

@@ -0,0 +1,108 @@
+/**
+ * Canonical representation of a flattened work order row that contains the
+ * information needed to build MM work order entities plus their operations.
+ *
+ * All properties are optional to maintain backwards compatibility with
+ * existing connectors.
+ */
+export interface FlattenedWorkOrderPartFields {
+  /** ERP part number (required for Parts when present). */
+  partNumber?: string | number;
+  /** ERP part revision or version string. */
+  partRevision?: string | number;
+  /** Routing/method identifier (defaults to "Standard" when omitted). */
+  method?: string;
+}
+
+export interface FlattenedWorkOrderPartOperationFields {
+  /** Sequence number of the operation on the routing. */
+  sequenceNumber?: string | number;
+  /** Resource or machine identifier responsible for the operation. */
+  resourceId?: string | number;
+  /** Operation cycle time expressed in milliseconds. */
+  cycleTimeMs?: number;
+  /** Operation setup time expressed in milliseconds. */
+  setupTimeMs?: number;
+  /** Human-readable description of the operation. */
+  operationDescription?: string;
+  /** Quantity of parts operated on per cycle. */
+  quantityPerPart?: number;
+}
+
+export interface FlattenedWorkOrderFields
+  extends FlattenedWorkOrderPartFields {
+  /** Unique identifier for the work order in the ERP. */
+  workOrderId?: string | number;
+  /** Lot number (if the ERP distinguishes lots). */
+  lot?: string | number;
+  /** Split identifier (if the ERP splits orders). */
+  split?: string | number;
+  /** Sub identifier (for multi-level orders). */
+  sub?: string | number;
+  /** Work order status (e.g., Open, Closed, Released). */
+  status?: string;
+  /**
+   * Due date expressed as an ISO-8601 UTC string (trailing `Z` or explicit offset).
+   * The SDK validates but does not shift timezones.
+   */
+  dueDate?: string;
+  /** Free-form description of the work order. */
+  description?: string;
+  /** Scheduled start datetime in ISO-8601 UTC form. */
+  scheduledStartDate?: string;
+  /** Scheduled end datetime in ISO-8601 UTC form. */
+  scheduledEndDate?: string;
+  /** Closed datetime in ISO-8601 UTC form. */
+  closedDate?: string;
+  /** Quantity required by the work order. */
+  quantityRequired?: number;
+}
+
+export interface FlattenedWorkOrderOperationFields {
+  /** Work order identifier (repeated for each operation). */
+  workOrderId?: string | number;
+  /** Lot identifier for the operation row. */
+  lot?: string | number;
+  /** Split identifier for the operation row. */
+  split?: string | number;
+  /** Sub identifier for the operation row. */
+  sub?: string | number;
+  /** Sequence number for the specific operation. */
+  sequenceNumber?: string | number;
+  /** Resource or machine identifier for the operation. */
+  resourceId?: string | number;
+  /** Quantity started on the operation. */
+  startQuantity?: number;
+  /** Quantity finished on the operation. */
+  finishQuantity?: number;
+  /** Expected reject percentage (0-1). */
+  expectedRejectRate?: number;
+  /** Scheduled start datetime (ISO-8601 UTC). */
+  opScheduledStartDate?: string;
+  /** Scheduled finish datetime (ISO-8601 UTC). */
+  opScheduledFinishDate?: string;
+  /** Closed datetime for the operation (ISO-8601 UTC). */
+  opClosedDate?: string;
+  /** Production burden rate per hour. */
+  productionburdenRateHourly?: number | string;
+  /** Setup burden rate per hour. */
+  setupburdenRatehourly?: number | string;
+  /** Operation type (Production, Setup, etc.). */
+  operationType?: string;
+  /** Quantity per part for the operation. */
+  quantityPerPart?: number;
+  /** Operation status (defaults to work-order status when omitted). */
+  opStatus?: string;
+}
+
+export type FlattenedWorkOrderRowBase =
+  FlattenedWorkOrderPartFields &
+  FlattenedWorkOrderPartOperationFields &
+  FlattenedWorkOrderFields &
+  FlattenedWorkOrderOperationFields;
+
+/**
+ * Canonical flattened row that callers pass into
+ * `StandardProcessDrivers.syncWorkOrderBatchFromFlattened`.
+ */
+export type FlattenedWorkOrderRow = FlattenedWorkOrderRowBase;

package/src/types/index.ts

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

package/src/utils/application-initializer.ts

@@ -1,9 +1,9 @@
-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 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 knex from "knex";
-import config from "../knexfile";
+import config from "../knexfile.js";
 
 /**
  * Utility class to handle application initialization tasks

package/src/utils/connector-factory.ts

@@ -1,5 +1,5 @@
-import { IERPConnector } from "../types/erp-connector";
-import logger from "../services/reporting-service/logger";
+import { IERPConnector } from "../types/erp-connector.js";
+import logger from "../services/reporting-service/logger.js";
 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';
-import type { LogEntry, LogLevelString } from './mm-connector-logger';
+import logger from '../../services/reporting-service/logger.js';
+import type { LogEntry, LogLevelString } from './mm-connector-logger.js';
 
 /**
  * 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';
-import logger from '../../services/reporting-service/logger';
-import type { LogDeduper } from './log-deduper';
+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';
 
 export type LogLevelString = 'info' | 'warn' | 'error';
 

package/src/utils/env.ts

@@ -0,0 +1,75 @@
+/**
+ * This module contains utility functions to get environment variables with default values and validation.
+ */
+
+const normalizeValue = (value?: string | null): string | undefined => {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const lowered = trimmed.toLowerCase();
+  if (lowered === "undefined" || lowered === "null") {
+    return undefined;
+  }
+
+  return trimmed;
+};
+
+const warnInvalid = (key: string, rawValue: string | undefined, reason: string) => {
+  const received = rawValue !== undefined ? `; received "${rawValue}"` : "";
+  console.warn(`[config] ${key} ${reason}${received}`); // eslint-disable-line no-console
+};
+
+export const getEnvString = (key: string, defaultValue = ""): string => {
+  const normalized = normalizeValue(process.env[key]);
+  return normalized ?? defaultValue;
+};
+
+export const getEnvNumber = (
+  key: string,
+  defaultValue: number
+): number => {
+  const normalized = normalizeValue(process.env[key]);
+  if (normalized === undefined) {
+    return defaultValue;
+  }
+
+  const parsed = Number.parseInt(normalized, 10);
+  if (Number.isNaN(parsed)) {
+    warnInvalid(key, normalized, `is not a valid number for key ${key}; falling back to default ${defaultValue}`);
+    return defaultValue;
+  }
+
+  return parsed;
+};
+
+export const getEnvBoolean = (key: string, defaultValue = false): boolean => {
+  const normalized = normalizeValue(process.env[key]);
+  if (normalized === undefined) {
+    return defaultValue;
+  }
+
+  const truthyValues = new Set(["true", "1", "yes", "y", "on"]);
+  const falsyValues = new Set(["false", "0", "no", "n", "off"]);
+  const lowered = normalized.toLowerCase();
+
+  if (truthyValues.has(lowered)) {
+    return true;
+  }
+  if (falsyValues.has(lowered)) {
+    return false;
+  }
+
+  warnInvalid(key, normalized, "is not a recognized boolean; falling back to default");
+  return defaultValue;
+};
+
+export const getOptionalEnv = (key: string): string | undefined => {
+  return normalizeValue(process.env[key]);
+};
+