@machinemetrics/mm-erp-sdk 0.1.1-beta.1

package/src/services/data-sync-service/data-sync-service.ts

@@ -0,0 +1,100 @@
+import Bree, { Job } from "bree";
+import Graceful from "@ladjs/graceful";
+import path from "path";
+import { fileURLToPath } from "url";
+import { CoreConfiguration } from "./configuration-manager";
+import logger from "../reporting-service/logger";
+
+export const runDataSyncService = async (connectorPath: string) => {
+  const config = CoreConfiguration.inst();
+
+  try {
+    // Find the SDK's node_modules directory and jobs path using ES module import
+    const currentFileUrl = import.meta.url;
+    const currentFilePath = fileURLToPath(currentFileUrl);
+
+    // Navigate from current file to the SDK root and then to jobs
+    // Current: /path/to/sdk/dist/mm-erp-sdk.js.js
+    // Target:  /path/to/sdk/dist/services/data-sync-service/jobs
+    const sdkDistPath = path.dirname(currentFilePath);
+    const jobsPath = path.join(
+      sdkDistPath,
+      "services",
+      "data-sync-service",
+      "jobs"
+    );
+
+    const bree = new Bree({
+      root: jobsPath,
+      logger,
+      worker: {
+        env: {
+          CONNECTOR_PATH: connectorPath,
+        },
+      },
+      jobs: [
+        // {
+        //   name: 'run-migrations',        // Running this once on startup will create the tables in the sqlite database
+        // },
+        {
+          name: "from-erp",
+          timeout: "10s",
+          interval: config.fromErpInterval,
+        },
+        {
+          name: "to-erp",
+          //timeout: '3s',                  // Use timeout during development to see the job in action quickly
+          interval: config.toErpInterval,
+        },
+        {
+          name: "retry-failed-labor-tickets",
+          interval: config.retryLaborTicketsInterval,
+        },
+        {
+          name: "clean-up-expired-cache",
+          interval: config.cacheExpirationCheckInterval,
+        },
+      ],
+    });
+
+    logger.info(
+      "\n================================INITIATING DATA SYNC CYCLES (Bree)================================\n"
+    );
+    const jobsConfig = bree.config.jobs.map((job: Job) => ({
+      name: job.name,
+      interval: job.interval,
+      timeout: job.timeout,
+    }));
+    logger.info("JOBS CONFIGURATION:", { jobs: jobsConfig });
+
+    const graceful = new Graceful({ brees: [bree] });
+    graceful.listen();
+
+    (async () => {
+      await bree.start();
+    })();
+
+    bree.on("jobStarted", (job) => {
+      console.log("Job " + job.name + " started");
+    });
+
+    bree.on("jobCompleted", (job) => {
+      if (job.error) {
+        console.error("Job " + job.name + " failed:", job.error);
+      } else {
+        console.log("Job " + job.name + " completed successfully!");
+      }
+    });
+
+    bree.on("error", (error) => {
+      console.error("Bree error:", error);
+    });
+
+    // Exit and let the jobs take over
+    logger.info(
+      "\n================================DATA SYNC CYCLES INITIATION COMPLETED================================\n"
+    );
+  } catch (error) {
+    logger.error("startUp: Error initiating data sync cycles:", error);
+  }
+};

package/src/services/data-sync-service/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Core data sync service functionality
+ */
+export { runDataSyncService } from "./data-sync-service";
+
+/**
+ * Configuration management for data sync
+ */
+export { getSQLServerConfiguration } from "./configuration-manager";
+
+export {
+  ErpApiConnectionParams,
+  getErpApiConnectionParams,
+} from "./configuration-manager";

package/src/services/data-sync-service/jobs/clean-up-expired-cache.ts

@@ -0,0 +1,38 @@
+import "dotenv/config";
+import { HashedCacheManager } from "../../caching-service/hashed-cache-manager";
+import { SQLiteCoordinator } from "../../sqlite-service";
+import logger from "../../../services/reporting-service/logger";
+
+const main = async () => {
+  const cacheManager = new HashedCacheManager();
+  try {
+    logger.info('Worker for job "clean-up-expired-cache" online');
+    logger.info(
+      "==========Starting clean-up-expired-cache job cycle=========="
+    );
+
+    await SQLiteCoordinator.executeWithLock("clean-up-cache", async () => {
+      await cacheManager.removeExpiredObjects();
+    });
+
+    logger.info(
+      "==========Completed clean-up-expired-cache job cycle=========="
+    );
+  } catch (error) {
+    logger.error('Worker for job "clean-up-expired-cache" had an error', {
+      err: error,
+    });
+    throw error; // Rethrow so Bree can handle it properly
+  } finally {
+    await cacheManager.destroy();
+  }
+};
+
+// For Bree compatibility - check if this is running as a worker
+if (require.main === module) {
+  // This is called when Bree runs this file as a worker
+  main();
+} else {
+  // Export for potential testing or direct usage
+  module.exports = main;
+}

package/src/services/data-sync-service/jobs/from-erp.ts

@@ -0,0 +1,55 @@
+import "dotenv/config";
+
+import logger from "../../../services/reporting-service/logger";
+import { SQLiteCoordinator } from "../../sqlite-service";
+import { createConnectorFromPath } from "../../../utils/connector-factory";
+
+const main = async () => {
+  try {
+    logger.info('Worker for job "from-erp" online');
+    logger.info("==========Starting from-erp job cycle==========");
+
+    // Get the connector path from the environment variable
+    const connectorPath = process.env.CONNECTOR_PATH;
+
+
+    if (!connectorPath) {
+      throw new Error("Connector path not provided in environment variables");
+    }
+
+    // Create a new connector instance for this job
+    const connector = await createConnectorFromPath(connectorPath);
+
+    await SQLiteCoordinator.executeWithLock("from-erp", async () => {
+      await connector.syncFromERP();
+    });
+
+    await connector.syncFromERPCompleted();
+    logger.info("==========Completed from-erp job cycle==========");
+  } catch (error) {
+    const errorDetails = {
+      message: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+      name: error instanceof Error ? error.name : undefined,
+      ...(error && typeof error === "object" ? error : {}), // Include all enumerable properties if it's an object
+    };
+    logger.error('Worker for job "from-erp" had an error', {
+      error: errorDetails,
+    });
+
+    throw error; // Rethrow so Bree can handle it properly
+  }
+};
+
+// For Bree compatibility - check if this is running as a worker
+// In ES modules, we need to check import.meta.url instead of require.main
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+
+if (isMainModule) {
+  // This is called when Bree runs this file as a worker
+  main().catch(() => {
+    process.exit(1);
+  });
+}
+
+export default main;

package/src/services/data-sync-service/jobs/retry-failed-labor-tickets.ts

@@ -0,0 +1,44 @@
+import "dotenv/config";
+
+import logger from "../../../services/reporting-service/logger";
+import { createConnectorFromPath } from "../../../utils/connector-factory";
+
+const main = async () => {
+  try {
+    logger.info('Worker for job "retry-failed-labor-tickets" online');
+    logger.info(
+      "==========Starting retry-failed-labor-tickets job cycle=========="
+    );
+
+    // Get the connector path from the environment variable
+    const connectorPath = process.env.CONNECTOR_PATH;
+
+    if (!connectorPath) {
+      throw new Error("Connector path not provided in environment variables");
+    }
+
+    // Create a new connector instance for this job
+    const connector = await createConnectorFromPath(connectorPath);
+
+    await connector.retryFailedLaborTickets();
+    await connector.retryFailedLaborTicketsCompleted();
+
+    logger.info(
+      "==========Completed retry-failed-labor-tickets job cycle=========="
+    );
+  } catch (error) {
+    logger.error('Worker for job "retry-failed-labor-tickets" had an error', {
+      err: error,
+    });
+    throw error; // Rethrow so Bree can handle it properly
+  }
+};
+
+// For Bree compatibility - check if this is running as a worker
+if (require.main === module) {
+  // This is called when Bree runs this file as a worker
+  main();
+} else {
+  // Export for potential testing or direct usage
+  module.exports = main;
+}

package/src/services/data-sync-service/jobs/run-migrations.ts

@@ -0,0 +1,21 @@
+import knex, { Knex } from "knex";
+import logger from "../../reporting-service/logger";
+import config from "../../../knexfile";
+
+// MLW TODO Consider the location of knexfile
+const db: Knex = knex(config.local);
+
+export default async function runMigrations() {
+  try {
+    logger.info("Running migrations...");
+    await db.migrate.latest();
+    logger.info("Migrations complete!");
+  } catch (error) {
+    logger.error("Error running migrations:", error);
+    process.exit(1);
+  } finally {
+    await db.destroy();
+  }
+}
+
+runMigrations();

package/src/services/data-sync-service/jobs/to-erp.ts

@@ -0,0 +1,53 @@
+import "dotenv/config";
+
+import logger from "../../reporting-service/logger";
+import { createConnectorFromPath } from "../../../utils/connector-factory";
+
+const main = async () => {
+  try {
+    logger.info('Worker for job "to-erp" online');
+    logger.info("==========Starting to-erp job cycle==========");
+
+    // Get the connector path from the environment variable
+    const connectorPath = process.env.CONNECTOR_PATH;
+
+    if (!connectorPath) {
+      throw new Error("Connector path not provided in environment variables");
+    }
+
+    // Create a new connector instance for this job
+    const connector = await createConnectorFromPath(connectorPath);
+
+    await connector.syncToERP();
+    await connector.syncToERPCompleted();
+
+    logger.info("==========Completed to-erp job cycle==========");
+  } catch (error) {
+    const errorDetails = {
+      message: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+      name: error instanceof Error ? error.name : undefined,
+      ...(error && typeof error === "object" ? error : {}), // Include all enumerable properties if it's an object
+    };
+    logger.error('Worker for job "to-erp" had an error', {
+      error: errorDetails,
+      connectorPath: process.env.CONNECTOR_PATH,
+    });
+
+    // Also log to console for immediate visibility
+    console.error("to-erp job error:", error);
+
+    throw error; // Rethrow so Bree can handle it properly
+  }
+};
+
+// For Bree compatibility - check if this is running as a worker
+// In ES modules, we need to check import.meta.url instead of require.main
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  // This is called when Bree runs this file as a worker
+  main();
+}
+
+// Export for potential testing or direct usage (ES module default export)
+export default main;

package/src/services/erp-api-services/errors.ts

@@ -0,0 +1,115 @@
+import { AxiosError } from "axios";
+import logger from "../reporting-service/logger";
+import { GraphQLServerError } from "./graphql/types";
+import { HTTPError } from "../../utils/http-client";
+
+/**
+ * Represents GraphQL specific errors (validation, missing fields, etc.)
+ */
+export class GraphQLError extends Error {
+  constructor(
+    message: string,
+    public errors: GraphQLServerError[]
+  ) {
+    super(message);
+    this.name = "GraphQLError";
+  }
+}
+
+/**
+ * Centralized error handling for API requests.
+ * Transforms various error types into standardized HTTPError or GraphQLError.
+ */
+export class ErrorHandler {
+  /**
+   * Transforms any error into a standardized HTTPError or GraphQLError and throws it.
+   * Never returns - always throws an error.
+   *
+   * @throws {HTTPError|GraphQLError} Standardized error with appropriate details
+   */
+  static handle(error: unknown): never {
+    // Handle HTTPError (already processed by http-client)
+    if (error instanceof HTTPError) {
+      // For GraphQL responses with errors in the data
+      if (
+        error.data &&
+        typeof error.data === "object" &&
+        "errors" in error.data
+      ) {
+        const graphqlError = new GraphQLError(
+          "GraphQL Error",
+          (error.data as { errors: GraphQLServerError[] }).errors
+        );
+
+        // Log the error
+        logger.error("Error>>GraphQL", {
+          message: graphqlError.message,
+          errors: graphqlError.errors,
+        });
+
+        throw graphqlError;
+      }
+
+      // Log HTTP error with generic response data
+      logger.error("Error>>HTTP", {
+        status: error.status,
+        message: error.message,
+        code: error.code,
+        data: error.data,
+      });
+
+      throw error; // Re-throw the original HTTPError
+    }
+
+    // Handle raw AxiosError (direct usage, not through http-client)
+    if (error instanceof AxiosError) {
+      // For GraphQL responses with errors
+      if (error.response?.data?.errors) {
+        const graphqlError = new GraphQLError(
+          "GraphQL Error",
+          error.response.data.errors as GraphQLServerError[]
+        );
+
+        // Log the error
+        logger.error("Error>>GraphQL", {
+          message: graphqlError.message,
+          errors: graphqlError.errors,
+        });
+
+        throw graphqlError;
+      }
+
+      // For HTTP errors - create HTTPError and log with response data
+      const httpError = new HTTPError(
+        error.message,
+        error.response?.status || 500,
+        error.code,
+        error.response?.data
+      );
+
+      // Log HTTP error with generic response data
+      logger.error("Error>>HTTP", {
+        status: httpError.status,
+        message: httpError.message,
+        code: httpError.code,
+        data: httpError.data,
+      });
+
+      throw httpError;
+    }
+
+    // For other errors
+    const httpError = new HTTPError(
+      error instanceof Error ? error.message : "An unknown error occurred",
+      500
+    );
+
+    // Log the error
+    logger.error("Error>>Unknown", {
+      message: httpError.message,
+      status: httpError.status,
+    });
+
+    throw httpError;
+  }
+}

package/src/services/erp-api-services/graphql/graphql-service.ts

@@ -0,0 +1,116 @@
+import {
+  HTTPClient,
+  HTTPClientFactory,
+  HTTPResponse,
+} from "../../../utils/http-client";
+import { GraphQLResponse } from "./types";
+import { ErrorHandler } from "../errors";
+import { APIResponse } from "../types";
+import { ERPApiConfig } from "../types";
+
+const DEFAULT_RETRY_ATTEMPTS = 0; // One try only, no retries
+
+export class GraphQLService {
+  private client: HTTPClient;
+  private config: ERPApiConfig;
+  private endpoint: string;
+
+  constructor(config: ERPApiConfig, endpoint: string, retryAttempts?: number) {
+    this.config = config;
+    this.endpoint = endpoint
+      ? endpoint.startsWith("/")
+        ? endpoint
+        : `/${endpoint}`
+      : "";
+    this.client = HTTPClientFactory.getInstance({
+      baseUrl: config.apiUrl,
+      retryAttempts: retryAttempts ?? DEFAULT_RETRY_ATTEMPTS,
+    });
+  }
+
+  private async getHeaders(): Promise<Record<string, string>> {
+    const token = await this.config.getAuthToken();
+    return {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    };
+  }
+
+  /**
+   * Handles a GraphQL response, properly handling both successful responses
+   * and GraphQL-level errors (which come in a 200 HTTP response)
+   * 
+   * From the GraphQL specification (https://spec.graphql.org/draft/#sec-Errors):
+>  *     "When a GraphQL server encounters an error, it should return a response with a 
+>  *      top-level "errors" field containing the error information. The response may still contain
+   *      a partial result in the "data" field if the error occurred after some data was already resolved."
+   * 
+   * And specifically about HTTP status codes:
+   *     "A server should return a 200 status code when a GraphQL operation successfully executes, including when  
+   *      the operation returns errors. A server should return a 400 status code when a GraphQL operation fails to execute."
+   */
+  private handleGraphQLResponse<T>(
+    response: HTTPResponse<GraphQLResponse<T>>
+  ): APIResponse<T> {
+    return {
+      data: response.data.data as T,
+      metadata: {
+        errors: response.data.errors,
+        extensions: response.data.extensions,
+      },
+    };
+  }
+
+  /**
+   * Executes a GraphQL query
+   * @param query The GraphQL query string
+   * @param variables Optional variables for the query
+   * @returns The query result
+   * @throws {HTTPError} For HTTP/network errors only
+   */
+  async query<T>(
+    query: string,
+    variables?: Record<string, unknown>
+  ): Promise<APIResponse<T>> {
+    try {
+      const headers = await this.getHeaders();
+      const response = await this.client.request<GraphQLResponse<T>>({
+        method: "POST",
+        url: this.endpoint,
+        data: { query, variables },
+        headers,
+      });
+
+      return this.handleGraphQLResponse(response);
+    } catch (error) {
+      ErrorHandler.handle(error);
+    }
+  }
+
+  /**
+   * Executes a GraphQL mutation
+   * @param mutation The GraphQL mutation string
+   * @param variables Optional variables for the mutation
+   * @returns The mutation result
+   * @throws {HTTPError} For HTTP/network errors only
+   */
+  async mutate<T>(
+    mutation: string,
+    variables?: Record<string, unknown>
+  ): Promise<APIResponse<T>> {
+    try {
+      const headers = await this.getHeaders();
+      const response = await this.client.request<GraphQLResponse<T>>({
+        method: "POST",
+        url: this.endpoint,
+        data: { query: mutation, variables },
+        headers,
+      });
+
+      return this.handleGraphQLResponse(response);
+    } catch (error) {
+      ErrorHandler.handle(error);
+    }
+  }
+}

package/src/services/erp-api-services/graphql/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Base GraphQL response type that matches the GraphQL specification.
+ * Note that pagination styles are server-specific and should be defined by each connector.
+ */
+
+/**
+ * This represents an error from the GraphQL server, described here: https://spec.graphql.org/draft/#sec-Errors
+ */
+export interface GraphQLServerError {
+  /** A description of the error */
+  message: string;
+  /** Locations in the query where the error occurred */
+  locations?: { line: number; column: number }[];
+  /** Path to the field that caused the error */
+  path?: (string | number)[];
+  /** Additional error information */
+  extensions?: Record<string, unknown>;
+}
+
+/**
+ * The standard GraphQL response format as per the GraphQL spec: https://spec.graphql.org/draft/#sec-Response-Format
+ */
+export interface GraphQLResponse<T> {
+  /** The actual response data, or null if there were errors */
+  data: T | null;
+  /** Array of errors if any occurred */
+  errors?: GraphQLServerError[];
+  /** Optional extensions to the response */
+  extensions?: Record<string, unknown>;
+}

package/src/services/erp-api-services/index.ts

@@ -0,0 +1,14 @@
+/**
+ * ERP API Services for the MachineMetrics ERP Connector SDK.
+ * This file exports the public interfaces and types for ERP API services.
+ */
+
+// REST API Service
+export { RestAPIService } from "./rest/rest-api-service";
+export type { QueryParams } from "./rest/get-query-params";
+
+// GraphQL Service
+export { GraphQLService } from "./graphql/graphql-service";
+
+// OAuth Client
+export { OAuthClient } from "./oauth-client";

package/src/services/erp-api-services/oauth-client.ts

@@ -0,0 +1,72 @@
+/**
+ * Configuration for OAuth client credentials flow
+ */
+export interface OAuthConfig {
+  /** The URL to request the OAuth token from */
+  authUrl: string;
+  /** The client ID for OAuth authentication */
+  clientId: string;
+  /** The client secret for OAuth authentication */
+  clientSecret: string;
+  /** The scope for the OAuth token. Use empty string if no scope is needed. */
+  scope: string;
+}
+
+/**
+ * Standard OAuth 2.0 token response format as defined in RFC 6749
+ */
+export interface OAuthTokenResponse {
+  /** The access token issued by the authorization server */
+  access_token: string;
+  /** The type of token issued (typically "Bearer") */
+  token_type: string;
+  /** The lifetime in seconds of the access token */
+  expires_in: number;
+  /** The refresh token, which can be used to obtain new access tokens (optional) */
+  refresh_token?: string;
+  /** The scope of the access token (optional) */
+  scope?: string;
+}
+
+/**
+ * A utility class for handling OAuth client credentials flow.
+ * This is specifically for the client credentials grant type,
+ * which is used for server-to-server authentication.
+ */
+export class OAuthClient {
+  constructor(private config: OAuthConfig) {}
+
+  /**
+   * Requests an OAuth token using the client credentials flow.
+   * The request is sent as application/x-www-form-urlencoded.
+   * @returns A promise that resolves to the token response containing access_token and expires_in
+   * @throws Error if the token request fails
+   */
+  async getToken(): Promise<OAuthTokenResponse> {
+    const formData = new URLSearchParams({
+      grant_type: "client_credentials",
+      client_id: this.config.clientId,
+      client_secret: this.config.clientSecret,
+      scope: this.config.scope,
+    });
+
+    const response = await fetch(this.config.authUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: formData,
+    });
+
+    if (!response.ok) {
+      throw new Error(`OAuth token request failed: ${response.statusText}`);
+    }
+
+    const data = (await response.json()) as OAuthTokenResponse;
+    if (data.token_type !== "Bearer") {
+      throw new Error(`Unexpected token type: ${data.token_type}`);
+    }
+
+    return data;
+  }
+}