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

package/src/services/nats-service/nats-service.ts

@@ -0,0 +1,351 @@
+/**
+ * NATS Service - Central connection and subscription management
+ * Allows connectors to register handlers for different NATS subjects
+ */
+
+import { connect, NatsConnection, StringCodec, Subscription } from "nats";
+import { logger } from "../reporting-service/index.js";
+
+const sc = StringCodec();
+
+export interface NatsMessageHandler {
+  /**
+   * Handler function for NATS messages
+   * - Return a value to reply (if msg has reply subject)
+   * - Return void/undefined for pub-sub (no reply)
+   */
+  handle: (data: any, subject: string) => Promise<any | void>;
+}
+
+export interface NatsHandlerRegistration {
+  /**
+   * Subject pattern to subscribe to (supports wildcards: *, >)
+   * Examples:
+   *   - "mm.16.epic01.labor-ticket.*" (single level wildcard)
+   *   - "mm.16.epic01.*" (multi-level wildcard)
+   */
+  subject: string;
+
+  /**
+   * Handler for this subject
+   */
+  handler: NatsMessageHandler;
+
+  /**
+   * Optional description for logging/debugging
+   */
+  description?: string;
+}
+
+export interface NatsServiceConfig {
+  /**
+   * NATS server URLs
+   */
+  servers: string | string[];
+
+  /**
+   * Connection name (for monitoring)
+   */
+  name: string;
+
+  /**
+   * Location reference (for subject namespacing)
+   */
+  locationRef: string;
+
+  /**
+   * ERP type (epicor, infor, etc.)
+   */
+  erpType: string;
+
+  /**
+   * Enable/disable NATS
+   */
+  enabled: boolean;
+
+  /**
+   * Auto-reconnect settings
+   */
+  reconnect?: boolean;
+  maxReconnectAttempts?: number;
+  reconnectTimeWait?: number;
+}
+
+export class NatsService {
+  private connection: NatsConnection | null = null;
+  private subscriptions: Map<string, Subscription> = new Map();
+  private config: NatsServiceConfig;
+  private handlers: NatsHandlerRegistration[] = [];
+  private statusPublishTimer: NodeJS.Timeout | null = null;
+
+  constructor(config: NatsServiceConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Register a handler for a specific subject pattern
+   */
+  registerHandler(registration: NatsHandlerRegistration): void {
+    logger.info("Registering NATS handler", {
+      subject: registration.subject,
+      description: registration.description,
+    });
+    this.handlers.push(registration);
+  }
+
+  /**
+   * Connect to NATS and start all registered handlers
+   */
+  async connect(): Promise<void> {
+    if (!this.config.enabled) {
+      logger.info("NATS is disabled, skipping connection");
+      return;
+    }
+
+    try {
+      logger.info("Connecting to NATS...", {
+        servers: this.config.servers,
+        name: this.config.name,
+      });
+
+      this.connection = await connect({
+        servers: this.config.servers,
+        name: this.config.name,
+        reconnect: this.config.reconnect ?? true,
+        maxReconnectAttempts: this.config.maxReconnectAttempts ?? -1,
+        reconnectTimeWait: this.config.reconnectTimeWait ?? 2000,
+      });
+
+      logger.info("Connected to NATS", {
+        server: this.connection.getServer(),
+        clientId: this.connection.info?.client_id,
+      });
+
+      // Start all registered handlers
+      for (const registration of this.handlers) {
+        await this.startHandler(registration);
+      }
+
+      // Start automatic status publishing
+      this.startStatusPublishing();
+
+      // Monitor connection status
+      this.monitorConnection();
+
+      // Graceful shutdown
+      this.setupShutdown();
+    } catch (error) {
+      logger.error("Failed to connect to NATS", { error });
+      throw error;
+    }
+  }
+
+  /**
+   * Start a single handler (subscribe to its subject)
+   */
+  private async startHandler(registration: NatsHandlerRegistration): Promise<void> {
+    if (!this.connection) {
+      throw new Error("NATS connection not established");
+    }
+
+    const sub = this.connection.subscribe(registration.subject);
+    this.subscriptions.set(registration.subject, sub);
+
+    logger.info("Started NATS handler", {
+      subject: registration.subject,
+      description: registration.description,
+    });
+
+    // Process messages
+    (async () => {
+      for await (const msg of sub) {
+        try {
+          const data = sc.decode(msg.data);
+          
+          logger.info("Received NATS message", {
+            subject: msg.subject,
+            hasReply: !!msg.reply,
+          });
+
+          // Parse JSON if possible
+          let parsedData: any;
+          try {
+            parsedData = JSON.parse(data);
+          } catch {
+            parsedData = data;
+          }
+
+          // Call handler
+          const response = await registration.handler.handle(parsedData, msg.subject);
+          
+          // If there's a reply subject and handler returned something, reply
+          if (msg.reply && response !== undefined) {
+            const responseStr = JSON.stringify(response);
+            msg.respond(sc.encode(responseStr));
+            logger.info("Sent reply", { replySubject: msg.reply });
+          }
+        } catch (error) {
+          logger.error("Error handling NATS message", {
+            subject: msg.subject,
+            error,
+          });
+
+          // Send error response if reply expected
+          if (msg.reply) {
+            const errorResponse = {
+              status: "error",
+              error: {
+                message: error instanceof Error ? error.message : "Unknown error",
+                code: "HANDLER_ERROR",
+              },
+            };
+            msg.respond(sc.encode(JSON.stringify(errorResponse)));
+          }
+        }
+      }
+    })();
+  }
+
+  /**
+   * Publish a message to a subject (for pub/sub)
+   */
+  async publish(subject: string, data: any): Promise<void> {
+    if (!this.connection) {
+      throw new Error("NATS connection not established");
+    }
+
+    const message = typeof data === "string" ? data : JSON.stringify(data);
+    this.connection.publish(subject, sc.encode(message));
+
+    logger.info("Published NATS message", { subject });
+  }
+
+  /**
+   * Send a request and wait for reply (for request-reply)
+   */
+  async request(subject: string, data: any, timeoutMs: number = 30000): Promise<any> {
+    if (!this.connection) {
+      throw new Error("NATS connection not established");
+    }
+
+    const message = typeof data === "string" ? data : JSON.stringify(data);
+    const response = await this.connection.request(
+      subject,
+      sc.encode(message),
+      { timeout: timeoutMs }
+    );
+
+    const responseData = sc.decode(response.data);
+    
+    try {
+      return JSON.parse(responseData);
+    } catch {
+      return responseData;
+    }
+  }
+
+  /**
+   * Check if connected to NATS
+   */
+  isConnected(): boolean {
+    return this.connection !== null && !this.connection.isClosed();
+  }
+
+  /**
+   * Start automatic status publishing (every 30 seconds)
+   */
+  private startStatusPublishing(): void {
+    logger.info("Starting status publishing (every 30 seconds)");
+
+    // Publish immediately on start
+    this.publishStatus();
+
+    // Then publish every 30 seconds
+    this.statusPublishTimer = setInterval(() => {
+      this.publishStatus();
+    }, 30000);
+  }
+
+  /**
+   * Publish connector status
+   */
+  private async publishStatus(): Promise<void> {
+    try {
+      const status = {
+        timestamp: new Date().toISOString(),
+        locationRef: this.config.locationRef,
+        erpType: this.config.erpType,
+        natsConnected: this.isConnected(),
+      };
+
+      await this.publish(
+        `mm.16.${this.config.locationRef}.status`,
+        status
+      );
+
+      logger.debug("Published connector status");
+    } catch (error) {
+      logger.error("Failed to publish status", { error });
+    }
+  }
+
+  /**
+   * Monitor connection status
+   */
+  private monitorConnection(): void {
+    if (!this.connection) return;
+
+    (async () => {
+      for await (const status of this.connection!.status()) {
+        // Only log important events, skip pingTimer
+        if (status.type !== "pingTimer") {
+          logger.info("NATS connection status", {
+            type: status.type,
+            data: status.data,
+          });
+        }
+      }
+    })();
+  }
+
+  /**
+   * Setup graceful shutdown
+   */
+  private setupShutdown(): void {
+    const shutdown = async () => {
+      logger.info("Shutting down NATS service...");
+      await this.disconnect();
+      process.exit(0);
+    };
+
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  }
+
+  /**
+   * Disconnect from NATS
+   */
+  async disconnect(): Promise<void> {
+    // Stop status publishing
+    if (this.statusPublishTimer) {
+      clearInterval(this.statusPublishTimer);
+      this.statusPublishTimer = null;
+    }
+
+    // Close connection
+    if (this.connection) {
+      await this.connection.drain();
+      this.connection = null;
+      this.subscriptions.clear();
+      logger.info("Disconnected from NATS");
+    }
+  }
+
+  /**
+   * Get the location reference
+   */
+  getLocationRef(): string {
+    return this.config.locationRef;
+  }
+}
+

package/src/services/nats-service/test-nats-subscriber.ts

@@ -0,0 +1,96 @@
+/**
+ * Simple proof-of-concept NATS subscriber
+ * Subscribes to mm.16.> and replies with "hello world"
+ */
+
+import { connect, StringCodec } from "nats";
+import { logger } from "../../services/reporting-service/index.js";
+
+const sc = StringCodec();
+
+async function startTestSubscriber() {
+  try {
+    // Connect to NATS server
+    const nc = await connect({
+      servers: "nats://localhost:4222",
+      name: "mm-erp-sdk-test-subscriber",
+    });
+
+    logger.info("Connected to NATS server", {
+      server: nc.getServer(),
+      clientId: nc.info?.client_id,
+    });
+
+    // Subscribe to all messages on mm.16.>
+    const sub = nc.subscribe("mm.16.>");
+
+    logger.info("Subscribed to mm.16.> - waiting for messages...");
+
+    // Process incoming messages
+    (async () => {
+      for await (const msg of sub) {
+        const data = sc.decode(msg.data);
+        
+        logger.info("📨 Received NATS message", {
+          subject: msg.subject,
+          data: data,
+          reply: msg.reply,
+        });
+
+        console.log("\n=== NATS MESSAGE RECEIVED ===");
+        console.log("Subject:", msg.subject);
+        console.log("Data:", data);
+        console.log("Reply subject:", msg.reply);
+        console.log("============================\n");
+
+        // Reply if there's a reply subject
+        if (msg.reply) {
+          const replyMessage = JSON.stringify({
+            message: "hello world",
+            timestamp: new Date().toISOString(),
+            receivedSubject: msg.subject,
+            receivedData: data,
+          });
+
+          msg.respond(sc.encode(replyMessage));
+          
+          logger.info("✅ Sent reply: hello world", {
+            replySubject: msg.reply,
+          });
+          
+          console.log("✅ Replied with: hello world\n");
+        }
+      }
+    })();
+
+    // Handle connection events
+    (async () => {
+      for await (const status of nc.status()) {
+        logger.info("NATS connection status", {
+          type: status.type,
+          data: status.data,
+        });
+        console.log(`Connection status: ${status.type}`, status.data);
+      }
+    })();
+
+    // Graceful shutdown
+    const shutdown = async () => {
+      logger.info("Shutting down NATS subscriber...");
+      await nc.drain();
+      process.exit(0);
+    };
+
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+
+  } catch (error) {
+    logger.error("Failed to connect to NATS", { error });
+    console.error("Error connecting to NATS:", error);
+    process.exit(1);
+  }
+}
+
+// Start the subscriber
+startTestSubscriber();
+

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

@@ -1,11 +1,9 @@
 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 initialLogLevel = process.env.LOG_LEVEL || "info";
 
 const LOGGER_ERROR_PREFIX = "[mm-erp-sdk logger]";
 
@@ -52,8 +50,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;
@@ -242,9 +277,6 @@ export const configureLogger = (logLevel: string, nodeEnv: string) => {
   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/types/erp-connector.ts

@@ -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

@@ -10,11 +10,3 @@ export type {
   ERPResponse,
   ERPObject,
 } from "./erp-types.js";
-export type {
-  FlattenedWorkOrderRow,
-  FlattenedWorkOrderRowBase,
-  FlattenedWorkOrderPartFields,
-  FlattenedWorkOrderPartOperationFields,
-  FlattenedWorkOrderFields,
-  FlattenedWorkOrderOperationFields,
-} from "./flattened-work-order.js";