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

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

@@ -1,351 +0,0 @@
-/**
- * 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";
-
-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.14.epic01.labor-ticket.*" (single level wildcard)
-   *   - "mm.14.epic01.erp.>" (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.14.${this.config.locationRef}.erp.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

@@ -1,96 +0,0 @@
-/**
- * Simple proof-of-concept NATS subscriber
- * Subscribes to mm.14.> and replies with "hello world"
- */
-
-import { connect, StringCodec } from "nats";
-import { logger } from "../../services/reporting-service";
-
-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.14.>
-    const sub = nc.subscribe("mm.14.>");
-
-    logger.info("Subscribed to mm.14.> - 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/utils/error-formatter.ts

@@ -1,205 +0,0 @@
-/**
- * Error formatter utility for standardizing error messages across connectors
- * Extracts human-readable messages from various error types (axios, custom errors, etc.)
- */
-
-export interface FormattedError {
-  message: string;
-  code: string;
-  httpStatus?: number;
-  metadata?: Record<string, any>;
-}
-
-/**
- * Extract meaningful error message from various error types
- */
-export function formatError(error: any): FormattedError {
-  if (!error) {
-    return {
-      message: 'Unknown error occurred',
-      code: 'UNKNOWN_ERROR',
-    };
-  }
-
-  // Handle axios errors FIRST (before checking for FormattedError)
-  // because axios errors also have message and code properties
-  if (error.isAxiosError || error.name === 'AxiosError') {
-    return formatAxiosError(error);
-  }
-
-  // If it's already a FormattedError, return as-is
-  // Check for httpStatus or metadata to distinguish from axios errors
-  if (error.message && error.code && typeof error.message === 'string' && typeof error.code === 'string' && !error.config) {
-    return error as FormattedError;
-  }
-
-  // Handle standard Error objects
-  if (error instanceof Error) {
-    return {
-      message: error.message || 'An error occurred',
-      code: 'ERROR',
-      metadata: {
-        name: error.name,
-      },
-    };
-  }
-
-  // Handle string errors
-  if (typeof error === 'string') {
-    return {
-      message: error,
-      code: 'ERROR',
-    };
-  }
-
-  // Last resort: try to extract any useful info
-  const message = error.message || error.toString?.() || 'Unknown error occurred';
-  return {
-    message: typeof message === 'string' ? message : JSON.stringify(message),
-    code: error.code || 'UNKNOWN_ERROR',
-  };
-}
-
-/**
- * Format axios-specific errors with detailed context
- */
-function formatAxiosError(error: any): FormattedError {
-  const httpStatus = error.response?.status;
-  const method = error.config?.method?.toUpperCase();
-  const url = error.config?.url;
-  
-  // First check if connector already extracted the message
-  let message = error._extractedMessage;
-  
-  // If not, try to extract from response data
-  if (!message) {
-    const extractedMessage = extractErrorMessage(error.response?.data);
-    message = extractedMessage || error.response?.statusText || error.message || 'Request failed';
-  }
-
-  // Determine error code based on status
-  const code = categorizeHttpError(httpStatus);
-
-  const metadata: Record<string, any> = {
-    method,
-    url,
-  };
-
-  // Add additional context for specific error types
-  if (httpStatus === 401 || httpStatus === 403) {
-    metadata.hint = 'Check authentication credentials';
-  } else if (httpStatus === 404) {
-    metadata.hint = 'Resource not found - check endpoint URL';
-  } else if (httpStatus && httpStatus >= 500) {
-    metadata.hint = 'ERP system may be temporarily unavailable';
-  }
-
-  return {
-    message,
-    code,
-    httpStatus,
-    metadata,
-  };
-}
-
-/**
- * Extract meaningful error message from response data
- * Handles various ERP-specific response formats
- */
-function extractErrorMessage(data: any): string | null {
-  if (!data) return null;
-
-  // Common error message fields across different ERPs
-  const possibleFields = [
-    'ErrorMessage',        // Epicor
-    'error.message',       // Common REST format
-    'error',               // Simple format
-    'Message',             // .NET style
-    'message',             // JavaScript style
-    'errorMessage',        // Camel case
-    'error_message',       // Snake case
-    'errors[0].message',   // Array of errors
-    'title',               // Problem details format
-    'detail',              // Problem details format
-  ];
-
-  for (const field of possibleFields) {
-    const value = getNestedValue(data, field);
-    if (value && typeof value === 'string') {
-      return value;
-    }
-  }
-
-  // If data is a string, return it
-  if (typeof data === 'string') {
-    // Try to parse as JSON first
-    try {
-      const parsed = JSON.parse(data);
-      return extractErrorMessage(parsed);
-    } catch {
-      return data;
-    }
-  }
-
-  return null;
-}
-
-/**
- * Get nested value from object using dot notation
- */
-function getNestedValue(obj: any, path: string): any {
-  const parts = path.split('.');
-  let current = obj;
-
-  for (const part of parts) {
-    // Handle array notation like 'errors[0]'
-    const arrayMatch = part.match(/(\w+)\[(\d+)\]/);
-    if (arrayMatch) {
-      const [, key, index] = arrayMatch;
-      current = current?.[key]?.[parseInt(index, 10)];
-    } else {
-      current = current?.[part];
-    }
-
-    if (current === undefined || current === null) {
-      return null;
-    }
-  }
-
-  return current;
-}
-
-/**
- * Categorize HTTP errors into standard codes
- */
-function categorizeHttpError(status?: number): string {
-  if (!status) return 'NETWORK_ERROR';
-
-  if (status === 400) return 'VALIDATION_ERROR';
-  if (status === 401) return 'AUTHENTICATION_ERROR';
-  if (status === 403) return 'AUTHORIZATION_ERROR';
-  if (status === 404) return 'NOT_FOUND';
-  if (status === 409) return 'CONFLICT';
-  if (status === 422) return 'VALIDATION_ERROR';
-  if (status === 429) return 'RATE_LIMIT';
-  if (status >= 500) return 'ERP_SERVER_ERROR';
-  if (status >= 400) return 'CLIENT_ERROR';
-
-  return 'HTTP_ERROR';
-}
-
-/**
- * Format error for logging (shorter, cleaner version)
- */
-export function formatErrorForLogging(error: any): string {
-  const formatted = formatError(error);
-  
-  let message = `[${formatted.code}] ${formatted.message}`;
-  
-  if (formatted.httpStatus) {
-    message = `[${formatted.httpStatus}] ${message}`;
-  }
-  
-  return message;
-}
-