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

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]);
+};
+

package/src/utils/erp-timezone-utils.ts

@@ -0,0 +1,99 @@
+import { DateTime } from "luxon";
+import logger from "../services/reporting-service/logger.js";
+import { getCachedTimezoneName } from "./local-data-store/jobs-shared-data.js";
+
+/**
+ * Retrieves the ERP timezone name that should have been cached during initialization.
+ * @throws Error when the timezone cache has not been populated.
+ */
+export function getERPTimezone(): string {
+  const timezone = getCachedTimezoneName();
+  if (!timezone) {
+    throw new Error(
+      "ERP timezone is not cached. Run getTimezoneOffsetAndPersist() to populate it."
+    );
+  }
+  return timezone;
+}
+
+/**
+ * Converts a UTC ISO-8601 datetime string to the ERP's local timezone (also ISO-8601).
+ * @param utcDateTime ISO-8601 datetime string representing UTC time.
+ * @param timezone Optional timezone override; defaults to the cached ERP timezone.
+ * @returns ISO-8601 string in the ERP timezone.
+ */
+export function convertUtcDateTimeToErpLocal(
+  utcDateTime: string,
+  timezone?: string
+): string {
+  if (!utcDateTime) {
+    throw new Error("convertUtcDateTimeToErpLocal requires a non-empty UTC datetime string");
+  }
+  try {
+    const targetZone = timezone ?? getERPTimezone();
+    const parsedUtc = DateTime.fromISO(utcDateTime, { zone: "utc" });
+    if (!parsedUtc.isValid) {
+      throw new Error(
+        `Invalid UTC datetime "${utcDateTime}": ${parsedUtc.invalidReason}`
+      );
+    }
+
+    const localized = parsedUtc.setZone(targetZone);
+    if (!localized.isValid) {
+      throw new Error(
+        `Unable to convert UTC datetime "${utcDateTime}" to target zone "${targetZone}": ${localized.invalidReason}`
+      );
+    }
+
+    return localized.toISO();
+  } catch (error) {
+    logger.error("convertUtcDateTimeToErpLocal: Failed to convert datetime", {
+      utcDateTime,
+      error,
+    });
+    throw new Error(
+      "Failed to convert UTC datetime to ERP local timezone. See logs for details."
+    );
+  }
+}
+
+/**
+ * Converts an ERP-local ISO-8601 datetime string to UTC (still ISO-8601).
+ * @param localDateTime ISO-8601 datetime string representing ERP local time.
+ * @param timezone Optional timezone override; defaults to the cached ERP timezone.
+ * @returns ISO-8601 string in UTC.
+ */
+export function convertErpLocalDateTimeToUtc(
+  localDateTime: string,
+  timezone?: string
+): string {
+  if (!localDateTime) {
+    throw new Error("convertErpLocalDateTimeToUtc requires a non-empty local datetime string");
+  }
+  try {
+    const sourceZone = timezone ?? getERPTimezone();
+    const parsedLocal = DateTime.fromISO(localDateTime, { zone: sourceZone });
+    if (!parsedLocal.isValid) {
+      throw new Error(
+        `Invalid ERP local datetime "${localDateTime}" for zone "${sourceZone}": ${parsedLocal.invalidReason}`
+      );
+    }
+
+    const utcDateTime = parsedLocal.setZone("utc");
+    if (!utcDateTime.isValid) {
+      throw new Error(
+        `Unable to convert ERP local datetime "${localDateTime}" to UTC: ${utcDateTime.invalidReason}`
+      );
+    }
+
+    return utcDateTime.toISO();
+  } catch (error) {
+    logger.error("convertErpLocalDateTimeToUtc: Failed to convert datetime", {
+      localDateTime,
+      error,
+    });
+    throw new Error(
+      "Failed to convert ERP local datetime to UTC. See logs for details."
+    );
+  }
+}

package/src/utils/index.ts

@@ -17,6 +17,11 @@ 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";
 
 /**

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

@@ -72,6 +72,8 @@ 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,15 +1,13 @@
-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";
 
 /**
- * Apply timezone offsets to datetime fields specifically for the MMApiReceiveLaborTicket object from the Zulu-based MM API
- * (presumably) before sending to the ERP
+ * 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.
  * @param laborTicket The MMApiReceiveLaborTicket object to convert
- * @param timezoneOffset The timezone offset to apply
  */
 export function convertLaborTicketToLocalTimezone(
-  laborTicket: MMReceiveLaborTicket,
-  timezoneOffset: number
+  laborTicket: MMReceiveLaborTicket
 ): MMReceiveLaborTicket {
   const timeFields = [
     "clockIn",
@@ -20,9 +18,14 @@ export function convertLaborTicketToLocalTimezone(
     "workOrderOperationClosedDate",
   ] as const;
 
+  const timezone = getERPTimezone();
   timeFields.forEach((field) => {
-    const localTime = convertToLocalTime(laborTicket[field], timezoneOffset);
-    laborTicket[field] = localTime ? toISOWithOffset(localTime, timezoneOffset) : null;
+    const value = laborTicket[field];
+    if (value) {
+      laborTicket[field] = convertUtcDateTimeToErpLocal(value, timezone);
+    } else {
+      laborTicket[field] = null;
+    }
   });
   return laborTicket;
 }

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

@@ -2,7 +2,6 @@ import { IERPLaborTicketHandler } from "../../types/erp-connector.js";
 import { MMApiClient } from "../../services/mm-api-service/mm-api-service.js";
 import { MMReceiveLaborTicket } from "../../services/mm-api-service/types/receive-types.js";
 import { convertLaborTicketToLocalTimezone } from "../mm-labor-ticket-helpers.js";
-import { getCachedTimezoneOffset } from "../local-data-store/jobs-shared-data.js";
 import logger from "../../services/reporting-service/logger.js";
 
 /**
@@ -54,9 +53,12 @@ export class LaborTicketERPSynchronizer {
 
       // 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.
+      // Consider, for instance, a time offset between an edge and the cloud, or that
+      // a DST change may have occurred between the last checkpoint and Now.
       const mostRecentUpdate = laborTicketsUpdates.reduce(
         (latest: string | null, ticket: MMReceiveLaborTicket) => {
-          if (!latest || !ticket.updatedAt) return latest;
+          if (!ticket.updatedAt) return latest;   // Skip tickets without updatedAt
+          if (!latest) return ticket.updatedAt;   // Initialize on first valid value
           return new Date(ticket.updatedAt) > new Date(latest)
             ? ticket.updatedAt
             : latest;
@@ -118,6 +120,9 @@ export class LaborTicketERPSynchronizer {
           timestamp: mostRecentUpdate || fallbackTimestamp,
         },
       });
+      logger.info("syncLaborTicketsToERP: Checkpoint saved:", {
+        checkpointTimestamp: (mostRecentUpdate || fallbackTimestamp)
+      });
     } catch (error) {
       logger.error("syncLaborTicketsToERP: Error:", error);
     }
@@ -214,10 +219,10 @@ export class LaborTicketERPSynchronizer {
   ): Promise<MMReceiveLaborTicket> {
     let laborTicketResult: MMReceiveLaborTicket;
 
-    laborTicketResult = convertLaborTicketToLocalTimezone(
-      laborTicket,
-      getCachedTimezoneOffset()
-    );
+    // Convert MM's UTC timestamps into the ERP's local timezone before invoking connector code.
+    // Connector implementations should treat the incoming values as localized wall time and avoid
+    // applying any further timezone shifts.
+    laborTicketResult = convertLaborTicketToLocalTimezone(laborTicket);
 
     logger.info(
       `processing laborTicket, id=${laborTicket.laborTicketId}, ref=${laborTicket.laborTicketRef}`

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

@@ -29,7 +29,13 @@ import { ErrorProcessor } from "./error-processor.js";
  */
 export class MMEntityProcessor {
   /**
-   * Writes entities to MM API with deduplication and caching
+   * Writes entities to MM API with deduplication and caching.
+   *
+   * IMPORTANT: All datetime fields on `mmRecords` MUST already be expressed as
+   * ISO-8601 UTC strings (either trailing `Z` or an explicit offset). The SDK
+   * does not apply timezone conversion on this path. It forwards values directly
+   * to MachineMetrics and only reserializes them for validation. Connector code
+   * is responsible for converting local ERP times to UTC before invoking this API.
    */
   static async writeEntities(
     entityType: ERPObjType,

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

@@ -1,5 +1,6 @@
 import { ERPObjType } from "../../types/erp-types.js";
 import { IERPLaborTicketHandler } from "../../types/erp-connector.js";
+import type { FlattenedWorkOrderRow } from "../../types/flattened-work-order.js";
 import { BatchCacheManager } from "../../services/caching-service/batch-cache-manager.js";
 import {
   IToRESTApiObject,
@@ -248,7 +249,12 @@ export class StandardProcessDrivers {
    * parts, part operations, work orders, and work order operations, then process them in the correct order
    * to maintain referential integrity.
    *
-   * @param flattenedData Array of flattened rows containing both work order and operation data (camelCase fields)
+   * Timezone expectation: all datetime fields provided in `flattenedData` MUST already be expressed
+   * as ISO-8601 UTC strings (trailing `Z` or explicit offset). The SDK does not attempt to infer or
+   * convert local ERP timestamps on this path; it simply validates and forwards the values to MM.
+   * Connector implementations should convert ERP-local times to UTC before invoking this method.
+   *
+   * @param flattenedData Array of flattened rows containing both work order and operation data (see `FlattenedWorkOrderRow`)
    * @param batchCacheManager The batch cache manager instance; pass in null if caching is not desired
    *
    * @returns Combined results from all entity processing with detailed logging information
@@ -256,7 +262,7 @@ export class StandardProcessDrivers {
    * @throws Error on other underlying issues (network, authentication, etc.)
    */
   static async syncWorkOrderBatchFromFlattened(
-    flattenedData: any[],
+    flattenedData: ReadonlyArray<FlattenedWorkOrderRow>,
     batchCacheManager: BatchCacheManager | null
   ): Promise<{
     parts: WriteEntitiesToMMResult;
@@ -268,6 +274,11 @@ export class StandardProcessDrivers {
       throw new Error("No flattened work order data provided");
     }
 
+    const toStringOrFallback = (
+      value: string | number | null | undefined,
+      fallback = ""
+    ): string => (value === undefined || value === null ? fallback : String(value));
+
     // Process the flattened data - each row contains both work order and operation info
     const uniqueParts = new Map();
     const uniquePartOperations = new Map();
@@ -297,8 +308,8 @@ export class StandardProcessDrivers {
           resourceId: row.resourceId, // → resourceId
           cycleTimeMs: row.cycleTimeMs, // → cycleTimeMs
           setupTimeMs: row.setupTimeMs, // → setupTimeMs
-          description: row.operationDescription || "", // → description
-          quantityPerPart: row.quantityPerPart || 1, // → quantityPerPart
+          operationDescription: row.operationDescription, // → description
+          quantityPerPart: row.quantityPerPart ?? 1, // → quantityPerPart
         });
       }
 
@@ -351,8 +362,8 @@ export class StandardProcessDrivers {
     const parts = Array.from(uniqueParts.values()).map(
       (item) =>
         new MMSendPart(
-          item.partNumber || "", // partNumber
-          item.partRevision || "", // partRevision
+          toStringOrFallback(item.partNumber), // partNumber
+          toStringOrFallback(item.partRevision), // partRevision
           item.method || "Standard" // method
         )
     );
@@ -360,14 +371,14 @@ export class StandardProcessDrivers {
     const partOperations = Array.from(uniquePartOperations.values()).map(
       (item) =>
         new MMSendPartOperation(
-          item.partNumber || "", // partNumber
-          item.partRevision || "", // partRevision
+          toStringOrFallback(item.partNumber), // partNumber
+          toStringOrFallback(item.partRevision), // partRevision
           item.method || "Standard", // method
           item.sequenceNumber?.toString() || "", // sequenceNumber
           item.resourceId?.toString() || "", // resourceId
           item.cycleTimeMs || 0, // cycleTimeMs
           item.setupTimeMs || 0, // setupTimeMs
-          item.description || "", // description
+          item.operationDescription || "", // description
           item.quantityPerPart || 1 // quantityPerPart
         )
     );
@@ -376,10 +387,12 @@ export class StandardProcessDrivers {
       (item) =>
         new MMSendWorkOrder(
           item.workOrderId?.toString() || "", // workOrderId
-          item.lot || "", // lot
-          item.split || "", // split
-          item.sub || "", // sub
+          toStringOrFallback(item.lot), // lot
+          toStringOrFallback(item.split), // split
+          toStringOrFallback(item.sub), // sub
           item.status || "Open", // status
+          // Datetimes are assumed to already be UTC (or include an explicit offset).
+          // We reserialize via Date solely to validate the ISO format before sending to MM.
           item.dueDate ? new Date(item.dueDate).toISOString() : null, // dueDate
           item.description || "", // description
           item.scheduledStartDate
@@ -390,8 +403,8 @@ export class StandardProcessDrivers {
             : null, // scheduledEndDate
           item.closedDate ? new Date(item.closedDate).toISOString() : null, // closedDate
           item.quantityRequired || 0, // quantityRequired
-          item.partNumber || "", // partNumber
-          item.partRevision || "", // partRevision
+          toStringOrFallback(item.partNumber), // partNumber
+          toStringOrFallback(item.partRevision), // partRevision
           item.method || "Standard" // method
         )
     );
@@ -400,14 +413,15 @@ export class StandardProcessDrivers {
       (item) =>
         new MMSendWorkOrderOperation(
           item.workOrderId?.toString() || "", // workOrderId
-          item.lot || "", // lot
-          item.split || "", // split
-          item.sub || "", // sub
+          toStringOrFallback(item.lot), // lot
+          toStringOrFallback(item.split), // split
+          toStringOrFallback(item.sub), // sub
           item.sequenceNumber?.toString() || "", // sequenceNumber
           item.resourceId?.toString() || "", // resourceId
           item.startQuantity || 0, // startQuantity
           item.finishQuantity || 0, // finishQuantity
           item.expectedRejectRate || 0, // expectedRejectRate
+          // Same UTC expectation as above; reserialize to ensure valid ISO.
           item.scheduledStartDate
             ? new Date(item.scheduledStartDate).toISOString()
             : null, // scheduledStartDate
@@ -417,8 +431,8 @@ export class StandardProcessDrivers {
           item.closedDate ? new Date(item.closedDate).toISOString() : null, // closedDate
           item.cycleTimeMs || 0, // cycleTimeMs
           item.setupTimeMs || 0, // setupTimeMs
-          parseFloat(item.productionburdenRateHourly || "0"), // productionburdenRateHourly
-          parseFloat(item.setupburdenRatehourly || "0"), // setupburdenRatehourly
+          parseFloat(toStringOrFallback(item.productionburdenRateHourly, "0")), // productionburdenRateHourly
+          parseFloat(toStringOrFallback(item.setupburdenRatehourly, "0")), // setupburdenRatehourly
           item.operationType || "Production", // operationType
           item.quantityPerPart || 1, // quantityPerPart
           item.status || "Open" // status

package/src/utils/time-utils.ts

@@ -1,3 +1,4 @@
+import { DateTime } from 'luxon';
 import logger from "../services/reporting-service/logger.js";
 import {
   setTimezoneOffsetInCache,
@@ -117,6 +118,16 @@ export const getTimezoneOffsetAndPersist = async (
       const { offset, timezone } = await getTimezoneOffset();
       logger.info(`Timezone offset: ${offset} hours, timezone: ${timezone}`);
       setTimezoneOffsetInCache(offset);
+
+      const now = DateTime.now().setZone(timezone);
+      if (!now.isValid) {
+          throw new Error(
+              `Invalid timezone name from Company properties: "${timezone}". ` +
+              `Must be a valid IANA timezone name (e.g., "America/Chicago"). ` +
+              `See: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones`
+          );
+      }
+      
       setTimezoneNameInCache(timezone);
       success = true;
     } catch (error) {