@mcesystems/logging-g4 1.0.70 → 1.0.72

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.