@machinemetrics/mm-erp-sdk 0.1.8-beta.9 → 0.1.8

package/src/services/mm-api-service/mm-api-service.ts

@@ -1,5 +1,5 @@
 import logger from "../reporting-service/logger";
-import { ERPObjType, ERPType } from "../../types/erp-types";
+import { ERPObjType } from "../../types/erp-types";
 import { MMReceiveLaborTicket } from "./types/receive-types";
 import { MMTokenManager } from "./token-mgr";
 import * as MM_SEND_TYPES from "./types/send-types";
@@ -624,7 +624,7 @@ export class MMApiClient {
    * @returns The response from the MM API
    */
   async addFailedLaborTicketRefs(
-    system: ERPType,
+    system: string,
     failedTicketRefs: string[]
   ): Promise<MMApiBaseResponse> {
     return await this.postData(
@@ -635,7 +635,7 @@ export class MMApiClient {
   }
 
   async fetchFailedLaborTickets(
-    system: ERPType
+    system: string
   ): Promise<MMReceiveLaborTicket[]> {
     const failedTickets = (await this.getData(
       `${this.resourceURLs[ERPObjType.LABOR_TICKETS]}/failed`,
@@ -675,7 +675,7 @@ export class MMApiClient {
   }
 
   async deleteFailedLaborTicketIds(
-    system: ERPType,
+    system: string,
     laborTicketRefs: string[]
   ): Promise<MMApiBaseResponse> {
     return await this.postData(

package/src/services/mm-api-service/types/checkpoint.ts

@@ -1,10 +1,8 @@
-import { ERPType } from "../../../types/erp-types";
-
 /**
  * Represents a checkpoint for a specific system, table, and checkpoint type
  */
 export type Checkpoint = {
-  system: ERPType;
+  system: string;
   table: string;
   checkpointType: "import" | "export";
   checkpointValue?: {

package/src/services/psql-erp-service/configuration.ts

@@ -0,0 +1,7 @@
+export interface PsqlConfiguration {
+  host: string;
+  port: string;
+  database: string;
+  username: string;
+  password: string;
+}

package/src/services/psql-erp-service/index.ts

@@ -0,0 +1,22 @@
+import { PsqlService } from "./psql-service";
+
+/**
+ * A class to manage interactions with PSQL (Pervasive) databases via ODBC
+ */
+export { PsqlService };
+
+/**
+ * Configuration interface for PSQL connections
+ */
+export type { PsqlConfiguration } from "./configuration";
+
+/**
+ * Helper functions for PSQL data formatting
+ */
+export {
+  formatPsqlDate,
+  formatPsqlTime,
+  combinePsqlDateTime,
+  isPsqlDateEmpty,
+  cleanPsqlCharField,
+} from "./psql-helpers";

package/src/services/psql-erp-service/internal/types/psql-types.ts

@@ -0,0 +1,13 @@
+/**
+ * PSQL-specific type definitions
+ */
+
+export interface OdbcError {
+  state: string;
+  message: string;
+  code?: number;
+}
+
+export interface OdbcErrorResponse extends Error {
+  odbcErrors?: OdbcError[];
+}

package/src/services/psql-erp-service/psql-helpers.ts

@@ -0,0 +1,114 @@
+/**
+ * Helper functions for PSQL/Pervasive database operations
+ */
+
+/**
+ * Formats a date from PSQL YYMMDD format to ISO date string
+ * @param psqlDate Date in YYMMDD format (e.g., "250105" for Jan 5, 2025)
+ * @returns ISO date string (e.g., "2025-01-05") or null if invalid
+ */
+export function formatPsqlDate(psqlDate: string): string | null {
+  if (!psqlDate || psqlDate.trim().length !== 6 || psqlDate === "000000") {  
+    return null;  
+  } 
+
+  try {
+    const year = parseInt(psqlDate.substring(0, 2), 10);
+    const month = parseInt(psqlDate.substring(2, 4), 10);
+    const day = parseInt(psqlDate.substring(4, 6), 10);
+
+    // Convert 2-digit year to 4-digit (assuming 2000s)
+    const fullYear = year + 2000;
+
+    // Basic validation
+    if (month < 1 || month > 12 || day < 1 || day > 31) {
+      return null;
+    }
+
+    const date = new Date(fullYear, month - 1, day);
+    // Validate that the constructed date matches the input values
+    if (
+      date.getFullYear() !== fullYear ||
+      date.getMonth() !== (month - 1) ||
+      date.getDate() !== day
+    ) {
+      return null;
+    }
+    return date.toISOString().split("T")[0];
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Formats a time from PSQL HHMM format to HH:MM:SS
+ * @param psqlTime Time in HHMM format (e.g., "1430" for 2:30 PM)
+ * @returns Time string in HH:MM:SS format or null if invalid
+ */
+export function formatPsqlTime(psqlTime: string): string | null {
+  if (!psqlTime) {
+    return null;
+  }
+  const trimmed = psqlTime.trim();
+  if (trimmed.length !== 4) {
+    return null;
+  }
+  try {
+    const hours = parseInt(trimmed.substring(0, 2), 10);
+    const minutes = parseInt(trimmed.substring(2, 4), 10);
+    if (
+      isNaN(hours) ||
+      isNaN(minutes) ||
+      hours < 0 ||
+      hours > 23 ||
+      minutes < 0 ||
+      minutes > 59
+    ) {
+      return null;
+    }
+    // Pad hours and minutes to 2 digits
+    const hoursStr = hours.toString().padStart(2, "0");
+    const minutesStr = minutes.toString().padStart(2, "0");
+    return `${hoursStr}:${minutesStr}:00`;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Combines PSQL date and time into ISO datetime string
+ * @param psqlDate Date in YYMMDD format
+ * @param psqlTime Time in HHMM format
+ * @returns ISO datetime string or null if invalid
+ */
+export function combinePsqlDateTime(
+  psqlDate: string,
+  psqlTime: string
+): string | null {
+  const date = formatPsqlDate(psqlDate);
+  const time = formatPsqlTime(psqlTime);
+
+  if (!date || !time) {
+    return null;
+  }
+
+  return `${date}T${time}`;
+}
+
+/**
+ * Helper to check if a PSQL date is "empty" (000000 or blank)
+ */
+export function isPsqlDateEmpty(psqlDate: string): boolean {
+  return !psqlDate || psqlDate === "000000" || psqlDate.trim() === "";
+}
+
+/**
+ * Clean and trim PSQL CHAR field (removes trailing spaces)
+ * PSQL CHAR fields are fixed-width and padded with spaces
+ */
+export function cleanPsqlCharField(value: string | null | undefined): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+  return String(value).trim();
+}

package/src/services/psql-erp-service/psql-service.ts

@@ -0,0 +1,247 @@
+import { PsqlConfiguration } from "./configuration";
+import { ERPResponse } from "../../types/erp-types";
+import { OdbcErrorResponse } from "./internal/types/psql-types";
+import logger from "../reporting-service/logger";
+
+type PagingParams = {
+  limit?: number;
+  offset?: number;
+};
+
+/**
+ * ODBC connection interface for type safety
+ */
+interface OdbcConnection {
+  query(sql: string): Promise<any[]>;
+  close(): Promise<void>;
+}
+
+/**
+ * ODBC module interface
+ */
+interface OdbcModule {
+  connect(connectionString: string): Promise<OdbcConnection>;
+}
+
+export class PsqlService {
+  private config: PsqlConfiguration;
+  private static odbcModule: OdbcModule | null = null;
+  private static odbcLoadError: Error | null = null;
+
+  constructor(config: PsqlConfiguration) {
+    this.config = config;
+  }
+
+  /**
+   * Dynamically load the ODBC module with lazy initialization and caching
+   * @throws Error with helpful message if ODBC package is not installed
+   */
+  private static async getOdbc(): Promise<OdbcModule> {
+    // If we've already tried and failed, throw the cached error
+    if (this.odbcLoadError) {
+      throw this.odbcLoadError;
+    }
+
+    // If already loaded, return cached module
+    if (this.odbcModule) {
+      return this.odbcModule;
+    }
+
+    try {
+      // Dynamic import - only loads when actually needed
+      // @ts-ignore - odbc is an optional dependency, may not be installed at build time
+      const odbcImport = await import("odbc");
+      // Handle both default export and named export patterns
+      const odbc = odbcImport.default || odbcImport;
+      this.odbcModule = odbc as OdbcModule;
+      return this.odbcModule;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.odbcLoadError = new Error(
+        `ODBC package is required for PSQL service but is not installed or failed to load.\n` +
+        `Install it with: npm install odbc\n` +
+        `Also install OS-level dependencies, e.g. on Alpine Linux:\n` +
+        `  apk add --no-cache unixodbc unixodbc-dev python3 make g++\n` +
+        `For other Linux distributions, install unixodbc and unixodbc-dev packages.\n` +
+        `Original error: ${errorMessage}`
+      );
+      throw this.odbcLoadError;
+    }
+  }
+
+  // REMOVED: dispose() method - not needed anymore
+  // REMOVED: connection property - not needed anymore
+  // REMOVED: openConnection() method - not needed anymore
+  // REMOVED: closeConnection() method - not needed anymore
+
+  /**
+   * Build PSQL ODBC connection string
+   * CRITICAL: ServerName must use IP.PORT format (e.g., 10.4.0.11.1583)
+   */
+  private buildConnectionString(): string {
+    const serverName = `${this.config.host}.${this.config.port}`;
+
+    return (
+      [
+        "Driver={Pervasive ODBC Interface}",
+        `ServerName=${serverName}`,
+        `DBQ=${this.config.database}`,
+        `UID=${this.config.username}`,
+        `PWD=${this.config.password}`,
+        "AutoDoubleQuote=0",
+      ].join(";") + ";"
+    );
+  }
+
+  /**
+   * Execute a query and return the results
+   * Creates a fresh connection for each query to avoid handle corruption
+   *
+   * SECURITY WARNING: This method executes the provided SQL string as-is.
+   * - Parameter binding is NOT implemented; the `params` argument is currently ignored.
+   * - Never concatenate untrusted/user-supplied input into `query`.
+   * - Doing so can result in SQL injection vulnerabilities and data exposure.
+   * If dynamic values are required, ensure they are strictly validated/escaped
+   * or implement proper parameterized execution before accepting untrusted input.
+   *
+   * @param query The SQL query to execute
+   * @param params Query parameters (currently unused for PSQL read operations)
+   * @param paging Optional paging parameters
+   * @returns The entities fetched from the database, along with paging information
+   */
+  public async executePreparedStatement(
+    query: string,
+    params: Record<string, string> = {},
+    paging?: PagingParams
+  ): Promise<ERPResponse | undefined> {
+    // Dynamically load ODBC module (will throw helpful error if not installed)
+    const odbc = await PsqlService.getOdbc();
+    let connection: OdbcConnection | null = null;
+
+    try {
+      // Create fresh connection for THIS query only
+      const connStr = this.buildConnectionString();
+      logger.debug("Creating fresh PSQL connection for query");
+      connection = await odbc.connect(connStr);
+
+      if (Object.keys(params).length > 0) {
+        logger.warn(
+          "PsqlService: Query parameters provided but parameter binding not yet implemented. " +
+            "Using direct query execution."
+        );
+      }
+
+      const records = await connection.query(query);
+      const allRecords = PsqlService.recordsetToRecords(records);
+      const rowsFetched = allRecords.length;
+
+      // Apply paging if requested
+      const pagedData =
+        paging?.offset !== undefined || paging?.limit !== undefined
+          ? allRecords.slice(
+              paging.offset || 0,
+              (paging.offset || 0) + (paging.limit || allRecords.length)
+            )
+          : allRecords;
+
+      return {
+        data: pagedData,
+        paging: {
+          count: rowsFetched,
+          limit: paging?.limit || 0,
+          offset: paging?.offset || 0,
+          nextPage:
+            paging?.limit && (paging.offset || 0) + paging.limit < rowsFetched
+              ? String((paging.offset || 0) + paging.limit)
+              : undefined,
+          previousPage: paging?.offset
+            ? String(Math.max(0, (paging.offset || 0) - (paging.limit || 10)))
+            : undefined,
+        },
+      };
+    } catch (error) {
+      // If this is an ODBC load error (from getOdbc), re-throw it as-is
+      // since it already has a helpful error message
+      if (error instanceof Error && error.message.includes("ODBC package is required")) {
+        throw error;
+      }
+
+      // Otherwise, handle as ODBC runtime error
+      const errorInfo = error as OdbcErrorResponse;
+      logger.error("Error fetching data from PSQL", {
+        error: errorInfo.message,
+        odbcErrors: errorInfo.odbcErrors,
+        query: query.substring(0, 200), // Log first 200 chars of query
+      });
+
+      throw this.handleOdbcError(errorInfo);
+    } finally {
+      // CRITICAL: Always close connection, even on error
+      if (connection) {
+        try {
+          await connection.close();
+          logger.debug("PSQL connection closed successfully");
+        } catch (err) {
+          // Don't throw on close errors, just log
+          logger.warn("Error closing PSQL connection (non-fatal)", {
+            error: err,
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Transform ODBC result set to array of Record<string, string> instances.
+   * IMPORTANT: PSQL CHAR fields are often padded with spaces - we trim them
+   */
+  public static recordsetToRecords(recordset: any[]): Record<string, string>[] {
+    if (!Array.isArray(recordset)) {
+      return [];
+    }
+
+    const data: Record<string, string>[] = recordset.map((row) => {
+      const transformedRow: Record<string, string> = {};
+      Object.keys(row).forEach((key) => {
+        const value = row[key];
+        transformedRow[key] =
+          value !== null && value !== undefined ? String(value).trim() : "";
+      });
+      return transformedRow;
+    });
+
+    return data;
+  }
+
+  /**
+   * Handle ODBC errors and provide meaningful messages
+   */
+  private handleOdbcError(error: OdbcErrorResponse): Error {
+    const odbcError = error.odbcErrors?.[0];
+    const errorCode = odbcError?.state;
+    const message = odbcError?.message || error.message;
+
+    switch (errorCode) {
+      case "08S01":
+        return new Error(
+          "PSQL connection failed. Check: " +
+            "1) PVSW environment variable set to /usr/local/psql/etc/pvsw.ini, " +
+            "2) Network connectivity to ports 1583/3351, " +
+            "3) ODBC configuration files in /usr/local/psql/etc/ and /etc/. " +
+            `Original error: ${message}`
+        );
+      case "28000":
+        return new Error(
+          `PSQL authentication failed. Check username/password. Original error: ${message}`
+        );
+      case "42000":
+        return new Error(`PSQL SQL syntax error. Original error: ${message}`);
+      case "42S02":
+        return new Error(
+          `PSQL table or view not found. Check table names in query. Original error: ${message}`
+        );
+      default:
+        return new Error(`PSQL error (${errorCode || "unknown"}): ${message}`);
+    }
+  }
+}

package/src/types/erp-connector.ts

@@ -1,5 +1,4 @@
 import { MMReceiveLaborTicket } from "../services/mm-api-service/types/receive-types";
-import { ERPType } from "./erp-types";
 
 /**
  * Interface for ERP connectors.
@@ -7,7 +6,11 @@ import { ERPType } from "./erp-types";
  * Required for any connector.
  */
 export interface IERPConnector {
-  readonly type: ERPType;
+
+  /**
+   * The type of ERP system this connector is for.
+   */
+  readonly type: string;
 
   /**
    * Sync data from the ERP system to MM.

package/src/types/erp-types.ts

@@ -1,14 +1,3 @@
-// TO DO: This will change once the SDK is refactored into its own repo
-export enum ERPType {
-  INVALID = "INVALID",
-  D365 = "D365",
-  JOB_BOSS = "JOB_BOSS",
-  PROFITKEY = "PROFITKEY",
-  PROSHOP = "PROSHOP",
-  SYTELINE = "SYTELINE",
-  TEMPLATE = "TEMPLATE",
-}
-
 export enum ERPObjType {
   RESOURCES,
   PARTS,

package/src/types/index.ts

@@ -5,7 +5,6 @@
 
 export type { IERPConnector } from "./erp-connector";
 export type {
-  ERPType,
   ERPObjType,
   ERPPagination,
   ERPResponse,

package/src/utils/application-initializer.ts

@@ -21,7 +21,7 @@ export class ApplicationInitializer {
 
       // Load and validate core configuration
       const coreConfig = CoreConfiguration.inst();
-      logger.info("Core Configuration loaded:", coreConfig);
+      logger.info("Core Configuration loaded:", coreConfig.toSafeLogObject());
 
       // Perform database startup checks
       logger.info("Performing database startup checks...");

package/src/utils/index.ts

@@ -33,7 +33,10 @@ export { BatchCacheManager } from "../services/caching-service/batch-cache-manag
 export { StandardProcessDrivers } from "./standard-process-drivers/";
 export type { WriteEntitiesToMMResult } from "./standard-process-drivers/";
 export { MMBatchValidationError } from "./standard-process-drivers/";
-export { getCachedTimezoneOffset } from "./local-data-store/jobs-shared-data";
+export {
+  getCachedTimezoneOffset,
+  getCachedTimezoneName,
+} from "./local-data-store/jobs-shared-data";
 
 // Local data store
 export {

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

@@ -71,13 +71,17 @@ export const setInitialLoadComplete = (complete: boolean): void => {
   writeStorage(data);
 };
 
+/**
+ * Gets the company's cached current timezone offset (e.g., -5)
+ * @returns The cached timezone offset or 0 if not found
+ */
 export const getCachedTimezoneOffset = (): number => {
   const data = readStorage();
   return (data.timezoneOffset as number) ?? 0;
 };
 
 /**
- * Sets the timezone offset in the cache
+ * Sets the company's current timezone offset in the cache
  * @param offset The timezone offset in hours
  */
 export const setTimezoneOffsetInCache = (offset: number): void => {
@@ -86,6 +90,25 @@ export const setTimezoneOffsetInCache = (offset: number): void => {
   writeStorage(data);
 };
 
+/**
+ * Gets the cached timezone name (e.g., "America/New_York")
+ * @returns The cached timezone name or null if not found
+ */
+export const getCachedTimezoneName = (): string | null => {
+  const data = readStorage();
+  return (data.timezoneName as string) ?? null;
+};
+
+/**
+ * Sets the timezone name in the cache
+ * @param timezone The timezone name (e.g., "America/New_York")
+ */
+export const setTimezoneNameInCache = (timezone: string): void => {
+  const data = readStorage();
+  data.timezoneName = timezone;
+  writeStorage(data);
+};
+
 interface CachedToken {
   token: string;
   expiration: number | null;

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

@@ -1,4 +1,3 @@
-import { ERPType } from "../../types/erp-types";
 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";
@@ -14,7 +13,7 @@ export class LaborTicketERPSynchronizer {
    * Synchronizes updated labor tickets from MachineMetrics to an ERP system
    */
   static async syncToERP(
-    connectorType: ERPType,
+    connectorType: string,
     connector: IERPLaborTicketHandler
   ): Promise<void> {
     try {
@@ -128,7 +127,7 @@ export class LaborTicketERPSynchronizer {
    * Retries labor tickets that have failed to be created or updated in the ERP during the sync
    */
   static async retryFailed(
-    connectorType: ERPType,
+    connectorType: string,
     connector: IERPLaborTicketHandler
   ): Promise<void> {
     try {

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

@@ -1,4 +1,4 @@
-import { ERPType, ERPObjType } from "../../types/erp-types";
+import { ERPObjType } from "../../types/erp-types";
 import { IERPLaborTicketHandler } from "../../types/erp-connector";
 import { BatchCacheManager } from "../../services/caching-service/batch-cache-manager";
 import {
@@ -72,7 +72,7 @@ export class StandardProcessDrivers {
    * and saves the checkpoint
    */
   static async syncLaborTicketsToERP(
-    connectorType: ERPType,
+    connectorType: string,
     connector: IERPLaborTicketHandler
   ): Promise<void> {
     return LaborTicketERPSynchronizer.syncToERP(connectorType, connector);
@@ -86,7 +86,7 @@ export class StandardProcessDrivers {
    * which are then deleted from the list of failed labor ticket ids.
    */
   static async retryFailedLaborTickets(
-    connectorType: ERPType,
+    connectorType: string,
     connector: IERPLaborTicketHandler
   ): Promise<void> {
     return LaborTicketERPSynchronizer.retryFailed(connectorType, connector);

package/src/utils/time-utils.ts

@@ -1,5 +1,8 @@
 import logger from "../services/reporting-service/logger";
-import { setTimezoneOffsetInCache } from "./local-data-store/jobs-shared-data";
+import {
+  setTimezoneOffsetInCache,
+  setTimezoneNameInCache,
+} from "./local-data-store/jobs-shared-data";
 import {
   convertToLocalTime,
   formatDateWithTZOffset,
@@ -91,8 +94,9 @@ interface TimezoneOffsetParams {
 }
 
 /**
- * Gets the timezone offset for the company and sets it in the cache
+ * Gets the timezone offset and timezone name for the company and sets them in the cache
  * The cached offset can be acquired from getCachedTimezoneOffset() in "./local-data-store/jobs-shared-data"
+ * The cached timezone name can be acquired from getCachedTimezoneName() in "./local-data-store/jobs-shared-data"
  *
  * @param params.maxRetries Maximum number of retry attempts
  * @param params.retryIntervalMs Time to wait between retries in milliseconds
@@ -106,13 +110,14 @@ export const getTimezoneOffsetAndPersist = async (
   let success = false;
   let retries = 0;
   logger.info(
-    "Acquiring the timezone offset from MachineMetrics and storing in cache"
+    "Acquiring the timezone offset and timezone name from MachineMetrics and storing in cache"
   );
   while (!success && retries < params.maxRetries) {
     try {
-      const offsetHours = await getTimezoneOffset();
-      logger.info(`Timezone offset: ${offsetHours} hours`);
-      setTimezoneOffsetInCache(offsetHours);
+      const { offset, timezone } = await getTimezoneOffset();
+      logger.info(`Timezone offset: ${offset} hours, timezone: ${timezone}`);
+      setTimezoneOffsetInCache(offset);
+      setTimezoneNameInCache(timezone);
       success = true;
     } catch (error) {
       logger.error("Error getting timezone offset:", error);