@machinemetrics/mm-erp-sdk 0.9.3 → 0.9.4

package/src/services/mm-api-service/mm-aggregated-part-counts.ts

@@ -0,0 +1,127 @@
+/**
+ * GraphQL `aggregatedPartCounts` argument builder (inline `args: { ... }` fragment).
+ * `machineRef`, `metricKey`, `windowStartAt`, and `windowEndAt` are required in `args`.
+ * Optional tuning: `bucketWidth`, `bucketResolution`, and `windowWidth` are passed through when set (see MM GraphQL schema).
+ *
+ * @see https://developers.machinemetrics.com/docs/graphql/api
+ */
+
+import type { MMAggregatedPartCountBucket } from "./types/mm-response-interfaces.js";
+import { escapeGraphqlStringLiteral } from "./graphql-string-literal.js";
+
+export const MM_DEFAULT_PART_COUNT_METRIC_KEY = "part-count" as const;
+
+export function buildAggregatedPartCountsArgsFragment(options: {
+  machineRef: number;
+  metricKey: string;
+  windowStartAt: string;
+  windowEndAt: string;
+  bucketWidth?: string;
+  bucketResolution?: number;
+  windowWidth?: string;
+}): string {
+  const refInt = Math.trunc(Number(options.machineRef));
+  if (!Number.isFinite(refInt)) {
+    throw new RangeError("machineRef must be a finite number");
+  }
+  const parts: string[] = [
+    `machineRef: ${refInt}`,
+    `metricKey: "${escapeGraphqlStringLiteral(options.metricKey)}"`,
+    `windowStartAt: "${escapeGraphqlStringLiteral(options.windowStartAt)}"`,
+    `windowEndAt: "${escapeGraphqlStringLiteral(options.windowEndAt)}"`,
+  ];
+  if (options.bucketWidth !== undefined) {
+    parts.push(`bucketWidth: "${escapeGraphqlStringLiteral(options.bucketWidth)}"`);
+  }
+  if (options.bucketResolution !== undefined) {
+    const bucketResolution = Number(options.bucketResolution);
+    if (!Number.isFinite(bucketResolution)) {
+      throw new RangeError("bucketResolution must be a finite number");
+    }
+    parts.push(`bucketResolution: ${bucketResolution}`);
+  }
+  if (options.windowWidth !== undefined) {
+    parts.push(`windowWidth: "${escapeGraphqlStringLiteral(options.windowWidth)}"`);
+  }
+  return parts.join(", ");
+}
+
+export function buildAggregatedPartCountsQuery(options: {
+  machineRef: number;
+  metricKey: string;
+  windowStartAt: string;
+  windowEndAt: string;
+  bucketWidth?: string;
+  bucketResolution?: number;
+  windowWidth?: string;
+}): string {
+  const args = buildAggregatedPartCountsArgsFragment(options);
+  return `query aggregatedPartCountsForMachine { aggregatedPartCounts(args: { ${args} }) { machineRef metricKey sumOfValues eventCount bucketStartAt bucketEndAt bucketWidth firstValue lastValue } }`;
+}
+
+/**
+ * Parses one `aggregatedPartCounts` bucket from JSON.
+ * Per MM GraphQL, each returned row includes non-null strings for `metricKey`, `bucketStartAt`, `bucketEndAt`, and `bucketWidth` (width may be empty); absence, null, or wrong types throw.
+ */
+export function parseAggregatedPartCountBucketRow(
+  raw: unknown
+): MMAggregatedPartCountBucket {
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error("aggregatedPartCounts: invalid row");
+  }
+  const o = raw as Record<string, unknown>;
+  const machineRef =
+    typeof o.machineRef === "number" ? o.machineRef : Number(o.machineRef);
+  const sumOfValues =
+    typeof o.sumOfValues === "number" ? o.sumOfValues : Number(o.sumOfValues);
+  const eventCount =
+    typeof o.eventCount === "number" ? o.eventCount : Number(o.eventCount);
+  if (typeof o.metricKey !== "string" || o.metricKey.length === 0) {
+    throw new Error("aggregatedPartCounts: invalid or missing metricKey");
+  }
+  if (typeof o.bucketStartAt !== "string" || o.bucketStartAt.length === 0) {
+    throw new Error("aggregatedPartCounts: invalid or missing bucketStartAt");
+  }
+  if (typeof o.bucketEndAt !== "string" || o.bucketEndAt.length === 0) {
+    throw new Error("aggregatedPartCounts: invalid or missing bucketEndAt");
+  }
+  if (typeof o.bucketWidth !== "string") {
+    throw new Error("aggregatedPartCounts: invalid or missing bucketWidth");
+  }
+  const metricKey = o.metricKey;
+  const bucketStartAt = o.bucketStartAt;
+  const bucketEndAt = o.bucketEndAt;
+  const bucketWidth = o.bucketWidth;
+  if (
+    !Number.isFinite(machineRef) ||
+    !Number.isFinite(sumOfValues) ||
+    !Number.isFinite(eventCount)
+  ) {
+    throw new Error("aggregatedPartCounts: missing numeric fields");
+  }
+  const firstValue =
+    o.firstValue === null || o.firstValue === undefined
+      ? null
+      : typeof o.firstValue === "number"
+        ? o.firstValue
+        : Number(o.firstValue);
+  const lastValue =
+    o.lastValue === null || o.lastValue === undefined
+      ? null
+      : typeof o.lastValue === "number"
+        ? o.lastValue
+        : Number(o.lastValue);
+  return {
+    machineRef,
+    metricKey,
+    sumOfValues,
+    eventCount,
+    bucketStartAt,
+    bucketEndAt,
+    bucketWidth,
+    firstValue:
+      firstValue === null || Number.isFinite(firstValue) ? firstValue : null,
+    lastValue:
+      lastValue === null || Number.isFinite(lastValue) ? lastValue : null,
+  };
+}

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

@@ -13,7 +13,19 @@ import { Checkpoint } from "./types/checkpoint.js";
 import { CoreConfiguration } from "../data-sync-service/configuration-manager.js";
 import { ErrorHandler } from "../erp-api-services/errors.js";
 import {
+  assertMmGraphqlProxyResponseHasNoErrors,
+  buildMmGraphqlProxyRequestBody,
+} from "./mm-graphql-proxy.js";
+import {
+  buildAggregatedPartCountsQuery,
+  MM_DEFAULT_PART_COUNT_METRIC_KEY,
+  parseAggregatedPartCountBucketRow,
+} from "./mm-aggregated-part-counts.js";
+import { escapeGraphqlStringLiteral } from "./graphql-string-literal.js";
+import {
+  MMAggregatedPartCountBucket,
   MMApiBaseResponse,
+  MMMappedErpResourceRow,
   MMGraphQLReasonResponse,
   MMGraphQLResourceResponse,
   MMGraphQLWorkOrderResponse,
@@ -344,11 +356,12 @@ export class MMApiClient {
     variables?: Record<string, unknown>
   ): Promise<MMApiBaseResponse> {
     try {
-      const body: Record<string, unknown> = { operationName, query };
-      if (variables !== undefined && Object.keys(variables).length > 0) {
-        body.variables = variables;
-      }
-      return await this.postData(
+      const body = buildMmGraphqlProxyRequestBody(
+        operationName,
+        query,
+        variables
+      );
+      const result = (await this.postData(
         this.resourceURLs[GRAPHQL],
         body,
         {},
@@ -357,7 +370,9 @@ export class MMApiClient {
           token: CoreConfiguration.inst().mmApiAuthToken,
           headers: { "Content-Type": "application/json" },
         }
-      );
+      )) as Record<string, unknown> & MMApiBaseResponse;
+      assertMmGraphqlProxyResponseHasNoErrors(result);
+      return result;
     } catch (error) {
       ErrorHandler.handle(error);
     }
@@ -838,10 +853,7 @@ export class MMApiClient {
   async fetchWorkOrderFromGraphQL(
     workOrderId: string
   ): Promise<MMGraphQLWorkOrderResponse> {
-    // Escape just enough to safely embed in a GraphQL string literal
-    const escapedWorkOrderId = workOrderId
-      .replace(/\\/g, "\\\\")
-      .replace(/"/g, '\\"');
+    const escapedWorkOrderId = escapeGraphqlStringLiteral(workOrderId);
 
     const query =
       `query getErpWorkOrder { ` +
@@ -858,6 +870,127 @@ export class MMApiClient {
     )) as unknown as MMGraphQLWorkOrderResponse;
   }
 
+  /**
+   * Returns ERP resources for a company that are **mapped to MachineMetrics** (`machineRef` is set).
+   * GraphQL: `erpResources` filtered by `companyId` and non-null `machineRef`. Extends
+   * {@link fetchResourcesFromGraphQL} with company scope and richer fields (`isResourceGroup`, `machineGroupId`, etc.).
+   *
+   * @param companyId - MachineMetrics company identifier (string). Whitespace is trimmed; empty after trim throws.
+   * @returns Parsed rows; order matches the API response.
+   * @throws {Error} When `companyId` is missing, the response shape is invalid, or the GraphQL proxy returns top-level `errors`.
+   */
+  async fetchMappedErpResourcesForCompany(
+    companyId: string
+  ): Promise<MMMappedErpResourceRow[]> {
+    const id = companyId.trim();
+    if (!id) {
+      throw new Error("fetchMappedErpResourcesForCompany: companyId is required");
+    }
+    const safe = escapeGraphqlStringLiteral(id);
+    const query = `query mappedErpResourcesForCompany { erpResources(where: { companyId: { _eq: "${safe}" }, machineRef: { _is_null: false } }) { isResourceGroup machineGroupId machineRef resourceId name type } }`;
+    const response = (await this.graphqlRequest(
+      "mappedErpResourcesForCompany",
+      query
+    )) as { data?: { erpResources?: unknown } };
+    const list = response.data?.erpResources;
+    if (!Array.isArray(list)) {
+      throw new Error(
+        "fetchMappedErpResourcesForCompany: missing data.erpResources array"
+      );
+    }
+    return list.map(parseMappedErpResourceRow);
+  }
+
+  /**
+   * GraphQL `aggregatedPartCounts` for one `machineRef`: **one HTTP request**; the API may return **multiple bucket rows**
+   * (time buckets) for that machine.
+   *
+   * @param options.machineRef - Numeric MM machine reference (`machineRef` in GraphQL).
+   * @param options.windowStartAt - Window start as an ISO-8601 string (e.g. `2025-01-01T00:00:00.000Z`). Must match MM GraphQL expectations.
+   * @param options.windowEndAt - Window end, same format as `windowStartAt`.
+   * @param options.metricKey - Metric to aggregate; defaults to `"part-count"` (`MM_DEFAULT_PART_COUNT_METRIC_KEY`).
+   * @param options.bucketWidth - Optional. GraphQL duration string for bucket size (API-specific; e.g. hour/day windowing).
+   * @param options.bucketResolution - Optional. Numeric resolution when the API supports sub-bucket refinement.
+   * @param options.windowWidth - Optional. Alternative window sizing hint when supported by the schema.
+   * @returns One row per bucket from `data.aggregatedPartCounts`.
+   * @throws {Error} When the response lacks `data.aggregatedPartCounts`, a row fails parsing, or GraphQL returns errors.
+   * @throws {RangeError} When `machineRef` or `bucketResolution` is not finite (via query builder).
+   *
+   * For multiple machines, call once per `machineRef` (for example `Promise.all`) so filtering and error policy stay explicit at the call site.
+   */
+  async fetchAggregatedPartCountsForMachine(options: {
+    machineRef: number;
+    windowStartAt: string;
+    windowEndAt: string;
+    metricKey?: string;
+    bucketWidth?: string;
+    bucketResolution?: number;
+    windowWidth?: string;
+  }): Promise<MMAggregatedPartCountBucket[]> {
+    const metricKey =
+      options.metricKey?.trim() || MM_DEFAULT_PART_COUNT_METRIC_KEY;
+    const query = buildAggregatedPartCountsQuery({
+      machineRef: options.machineRef,
+      metricKey,
+      windowStartAt: options.windowStartAt,
+      windowEndAt: options.windowEndAt,
+      bucketWidth: options.bucketWidth,
+      bucketResolution: options.bucketResolution,
+      windowWidth: options.windowWidth,
+    });
+    const response = (await this.graphqlRequest(
+      "aggregatedPartCountsForMachine",
+      query
+    )) as { data?: { aggregatedPartCounts?: unknown } };
+    const list = response.data?.aggregatedPartCounts;
+    if (!Array.isArray(list)) {
+      throw new Error(
+        "fetchAggregatedPartCountsForMachine: missing data.aggregatedPartCounts array"
+      );
+    }
+    return list.map(parseAggregatedPartCountBucketRow);
+  }
+
+  /**
+   * Resolves the REST **`machine_id`** for **part adjustment** and other MM REST calls that take
+   * `machine_id`, using GraphQL `machines` where `machineRef` matches. Docs often describe this as a UUID;
+   * this method does not validate a particular string format—only that the GraphQL field is a non-empty string.
+   *
+   * @param machineRef - Numeric MM `machineRef`. Non-finite values throw.
+   * @returns Trimmed `machine_id` string, or `null` if no row, unmapped machine, or when `machineId` is
+   *   missing, empty after trim, or not a string (avoids coercing arbitrary JSON values to strings).
+   * @throws {RangeError} When `machineRef` is not finite.
+   * @throws {Error} When GraphQL returns errors.
+   */
+  async fetchMachineIdForMachineRef(
+    machineRef: number
+  ): Promise<string | null> {
+    const ref = Math.trunc(Number(machineRef));
+    if (!Number.isFinite(ref)) {
+      throw new RangeError("fetchMachineIdForMachineRef: machineRef must be finite");
+    }
+    const query = `query mmMachineIdByRef { machines(where: { machineRef: { _eq: ${ref} } }, limit: 1) { machineId } }`;
+    const response = (await this.graphqlRequest(
+      "mmMachineIdByRef",
+      query
+    )) as { data?: { machines?: unknown } };
+    const list = response.data?.machines;
+    if (!Array.isArray(list) || list.length === 0) {
+      return null;
+    }
+    const row = list[0];
+    if (typeof row !== "object" || row === null) {
+      return null;
+    }
+    const o = row as Record<string, unknown>;
+    const mid = o.machineId;
+    if (typeof mid !== "string") {
+      return null;
+    }
+    const s = mid.trim();
+    return s || null;
+  }
+
   /**
    * Cleanup all HTTP connections and resources
    * Call this when the service is no longer needed
@@ -869,3 +1002,32 @@ export class MMApiClient {
 
   //#endregion public methods
 }
+
+function parseMappedErpResourceRow(raw: unknown): MMMappedErpResourceRow {
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error("fetchMappedErpResourcesForCompany: invalid row");
+  }
+  const o = raw as Record<string, unknown>;
+  const refRaw = o.machineRef;
+  const ref = typeof refRaw === "number" ? refRaw : Number(refRaw);
+  if (!Number.isFinite(ref)) {
+    throw new Error("fetchMappedErpResourcesForCompany: invalid machineRef");
+  }
+  const rid = o.resourceId;
+  return {
+    isResourceGroup: Boolean(o.isResourceGroup),
+    machineGroupId:
+      o.machineGroupId === null || o.machineGroupId === undefined
+        ? null
+        : String(o.machineGroupId),
+    machineRef: Math.trunc(ref),
+    resourceId:
+      rid === null || rid === undefined
+        ? null
+        : typeof rid === "string"
+          ? rid.trim() || null
+          : String(rid).trim() || null,
+    name: typeof o.name === "string" ? o.name : null,
+    type: o.type === null || o.type === undefined ? null : String(o.type),
+  };
+}

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

@@ -0,0 +1,33 @@
+import { GraphQLError } from "../erp-api-services/errors.js";
+import type { GraphQLServerError } from "../erp-api-services/graphql/types.js";
+
+/**
+ * JSON body for POST to MM API `/proxy/graphql` (MachineMetrics GraphQL proxy).
+ * Used only by `MMApiClient` (not exported from the public SDK entrypoint).
+ */
+export function buildMmGraphqlProxyRequestBody(
+  operationName: string,
+  query: string,
+  variables?: Record<string, unknown>
+): Record<string, unknown> {
+  const body: Record<string, unknown> = { operationName, query };
+  if (variables !== undefined && Object.keys(variables).length > 0) {
+    body.variables = variables;
+  }
+  return body;
+}
+
+/**
+ * GraphQL-over-HTTP often returns **HTTP 200** with a top-level `errors` array and partial or null `data`.
+ * Axios treats that as success, so callers must inspect the envelope.
+ *
+ * @throws {GraphQLError} when `errors` is a non-empty array
+ */
+export function assertMmGraphqlProxyResponseHasNoErrors(
+  response: Record<string, unknown>
+): void {
+  const errors = response.errors;
+  if (Array.isArray(errors) && errors.length > 0) {
+    throw new GraphQLError("GraphQL Error", errors as GraphQLServerError[]);
+  }
+}

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

@@ -24,12 +24,7 @@ export class MMTokenManager {
       ? new Date(cached.expiration)
       : null;
     const config = CoreConfiguration.inst();
-    console.log("=== MMTOKEN MANAGER DEBUG ===");
-    console.log("config.mmApiBaseUrl:", config.mmApiBaseUrl);
-    console.log("config object keys:", Object.keys(config));
     this.baseUrl = config.mmApiBaseUrl;
-    console.log("this.baseUrl set to:", this.baseUrl);
-    console.log("=== END MMTOKEN MANAGER DEBUG ===");
     this.api = HTTPClientFactory.getInstance({
       baseUrl: this.baseUrl,
       retryAttempts: config.mmApiRetryAttempts,

package/src/services/mm-api-service/types/mm-response-interfaces.ts

@@ -331,6 +331,41 @@ export interface MMGraphQLWorkOrderResponse extends MMApiBaseResponse {
   };
 }
 
+/**
+ * ERP resources for a company with a mapped MM machine (`machineRef` present).
+ */
+export interface MMMappedErpResourceRow {
+  isResourceGroup: boolean;
+  machineGroupId: string | null;
+  machineRef: number;
+  /** ERP resource id when exposed by GraphQL (connector-specific meaning). */
+  resourceId: string | null;
+  /** Display name from GraphQL; null when absent or not a string (callers may default for UI). */
+  name: string | null;
+  type: string | null;
+}
+
+/**
+ * One time bucket row from GraphQL `aggregatedPartCounts` for a single `machineRef` and `metricKey`.
+ * Window and bucket shape follow the MM GraphQL schema (see MachineMetrics GraphQL docs).
+ */
+export interface MMAggregatedPartCountBucket {
+  machineRef: number;
+  metricKey: string;
+  /** Sum of metric values across events in this bucket. */
+  sumOfValues: number;
+  /** Number of contributing events in this bucket. */
+  eventCount: number;
+  bucketStartAt: string;
+  bucketEndAt: string;
+  /** Duration string for this bucket when the API provides it (may be empty). */
+  bucketWidth: string;
+  /** Optional gauge at bucket start; null when not applicable. */
+  firstValue: number | null;
+  /** Optional gauge at bucket end; null when not applicable. */
+  lastValue: number | null;
+}
+
 /**
  * Response for machine groups fetch
  * Used by fetchMachineGroups() method

package/src/utils/resource-group.ts

@@ -1,4 +1,5 @@
 import { sdkLogger as logger } from "../services/reporting-service/logger.js";
+import { GraphQLError } from "../services/erp-api-services/errors.js";
 import {
   MMApiClient,
   MMGraphQLResourceResponse,
@@ -22,8 +23,20 @@ export async function getResourceERPGroupId(
 ): Promise<string | undefined> {
   try {
     // Get the ERP resources to map resource IDs to machine refs
-    const erpResources =
-      (await client.fetchResourcesFromGraphQL()) as MMGraphQLResourceResponse;
+    let erpResources: MMGraphQLResourceResponse;
+    try {
+      erpResources =
+        (await client.fetchResourcesFromGraphQL()) as MMGraphQLResourceResponse;
+    } catch (error) {
+      if (error instanceof GraphQLError) {
+        logger.warn(
+          "ERP resources GraphQL request failed; cannot resolve resource group",
+          { resourceId, graphqlErrors: error.errors }
+        );
+        return undefined;
+      }
+      throw error;
+    }
     if (!erpResources?.data?.machineResource) {
       logger.error("Failed to fetch ERP resources");
       return undefined;