@mcesystems/logging-g4 1.0.69 → 1.0.71

package/Example.md

@@ -0,0 +1,44 @@
+# Logging examples
+
+This document describes the examples in `src/example/` and how to run them.
+
+## sendLog.ts
+
+**Purpose:** Send a single log event using the default batch schedule.
+
+**Setup:** Set in `.env` or environment:
+
+- `CREDENTIALS_PATH` — path to credentials file
+- `LOGGING_API_URL` — logging API base URL
+- `AUTH_API_URL` — auth API URL
+
+Optional for this example: `TIME_BETWEEN_LOG`, `MAX_OFFLINE_TIME`, `CACHED_EVENTS_PATH` (defaults: 10 min, 1 hour; `CACHED_EVENTS_PATH` must be set).
+
+**Run (from package root):**
+
+```bash
+pnpm exec tsx src/example/sendLog.ts
+```
+
+**Behavior:** Creates a `LogClient`, calls `logEvent()` once with a test event. Returns `"delayed"`; the event is queued and sent at the next cron boundary.
+
+## sendBatchAfterOneMinute.ts
+
+**Purpose:** Queue a batch of log events with a 15-second gap between each, and show the time when the batch is really sent (at the next 1-minute boundary).
+
+**Setup:** Same as sendLog. The example sets `TIME_BETWEEN_LOG=60000` (1 minute) and `CACHED_EVENTS_PATH` to a temp file if not set.
+
+**Run (from package root):**
+
+```bash
+pnpm exec tsx src/example/sendBatchAfterOneMinute.ts
+```
+
+**Behavior:**
+
+1. Logs the scheduled send time (next 1-minute boundary).
+2. Queues three events: "First event", "Second event", "Third event", with 15 seconds between each. Each log line includes the queue time.
+3. Waits until after the boundary so the cron sends the batch.
+4. Logs "Batch was sent at: <time>" with the boundary time.
+
+Use this to verify batching and cron-style send times.

package/README.md

@@ -1,23 +1,71 @@
 # @mcesystems/logging-g4
 
-Node-only logging client that sends events to the MCE logging service.
+## 1. Description
 
-## Install
+**What it does:** Node-only logging client that sends events to the MCE logging service. Events are queued and sent in batches on a cron-style schedule (e.g. every 10 minutes at fixed clock boundaries). Failed sends (401, network errors) are persisted to disk and retried on the next run. If the service stays offline longer than `MAX_OFFLINE_TIME`, the client throws.
 
-```
+**When it's used:** Use this package when your application needs to send structured log events to the MCE logging service with batching, persistence, and offline handling—for example device management tools or services that must not lose logs when the API is temporarily unavailable.
+
+## 2. Install
+
+```bash
 pnpm add @mcesystems/logging-g4
 ```
 
-## Usage (Node only)
+**Requirements:** Node.js 18+. This package uses Node APIs (`fs`, `os`, `path`) and is not compatible with browsers or other non-Node runtimes.
+
+## 3. Resources
+
+No binary resources are required. You need a credentials file (see Setup) and network access to the auth and logging APIs.
+
+## 4. Examples
+
+**Single event**
+
+```bash
+pnpm exec tsx src/example/sendLog.ts
+```
+
+Uses `CREDENTIALS_PATH`, `LOGGING_API_URL`, `AUTH_API_URL` from `.env` or environment. Sends one event; returns `"delayed"` (event queued for next scheduled send).
 
-This package uses Node APIs (`fs`, `os`, `path`) and environment variables. It is not
-compatible with browsers or other non-Node runtimes.
+**Batch after 1 minute (with 15s gap between events)**
 
+```bash
+pnpm exec tsx src/example/sendBatchAfterOneMinute.ts
 ```
+
+Queues three events with a 15-second gap between each; shows the time when the batch is sent at the next 1-minute boundary. Sets `TIME_BETWEEN_LOG=60000` and `CACHED_EVENTS_PATH` to a temp file if not set.
+
+For step-by-step explanations and scenarios, see [Example.md](./Example.md).
+
+## 5. API
+
+### LogClient
+
+**Constructor**
+
+- **Input:** none
+- **Output:** new `LogClient` instance. Call `logEvent()` after creation; `init()` runs on first `logEvent()` if needed.
+
+**logEvent(event)**
+
+- **Input:** `event` — object with `event_severity`, `event_type`, `event_info`, `context` (and optional fields). Omit `event_id`, `event_time`, `framework_id`, `event_source`; they are set by the client.
+- **Output:** `Promise<LogSendResult>` — always `"delayed"` (event queued for next scheduled send). No immediate send. The outcomes `"success"` and `"MAX_OFFLINE_TIME passed"` occur inside the cron job: when `MAX_OFFLINE_TIME` is exceeded, `sendBatch()` throws so the process receives the exception.
+
+### LogSendResult
+
+Type: `"success" | "MAX_OFFLINE_TIME passed" | "delayed"`. Exported for typing; `logEvent()` returns `"delayed"` only.
+
+## 6. Flow
+
+Example flow: create client, queue several events, let the cron send the batch at the next boundary.
+
+```typescript
 import { LogSeverity } from "@mcesystems/logging-interfaces/lib/sdk";
 import { LogClient } from "@mcesystems/logging-g4";
 
 const logClient = new LogClient();
+
 await logClient.logEvent({
 	event_severity: LogSeverity.Info,
 	event_type: "device_connected",
@@ -26,8 +74,33 @@ await logClient.logEvent({
 		source: "device-manager",
 		timestamp: new Date().toISOString(),
 	},
-	context: {
-		deviceId: "abc123",
-	},
+	context: { deviceId: "abc123" },
 });
+// result is "delayed" — batch will be sent at next TIME_BETWEEN_LOG boundary
+
+await logClient.logEvent({
+	event_severity: LogSeverity.Info,
+	event_type: "device_disconnected",
+	event_info: { message: "Device disconnected", timestamp: new Date().toISOString() },
+	context: { deviceId: "abc123" },
+});
+// both events are queued; cron sends the batch at the next boundary
 ```
+
+## 7. Setup
+
+**Environment variables**
+
+- **TIME_BETWEEN_LOG** (ms): Interval between batch send attempts. Sends run at fixed clock boundaries (e.g. 10 min → 13:50, 14:00, 14:10). Default: 10 minutes.
+- **MAX_OFFLINE_TIME** (ms): After this many ms since the first send failure, the client throws. If the batch was successfully persisted and still within this window, no throw. Default: 1 hour.
+- **CACHED_EVENTS_PATH**: Path to a single JSON file for pending (delayed) events. **Required.** Delayed batches are written here on send failure and loaded on the next run; file is deleted after a successful send.
+- **CREDENTIALS_PATH**: Path to credentials file used by `@mcesystems/auth-g4`. Required for auth.
+- **LOGGING_API_URL**: Logging API base URL. Required.
+- **AUTH_API_URL**: Auth API URL for token. Required.
+
+**Resources location:** None. Credentials file path is given by `CREDENTIALS_PATH`. Pending events file path is given by `CACHED_EVENTS_PATH`.
+
+## 8. TODO
+
+- [ ] Optional: Expand Example.md with more scenarios (e.g. offline handling, MAX_OFFLINE_TIME).
+- [ ] Optional: Token refresh on 401 before persisting and retrying.

package/dist/index.js

@@ -21437,16 +21437,80 @@ function v4(options, buf, offset) {
 }
 var v4_default = v4;
 
+// src/logic/cronSchedule.ts
+function getNextCronRun(intervalMs) {
+  const now = Date.now();
+  const midnight = new Date(now);
+  midnight.setHours(0, 0, 0, 0);
+  const msSinceMidnight = now - midnight.getTime();
+  const nextBoundaryMs = Math.ceil(msSinceMidnight / intervalMs) * intervalMs;
+  let nextRun = midnight.getTime() + nextBoundaryMs;
+  if (nextRun <= now) {
+    nextRun += intervalMs;
+  }
+  return nextRun;
+}
+
+// src/logic/pendingEventsStorage.ts
+var import_promises = require("node:fs/promises");
+async function readPendingEvents(filePath) {
+  try {
+    const data = await (0, import_promises.readFile)(filePath, "utf-8");
+    return JSON.parse(data);
+  } catch (error) {
+    const err = error;
+    if (err.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+async function writePendingEvents(filePath, events) {
+  await (0, import_promises.writeFile)(filePath, JSON.stringify(events), "utf-8");
+}
+async function deletePendingEvents(filePath) {
+  try {
+    await (0, import_promises.unlink)(filePath);
+  } catch (error) {
+    const err = error;
+    if (err.code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
 // src/logic/logClient.ts
 var LogClient = class {
   credentials;
   loggingClient;
-  offlinetime;
   cachedEvents = [];
   initialized = false;
+  firstOfflineTime;
+  sendTimeoutId;
+  timeBetweenLogMs;
+  maxOfflineTimeMs;
+  pendingEventsPath;
+  sendInProgress = false;
+  schedulerStarted = false;
   async init() {
     setLogLevel2(process.env.LOG_LEVEL ?? "none");
     logNamespace2("logging");
+    if (typeof this.timeBetweenLogMs !== "number") {
+      const DEFAULT_TIME_BETWEEN_LOG_MS = 10 * 60 * 1e3;
+      const DEFAULT_MAX_OFFLINE_TIME_MS = 60 * 60 * 1e3;
+      const timeBetweenLog = process.env.TIME_BETWEEN_LOG;
+      const maxOfflineTime = process.env.MAX_OFFLINE_TIME;
+      const cachedEventsPath = process.env.CACHED_EVENTS_PATH;
+      if (!cachedEventsPath) {
+        throw new Error("CACHED_EVENTS_PATH must be set");
+      }
+      this.timeBetweenLogMs = Number(timeBetweenLog) || DEFAULT_TIME_BETWEEN_LOG_MS;
+      this.maxOfflineTimeMs = Number(maxOfflineTime) || DEFAULT_MAX_OFFLINE_TIME_MS;
+      this.pendingEventsPath = cachedEventsPath;
+      if (!Number.isFinite(this.timeBetweenLogMs) || this.timeBetweenLogMs <= 0 || !Number.isFinite(this.maxOfflineTimeMs) || this.maxOfflineTimeMs <= 0) {
+        throw new Error("TIME_BETWEEN_LOG and MAX_OFFLINE_TIME must be positive numbers");
+      }
+    }
     const os4 = await import("node:os");
     const path = await import("node:path");
     const fs = await import("node:fs/promises");
@@ -21485,18 +21549,81 @@ var LogClient = class {
     } else {
       token = tokenFile.token;
     }
-    if (!token) {
-      throw new Error("Token not found");
-    }
-    try {
+    if (token) {
       const loggingApi = process.env.LOGGING_API_URL ?? "";
       if (!loggingApi) {
         throw new Error("LOGGING_API_URL is not set");
       }
       this.loggingClient = new import_gql_logging_client.default(loggingApi, token.accessToken);
       this.initialized = true;
-    } catch (error) {
-      logError2("Check your internet connection", error);
+    } else {
+      logError2("Check your internet connection - token not found");
+    }
+    if (!this.schedulerStarted) {
+      this.schedulerStarted = true;
+      this.scheduleNextRun();
+    }
+  }
+  scheduleNextRun() {
+    if (this.sendTimeoutId !== void 0) {
+      clearTimeout(this.sendTimeoutId);
+      this.sendTimeoutId = void 0;
+    }
+    const nextRun = getNextCronRun(this.timeBetweenLogMs);
+    const delay = Math.max(0, nextRun - Date.now());
+    this.sendTimeoutId = setTimeout(() => {
+      void this.runScheduledSend();
+    }, delay);
+  }
+  async runScheduledSend() {
+    try {
+      await this.sendBatch();
+    } catch {
+      this.sendTimeoutId = void 0;
+      return;
+    }
+    this.scheduleNextRun();
+  }
+  async sendBatch() {
+    if (this.sendInProgress) {
+      return;
+    }
+    this.sendInProgress = true;
+    try {
+      const loaded = await readPendingEvents(this.pendingEventsPath);
+      const batch = [...this.cachedEvents, ...loaded];
+      this.cachedEvents = [];
+      if (batch.length === 0) {
+        this.firstOfflineTime = void 0;
+        return;
+      }
+      if (!this.loggingClient) {
+        if (this.firstOfflineTime === void 0) {
+          this.firstOfflineTime = Date.now();
+        }
+        await writePendingEvents(this.pendingEventsPath, batch);
+        if (Date.now() - this.firstOfflineTime > this.maxOfflineTimeMs) {
+          throw new Error("Exceeded max offline time");
+        }
+        return;
+      }
+      try {
+        await this.loggingClient.mutate({ events: batch }).promise();
+        await deletePendingEvents(this.pendingEventsPath);
+        this.firstOfflineTime = void 0;
+        logInfo2(`Logging batch result: ${batch.length} events sent`);
+      } catch (error) {
+        logError2("Send batch failed", error);
+        if (this.firstOfflineTime === void 0) {
+          this.firstOfflineTime = Date.now();
+        }
+        await writePendingEvents(this.pendingEventsPath, batch);
+        if (Date.now() - this.firstOfflineTime > this.maxOfflineTimeMs) {
+          throw new Error("Exceeded max offline time");
+        }
+      }
+    } finally {
+      this.sendInProgress = false;
     }
   }
   async logEvent(event) {
@@ -21513,34 +21640,8 @@ var LogClient = class {
       ...event
     };
     logDataObject("Logging event", newEvent);
-    if (!this.loggingClient) {
-      logError2("Logging client not initialized");
-      if (!this.offlinetime) {
-        this.offlinetime = Date.now();
-      } else if (Date.now() - this.offlinetime > +(process.env.OFFLINE_TIME ?? 1e3 * 60 * 60)) {
-        if (process.env.APP_TYPE === "node") {
-          const { writeFile } = await import("node:fs/promises");
-          if (!process.env.CACHED_EVENTS_PATH) {
-            throw new Error("CACHED_EVENTS_PATH is not set");
-          }
-          await writeFile(
-            `${process.env.CACHED_EVENTS_PATH}-${Date.now()}.json`,
-            JSON.stringify(this.cachedEvents)
-          );
-          logInfo2(`Cached events saved to: ${process.env.CACHED_EVENTS_PATH}`);
-          this.offlinetime = Date.now();
-          this.cachedEvents = [];
-        }
-      }
-      this.cachedEvents.push(newEvent);
-      return;
-    }
-    const result = await this.loggingClient.mutate({
-      events: [newEvent, ...this.cachedEvents]
-    }).promise();
-    this.cachedEvents = [];
-    logInfo2(`Logging event result: ${JSON.stringify(result)}`);
-    return result;
+    this.cachedEvents.push(newEvent);
+    return "delayed";
   }
 };
 // Annotate the CommonJS export names for ESM import in node: