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

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

@@ -19,7 +19,8 @@ export class MMSendPerson implements IToRESTApiObject {
     public personId: string,
     public firstName: string,
     public lastName: string,
-    public isActive: boolean
+    public isActive: boolean,
+    public customFields: Record<string, any> = {}
   ) {}
 
   toRESTApiObject(): Record<string, string> {
@@ -28,6 +29,7 @@ export class MMSendPerson implements IToRESTApiObject {
       firstName: this.firstName,
       lastName: this.lastName,
       isActive: this.isActive ? "1" : "0",
+      customFields: JSON.stringify(this.customFields),
     };
   }
 
@@ -36,7 +38,8 @@ export class MMSendPerson implements IToRESTApiObject {
       data.personId || "",
       data.firstName || "",
       data.lastName || "",
-      data.isActive === "1"
+      data.isActive === "1",
+      data.customFields ? JSON.parse(data.customFields) : {}
     );
   }
 }
@@ -49,7 +52,8 @@ export class MMSendResource implements IToRESTApiObject {
     public description: string, // Text description of the resource (optional)
     public type: string, // The type of resource (optional)
     public productionBurdenRateHourly: number, // The cost associated with running this machine in production/hour (optional)
-    public setupBurdenRateHourly: number // The cost associated with running this machine in setup/hour (optional)
+    public setupBurdenRateHourly: number, // The cost associated with running this machine in setup/hour (optional)
+    public customFields: Record<string, any> = {}
   ) {}
 
   toRESTApiObject(): Record<string, string> {
@@ -61,6 +65,7 @@ export class MMSendResource implements IToRESTApiObject {
       type: this.type,
       productionBurdenRateHourly: this.productionBurdenRateHourly.toString(),
       setupBurdenRateHourly: this.setupBurdenRateHourly.toString(),
+      customFields: JSON.stringify(this.customFields),
     };
   }
 
@@ -72,7 +77,8 @@ export class MMSendResource implements IToRESTApiObject {
       data.description || "",
       data.type || "",
       parseFloat(data.productionBurdenRateHourly || "0"),
-      parseFloat(data.setupBurdenRateHourly || "0")
+      parseFloat(data.setupBurdenRateHourly || "0"),
+      data.customFields ? JSON.parse(data.customFields) : {}
     );
   }
 }
@@ -81,7 +87,8 @@ export class MMSendPart implements IToRESTApiObject {
   constructor(
     public partNumber: string,
     public partRevision: string,
-    public method: string
+    public method: string,
+    public customFields: Record<string, any> = {}
   ) {}
 
   toRESTApiObject(): Record<string, string> {
@@ -89,6 +96,7 @@ export class MMSendPart implements IToRESTApiObject {
       partNumber: this.partNumber,
       partRevision: this.partRevision,
       method: this.method,
+      customFields: JSON.stringify(this.customFields),
     };
   }
 
@@ -96,7 +104,8 @@ export class MMSendPart implements IToRESTApiObject {
     return new MMSendPart(
       data.partNumber || "",
       data.partRevision || "",
-      data.method || ""
+      data.method || "",
+      data.customFields ? JSON.parse(data.customFields) : {}
     );
   }
 }
@@ -111,7 +120,8 @@ export class MMSendPartOperation implements IToRESTApiObject {
     public cycleTimeMs: number,
     public setupTimeMs: number,
     public description: string,
-    public quantityPerPart: number
+    public quantityPerPart: number,
+    public customFields: Record<string, any> = {}
   ) {}
 
   toRESTApiObject(): Record<string, string | null> {
@@ -125,6 +135,7 @@ export class MMSendPartOperation implements IToRESTApiObject {
       setupTimeMs: this.setupTimeMs.toString(),
       description: this.description,
       quantityPerPart: this.quantityPerPart.toString(),
+      customFields: JSON.stringify(this.customFields),
     };
   }
 
@@ -140,7 +151,8 @@ export class MMSendPartOperation implements IToRESTApiObject {
       parseInt(data.cycleTimeMs || "0"),
       parseInt(data.setupTimeMs || "0"),
       data.description || "",
-      parseFloat(data.quantityPerPart || "1")
+      parseFloat(data.quantityPerPart || "1"),
+      data.customFields ? JSON.parse(data.customFields) : {}
     );
   }
 }
@@ -160,7 +172,8 @@ export class MMSendWorkOrder implements IToRESTApiObject {
     public quantityRequired: number,
     public partNumber: string,
     public partRevision: string,
-    public method: string
+    public method: string,
+    public customFields: Record<string, any> = {}
   ) {}
 
   toRESTApiObject(): Record<string, string | null> {
@@ -179,6 +192,7 @@ export class MMSendWorkOrder implements IToRESTApiObject {
       partNumber: this.partNumber,
       partRevision: this.partRevision,
       method: this.method,
+      customFields: JSON.stringify(this.customFields),
     };
   }
 
@@ -197,7 +211,8 @@ export class MMSendWorkOrder implements IToRESTApiObject {
       parseFloat(data.quantityRequired || "0"),
       data.partNumber || "",
       data.partRevision || "",
-      data.method || ""
+      data.method || "",
+      data.customFields ? JSON.parse(data.customFields) : {}
     );
   }
 }
@@ -222,7 +237,8 @@ export class MMSendWorkOrderOperation implements IToRESTApiObject {
     public setupburdenRatehourly: number,
     public operationType: string,
     public quantityPerPart: number,
-    public status: string
+    public status: string,
+    public customFields: Record<string, any> = {}
   ) {}
 
   toRESTApiObject(): Record<string, string | null> {
@@ -246,6 +262,7 @@ export class MMSendWorkOrderOperation implements IToRESTApiObject {
       operationType: this.operationType,
       quantityPerPart: this.quantityPerPart.toString(),
       status: this.status,
+      customFields: JSON.stringify(this.customFields),
     };
   }
 
@@ -271,7 +288,8 @@ export class MMSendWorkOrderOperation implements IToRESTApiObject {
       parseFloat(data.setupburdenRatehourly || "0"),
       data.operationType || "",
       parseFloat(data.quantityPerPart || "1"),
-      data.status || ""
+      data.status || "",
+      data.customFields ? JSON.parse(data.customFields) : {}
     );
   }
 }
@@ -282,7 +300,8 @@ export class MMSendReason implements IToRESTApiObject {
     public category: string,
     public code: string,
     public description: string,
-    public entityType: string
+    public entityType: string,
+    public customFields: Record<string, any> = {}
   ) {}
 
   toRESTApiObject(): Record<string, string> {
@@ -292,6 +311,7 @@ export class MMSendReason implements IToRESTApiObject {
       code: this.code,
       description: this.description,
       entityType: this.entityType,
+      customFields: JSON.stringify(this.customFields),
     };
   }
 
@@ -301,7 +321,8 @@ export class MMSendReason implements IToRESTApiObject {
       data.category || "",
       data.code || "",
       data.description || "",
-      data.entityType || ""
+      data.entityType || "",
+      data.customFields ? JSON.parse(data.customFields) : {}
     );
   }
 }
@@ -323,7 +344,8 @@ export class MMSendLaborTicket implements IToRESTApiObject {
     public badParts: number,
     public type: string,
     public comment: string,
-    public state: string
+    public state: string,
+    public customFields: Record<string, any> = {}
   ) {}
 
   toRESTApiObject(): Record<string, string | null> {
@@ -344,6 +366,7 @@ export class MMSendLaborTicket implements IToRESTApiObject {
       type: this.type,
       comment: this.comment,
       state: this.state,
+      customFields: JSON.stringify(this.customFields),
     };
   }
 
@@ -366,7 +389,8 @@ export class MMSendLaborTicket implements IToRESTApiObject {
       parseInt(data.badParts || "0"),
       data.type || "",
       data.comment || "",
-      data.state || ""
+      data.state || "",
+      data.customFields ? JSON.parse(data.customFields) : {}
     );
   }
 }

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();
+