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

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

@@ -1,14 +1,17 @@
-import { IERPLaborTicketHandler } from "../../types/erp-connector";
-import { MMApiClient } from "../../services/mm-api-service/mm-api-service";
-import { MMReceiveLaborTicket } from "../../services/mm-api-service/types/receive-types";
-import { convertLaborTicketToLocalTimezone } from "../mm-labor-ticket-helpers";
-import { getCachedTimezoneOffset } from "../local-data-store/jobs-shared-data";
-import logger from "../../services/reporting-service/logger";
+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 logger from "../../services/reporting-service/logger.js";
 
 /**
  * Handles synchronization of labor tickets between MachineMetrics and ERP systems
  */
 export class LaborTicketERPSynchronizer {
+  // Small allowance to mitigate tiny clock offsets / timestamp granularity differences
+  // between the connector host and MM's timestamps.
+  private static readonly CHECKPOINT_SKEW_MS = 2_000;
+
   /**
    * Synchronizes updated labor tickets from MachineMetrics to an ERP system
    */
@@ -18,9 +21,9 @@ export class LaborTicketERPSynchronizer {
   ): Promise<void> {
     try {
       const mmApiClient = new MMApiClient();
-      const failedLaborTicketRefs: string[] = [];
+      const failedLaborTicketRefs = new Set<string>();
+      const attemptedSignatures = new Set<string>();
 
-      // Initialize and fetch checkpoint (quick operations, don't need prolonged lock)
       await mmApiClient.initializeCheckpoint({
         system: connectorType,
         table: "labor_tickets",
@@ -30,95 +33,168 @@ export class LaborTicketERPSynchronizer {
         },
       });
 
-      const fallbackTimestamp = new Date().toISOString();
-      const laborTicketsUpdates = await mmApiClient.fetchLaborTicketUpdates({
-        system: connectorType,
-        checkpointType: "export",
-      });
+      /**
+       * We cannot safely checkpoint to "now" without draining, because updates can arrive mid-run.
+       * And we cannot checkpoint to "most recent updatedAt from the initial fetch" because we
+       * update MM (setting laborTicketId on creates), which bumps updatedAt and causes the same
+       * ticket to be re-pulled next cycle.
+       *
+       * We also cannot dedupe only by laborTicketRef, because the same ticket can legitimately
+       * change multiple times within a single run (parts counts, times, reasons, state, etc.).
+       * And we cannot dedupe by (laborTicketRef, updatedAt) because updatedAt is exactly what our
+       * own MM write-back (setting laborTicketId) mutates, creating a false "new version".
+       *
+       * Remedy: drain the window up to a moving barrier time (local "now"), re-fetching until MM
+       * reports no additional unattempted tickets in that window, and dedupe within the run by a
+       * stable business signature (operational fields only; excludes metadata like updatedAt and
+       * excludes SDK-mutated fields like laborTicketId). Then checkpoint to a value that is not
+       * meaningfully ahead of MM's own timestamps (small skew clamp).
+       */
+      const maxPasses = 10;
+      let pass = 0;
+      let barrierTime = new Date().toISOString();
+      let maxMmTimestampWithinBarrier: string | null = null;
 
-      if (laborTicketsUpdates.length === 0) {
-        logger.info("syncLaborTicketsToERP:No updated labor tickets found");
-        return;
-      }
+      while (pass < maxPasses) {
+        pass += 1;
+        barrierTime = new Date().toISOString();
 
-      logger.info(
-        `ToERP: Found ${laborTicketsUpdates.length} Labor Ticket Ids and Refs to process`,
-        {
-          laborTickets: laborTicketsUpdates.map(
-            (ticket: MMReceiveLaborTicket) => ({
-              ref: ticket.laborTicketRef,
-              id: ticket.laborTicketId,
-            })
-          ),
+        const laborTicketsUpdates = await mmApiClient.fetchLaborTicketUpdates({
+          system: connectorType,
+          checkpointType: "export",
+        });
+
+        if (laborTicketsUpdates.length === 0) {
+          if (pass === 1) {
+            logger.info("syncLaborTicketsToERP:No updated labor tickets found");
+          }
+          break;
         }
-      );
 
-      // 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.
-      const mostRecentUpdate = laborTicketsUpdates.reduce(
-        (latest: string | null, ticket: MMReceiveLaborTicket) => {
-          if (!latest || !ticket.updatedAt) return latest;
-          return new Date(ticket.updatedAt) > new Date(latest)
-            ? ticket.updatedAt
-            : latest;
-        },
-        null as string | null
-      );
+        // Track the latest MM timestamp we see that is <= the current barrier.
+        for (const ticket of laborTicketsUpdates) {
+          const ts = this.getComparableTicketTimestamp(ticket);
+          if (!ts) continue;
+          if (new Date(ts) > new Date(barrierTime)) continue;
+          if (
+            !maxMmTimestampWithinBarrier ||
+            new Date(ts) > new Date(maxMmTimestampWithinBarrier)
+          ) {
+            maxMmTimestampWithinBarrier = ts;
+          }
+        }
 
-      await Promise.all(
-        laborTicketsUpdates.map(async (laborTicket: MMReceiveLaborTicket) => {
-          if (!laborTicket.laborTicketRef) {
+        if (pass === 1) {
+          logger.info(
+            `ToERP: Found ${laborTicketsUpdates.length} Labor Ticket Ids and Refs to process`,
+            {
+              laborTickets: laborTicketsUpdates.map(
+                (ticket: MMReceiveLaborTicket) => ({
+                  ref: ticket.laborTicketRef,
+                  id: ticket.laborTicketId,
+                })
+              ),
+            }
+          );
+        }
+
+        // Build a unique pending list by a stable "business signature", and only consider tickets
+        // whose timestamps are <= the barrierTime (prevents checkpoint gaps if clocks differ).
+        const pending: Array<{ sig: string; ticket: MMReceiveLaborTicket }> = [];
+        const dedupeWithinFetch = new Set<string>();
+
+        for (const ticket of laborTicketsUpdates) {
+          if (!ticket.laborTicketRef) {
             logger.error(
               "syncLaborTicketsToERP: laborTicketRef is not set for laborTicket pulled from MM:",
-              { laborTicket }
+              { laborTicket: ticket }
             );
-            return undefined;
+            continue;
           }
 
-          try {
-            return await this.processLaborTicket(
-              connector,
-              mmApiClient,
-              laborTicket
-            );
-          } catch (error) {
-            failedLaborTicketRefs.push(laborTicket.laborTicketRef);
-            logger.error(
-              `syncLaborTicketsToERP: Error processing laborTicketRef ${laborTicket.laborTicketRef}:`,
-              { error }
-            );
-            return undefined;
+          const ts = this.getComparableTicketTimestamp(ticket);
+          if (ts && new Date(ts) > new Date(barrierTime)) {
+            // Defer "future" tickets (relative to local wall clock) to a later run/pass.
+            continue;
           }
-        })
-      );
+
+          const sig = this.laborTicketBusinessSignature(ticket);
+          if (attemptedSignatures.has(sig) || dedupeWithinFetch.has(sig)) continue;
+          dedupeWithinFetch.add(sig);
+          pending.push({ sig, ticket });
+        }
+
+        if (pending.length === 0) {
+          // Nothing new to do in this barrier window; safe to checkpoint and exit.
+          break;
+        }
+
+        logger.info(
+          `syncLaborTicketsToERP: pass=${pass}/${maxPasses}, barrier=${barrierTime}, pending=${pending.length}`
+        );
+
+        await Promise.all(
+          pending.map(async ({ sig, ticket }) => {
+            // Mark attempted up-front so we don't re-attempt within this run even if MM reorders.
+            attemptedSignatures.add(sig);
+
+            try {
+              return await this.processLaborTicket(connector, mmApiClient, ticket);
+            } catch (error) {
+              failedLaborTicketRefs.add(ticket.laborTicketRef);
+              logger.error(
+                `syncLaborTicketsToERP: Error processing laborTicketRef ${ticket.laborTicketRef}:`,
+                { error }
+              );
+              return undefined;
+            }
+          })
+        );
+      }
+
+      if (pass >= maxPasses) {
+        logger.warn(
+          `syncLaborTicketsToERP: Reached max passes (${maxPasses}). Checkpointing anyway to avoid infinite loops.`
+        );
+      }
 
       logger.info(
-        `syncLaborTicketsToERP: ${failedLaborTicketRefs.length} failed labor ticket ids`
+        `syncLaborTicketsToERP: ${failedLaborTicketRefs.size} failed labor ticket ids`
       );
-      if (failedLaborTicketRefs.length > 0) {
+      if (failedLaborTicketRefs.size > 0) {
+        const failedTicketRefs = Array.from(failedLaborTicketRefs);
         logger.info(
-          `syncLaborTicketsToERP: Reporting ${failedLaborTicketRefs.length} labor ticket failures:`,
+          `syncLaborTicketsToERP: Reporting ${failedTicketRefs.length} labor ticket failures:`,
           {
-            failedLaborTicketRefs,
+            failedLaborTicketRefs: failedTicketRefs,
           }
         );
         const addFailedResult = await mmApiClient.addFailedLaborTicketRefs(
           connectorType,
-          failedLaborTicketRefs
+          failedTicketRefs
         );
         logger.info("syncLaborTicketsToERP: addFailedResult:", {
           addFailedResult,
         });
       }
 
-      mmApiClient.saveCheckpoint({
+      const checkpointTimestamp = this.computeCheckpointTimestamp({
+        barrierTime,
+        maxMmTimestampWithinBarrier,
+        skewMs: this.CHECKPOINT_SKEW_MS,
+      });
+
+      await mmApiClient.saveCheckpoint({
         system: connectorType,
         table: "labor_tickets",
         checkpointType: "export",
         checkpointValue: {
-          timestamp: mostRecentUpdate || fallbackTimestamp,
+          timestamp: checkpointTimestamp,
         },
       });
+      logger.info("syncLaborTicketsToERP: Checkpoint saved:", {
+        checkpointTimestamp,
+      });
     } catch (error) {
       logger.error("syncLaborTicketsToERP: Error:", error);
     }
@@ -215,10 +291,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}`
@@ -258,4 +334,84 @@ export class LaborTicketERPSynchronizer {
 
     return laborTicketResult;
   }
+
+  /**
+   * A stable identity for "did the business-relevant contents of this labor ticket change?"
+   *
+   * IMPORTANT: Excludes fields that the SDK itself mutates (e.g. laborTicketId, updatedAt),
+   * otherwise we'd reprocess the write-back bump on the next cycle.
+   */
+  private static laborTicketBusinessSignature(ticket: MMReceiveLaborTicket): string {
+    const reasons = (ticket.reasons ?? [])
+      .map((r) => {
+        const reason: any = (r as any)?.reason ?? {};
+        return (
+          reason.reasonId ??
+          reason.code ??
+          reason.reasonRef ??
+          reason.rejectReasonRef ??
+          ""
+        );
+      })
+      .filter((v) => v !== "" && v !== null && v !== undefined)
+      .map(String)
+      .sort();
+
+    const signatureObject = {
+      laborTicketRef: ticket.laborTicketRef ?? null,
+      clockIn: ticket.clockIn ?? null,
+      clockOut: ticket.clockOut ?? null,
+      goodParts: ticket.goodParts ?? null,
+      badParts: ticket.badParts ?? null,
+      state: ticket.state ?? null,
+      type: ticket.type ?? null,
+      transactionDate: ticket.transactionDate ?? null,
+      workOrderId: ticket.workOrderId ?? null,
+      sequenceNumber: ticket.sequenceNumber ?? null,
+      personId: ticket.personId ?? null,
+      resourceId: ticket.resourceId ?? null,
+      lot: ticket.lot ?? null,
+      split: ticket.split ?? null,
+      sub: ticket.sub ?? null,
+      comment: ticket.comment ?? null,
+      workOrderOperationClosedDate: ticket.workOrderOperationClosedDate ?? null,
+      reasons,
+    };
+
+    return JSON.stringify(signatureObject);
+  }
+
+  /**
+   * Selects a comparable timestamp for windowing decisions.
+   * Prefer updatedAt; fall back to other stable timestamps if needed.
+   */
+  private static getComparableTicketTimestamp(
+    ticket: MMReceiveLaborTicket
+  ): string | null {
+    return (
+      ticket.updatedAt ??
+      ticket.createdAt ??
+      ticket.transactionDate ??
+      ticket.clockOut ??
+      ticket.clockIn ??
+      null
+    );
+  }
+
+  private static addMsToIso(iso: string, ms: number): string {
+    return new Date(new Date(iso).getTime() + ms).toISOString();
+  }
+
+  private static computeCheckpointTimestamp(options: {
+    barrierTime: string;
+    maxMmTimestampWithinBarrier: string | null;
+    skewMs: number;
+  }): string {
+    const { barrierTime, maxMmTimestampWithinBarrier, skewMs } = options;
+
+    if (!maxMmTimestampWithinBarrier) return barrierTime;
+
+    const mmPlusSkew = this.addMsToIso(maxMmTimestampWithinBarrier, skewMs);
+    return new Date(mmPlusSkew) < new Date(barrierTime) ? mmPlusSkew : barrierTime;
+  }
 }

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

@@ -1,5 +1,5 @@
-import { ERPObjType } from "../../types/erp-types";
-import { BatchCacheManager } from "../../services/caching-service/batch-cache-manager";
+import { ERPObjType } from "../../types/erp-types.js";
+import { BatchCacheManager } from "../../services/caching-service/batch-cache-manager.js";
 import {
   IToRESTApiObject,
   MMSendPerson,
@@ -15,21 +15,27 @@ import {
   MM200LaborTicketResponse,
   MM207NonLaborTicketResponse,
   MM207LaborTicketResponse,
-} from "../../services/mm-api-service";
-import { MMApiClient } from "../../services/mm-api-service/mm-api-service";
-import { HTTPError } from "../http-client";
+} from "../../services/mm-api-service/index.js";
+import { MMApiClient } from "../../services/mm-api-service/mm-api-service.js";
+import { HTTPError } from "../http-client.js";
 import {
   WriteEntitiesToMMResult,
   MMBatchValidationError,
-} from "./standard-process-drivers";
-import { ErrorProcessor } from "./error-processor";
+} from "./standard-process-drivers.js";
+import { ErrorProcessor } from "./error-processor.js";
 
 /**
  * Handles processing of entities to the MachineMetrics API
  */
 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,6 +1,7 @@
-import { ERPObjType } from "../../types/erp-types";
-import { IERPLaborTicketHandler } from "../../types/erp-connector";
-import { BatchCacheManager } from "../../services/caching-service/batch-cache-manager";
+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,
   MMSendWorkOrderBatch,
@@ -8,9 +9,9 @@ import {
   MMSendPartOperation,
   MMSendWorkOrder,
   MMSendWorkOrderOperation,
-} from "../../services/mm-api-service";
-import { LaborTicketERPSynchronizer } from "./labor-ticket-erp-synchronizer";
-import { MMEntityProcessor } from "./mm-entity-processor";
+} from "../../services/mm-api-service/index.js";
+import { LaborTicketERPSynchronizer } from "./labor-ticket-erp-synchronizer.js";
+import { MMEntityProcessor } from "./mm-entity-processor.js";
 
 /**
  * The result of writing entities to the MachineMetrics API on complete success.
@@ -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,13 +1,14 @@
-import logger from "../services/reporting-service/logger";
+import { DateTime } from 'luxon';
+import logger from "../services/reporting-service/logger.js";
 import {
   setTimezoneOffsetInCache,
   setTimezoneNameInCache,
-} from "./local-data-store/jobs-shared-data";
+} from "./local-data-store/jobs-shared-data.js";
 import {
   convertToLocalTime,
   formatDateWithTZOffset,
   getTimezoneOffset,
-} from "./timezone";
+} from "./timezone.js";
 
 /**
  * Calculates the difference in hours between two timestamps
@@ -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) {

package/src/utils/timezone.ts

@@ -1,5 +1,5 @@
-import { CoreConfiguration } from "../services/data-sync-service/configuration-manager";
-import { HTTPClientFactory } from "./http-client";
+import { CoreConfiguration } from "../services/data-sync-service/configuration-manager.js";
+import { HTTPClientFactory } from "./http-client.js";
 
 /**
  * Gets the timezone offset in hours and timezone name for the company's timezone