@webimpian/log-central-node 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Webimpian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# Log Central for Node.js
+
+[![npm version](https://img.shields.io/npm/v/@webimpian/log-central-node.svg)](https://www.npmjs.com/package/@webimpian/log-central-node)
+[![License](https://img.shields.io/npm/l/@webimpian/log-central-node.svg)](LICENSE.md)
+
+Ship logs and errors from any Node.js application to a [Log Central](https://log.dev-aplikasiniaga.com) server.
+
+- **General-purpose client** — leveled logging (`debug` … `emergency`) and exception capture from any Node.js 18+ process. Zero dependencies.
+- **Non-blocking by design** — entries are batched in memory and flushed in the background with capped exponential backoff. Delivery failures are silent and bounded; logging can never crash or slow the host application.
+- **ZoneMTA?** — use [`@webimpian/zonemta-log-central`](https://www.npmjs.com/package/@webimpian/zonemta-log-central), a ZoneMTA plugin built on this client.
+
+## Installation
+
+```bash
+npm install @webimpian/log-central-node
+```
+
+Requires Node.js 18+ (uses global `fetch`) and a Log Central project key — create an app on the [dashboard](https://log.dev-aplikasiniaga.com) to obtain one.
+
+## Usage
+
+```js
+const { LogCentralClient } = require('@webimpian/log-central-node');
+
+const logs = new LogCentralClient({
+    url: 'https://logs.example.com/api',
+    token: 'your-project-key',
+    app: 'your-app-slug',
+    environment: 'production',
+    channel: 'app',
+});
+
+// Leveled logging (debug, info, notice, warning, error, critical, alert, emergency)
+logs.info('Callback received', { ref: 'BC-8231' });
+logs.warning('Retrying webhook', { attempt: 3 }, { channel: 'webhook', traceId: 'tr-91' });
+
+// Exception capture (fingerprinted, grouped by the error tracker)
+try {
+    await processPayment(order);
+} catch (err) {
+    logs.captureException(err, { entrypoint: 'queue', context: { orderId: order.id } });
+    throw err;
+}
+
+// Optional: flush before shutdown
+process.on('SIGTERM', () => logs.close());
+```
+
+## Options
+
+| Option | Default | Purpose |
+|---|---|---|
+| `url` | *(required)* | Log Central ingest base URL, e.g. `https://logs.example.com/api` |
+| `token` | *(required)* | The app's project key (bearer token) |
+| `app` | *(required)* | The app's slug, must match the token's app |
+| `environment` | `production` | Environment tag on every entry |
+| `channel` | `app` | Default log channel |
+| `hostname` | `os.hostname()` | Hostname tag on every entry |
+| `batchSize` | `200` | Entries per POST (hard-capped at the server's 1,000) |
+| `flushInterval` | `5000` | Background flush period in ms |
+| `maxQueue` | `10000` | Max buffered entries per type; oldest are dropped beyond this |
+| `requestTimeout` | `10000` | Per-request timeout in ms |
+| `onError` | `null` | Callback invoked with delivery/rejection errors (for debugging) |
+
+Delivery semantics: batches that fail with a network error or 5xx stay queued and retry with capped backoff (max 60s); batches rejected with a 4xx are dropped (retrying cannot fix them) and reported to `onError`.
+
+## Testing
+
+```bash
+npm test
+```
+
+## License
+
+MIT — see [LICENSE.md](LICENSE.md).

package/lib/client.js

@@ -0,0 +1,277 @@
+'use strict';
+
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+const LEVELS = ['debug', 'info', 'notice', 'warning', 'error', 'critical', 'alert', 'emergency'];
+
+const LEVEL_ALIASES = {
+    warn: 'warning',
+    err: 'error',
+    fatal: 'critical',
+    trace: 'debug',
+    verbose: 'debug',
+};
+
+const ENTRYPOINTS = ['http', 'console', 'queue'];
+
+const MAX_BATCH = 1000;
+
+function formatTimestamp(date = new Date()) {
+    const pad = (value, width = 2) => String(value).padStart(width, '0');
+
+    return (
+        `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())} ` +
+        `${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())}.` +
+        pad(date.getUTCMilliseconds(), 3)
+    );
+}
+
+function safeStringify(value) {
+    const seen = new WeakSet();
+
+    try {
+        const json = JSON.stringify(value ?? {}, (key, entry) => {
+            if (typeof entry === 'bigint') {
+                return entry.toString();
+            }
+
+            if (typeof entry === 'object' && entry !== null) {
+                if (seen.has(entry)) {
+                    return '[circular]';
+                }
+
+                seen.add(entry);
+            }
+
+            return entry;
+        });
+
+        return json === undefined ? '{}' : json;
+    } catch {
+        return '{}';
+    }
+}
+
+function md5(value) {
+    return crypto.createHash('md5').update(value).digest('hex');
+}
+
+function firstStackFrame(stack) {
+    for (const line of String(stack).split('\n').slice(1)) {
+        const match = /^\s*at\s+(?:.+?\s+\()?(.+?):(\d+):\d+\)?\s*$/.exec(line);
+
+        if (match) {
+            return { file: match[1], line: Number(match[2]) };
+        }
+    }
+
+    return { file: '', line: 0 };
+}
+
+class LogCentralClient {
+    constructor(options = {}) {
+        for (const required of ['url', 'token', 'app']) {
+            if (!options[required] || typeof options[required] !== 'string') {
+                throw new TypeError(`LogCentralClient: option '${required}' is required`);
+            }
+        }
+
+        this.url = options.url.replace(/\/+$/, '');
+        this.token = options.token;
+        this.app = options.app;
+        this.environment = options.environment || 'production';
+        this.channel = options.channel || 'app';
+        this.hostname = options.hostname || os.hostname();
+        this.batchSize = Math.min(options.batchSize || 200, MAX_BATCH);
+        this.flushInterval = options.flushInterval || 5000;
+        this.maxQueue = options.maxQueue || 10000;
+        this.requestTimeout = options.requestTimeout || 10000;
+        this.onError = typeof options.onError === 'function' ? options.onError : null;
+        this.fetch = options.fetch || globalThis.fetch;
+
+        this.queues = { logs: [], errors: [], requests: [] };
+        this.dropped = 0;
+        this.failures = 0;
+        this.retryAt = 0;
+        this.flushing = null;
+
+        this.timer = setInterval(() => {
+            this.flush().catch(() => {});
+        }, this.flushInterval);
+
+        if (typeof this.timer.unref === 'function') {
+            this.timer.unref();
+        }
+    }
+
+    log(level, message, context = {}, overrides = {}) {
+        let normalized = String(level).toLowerCase();
+        normalized = LEVEL_ALIASES[normalized] || normalized;
+
+        if (!LEVELS.includes(normalized)) {
+            normalized = 'info';
+        }
+
+        const entry = {
+            timestamp: overrides.timestamp || formatTimestamp(),
+            app: this.app,
+            environment: overrides.environment || this.environment,
+            channel: overrides.channel || this.channel,
+            level: normalized,
+            message: String(message ?? ''),
+            context: safeStringify(context),
+            hostname: overrides.hostname || this.hostname,
+        };
+
+        if (overrides.traceId) {
+            entry.trace_id = String(overrides.traceId);
+        }
+
+        this.enqueue('logs', entry);
+    }
+
+    captureException(err, extra = {}) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        const stack = error.stack || '';
+        const frame = firstStackFrame(stack);
+        const name = error.name || 'Error';
+
+        const entry = {
+            timestamp: extra.timestamp || formatTimestamp(),
+            fingerprint: md5(`${name}|${frame.file}|${frame.line}`),
+            app: this.app,
+            environment: extra.environment || this.environment,
+            exception: name,
+            message: String(error.message ?? ''),
+            file: frame.file,
+            line: frame.line,
+            trace: stack,
+            url: extra.url || '',
+            method: extra.method || 'CLI',
+            user_id: Number.isInteger(extra.userId) && extra.userId >= 0 ? extra.userId : 0,
+            input: safeStringify(extra.context ?? {}),
+            hostname: extra.hostname || this.hostname,
+            entrypoint: ENTRYPOINTS.includes(extra.entrypoint) ? extra.entrypoint : 'console',
+        };
+
+        if (extra.ip) {
+            entry.ip = String(extra.ip);
+        }
+
+        if (extra.userAgent) {
+            entry.user_agent = String(extra.userAgent);
+        }
+
+        if (extra.user) {
+            entry.user = safeStringify(extra.user);
+        }
+
+        this.enqueue('errors', entry);
+    }
+
+    enqueue(type, entry) {
+        const queue = this.queues[type];
+
+        if (!queue) {
+            throw new TypeError(`LogCentralClient: unknown entry type '${type}'`);
+        }
+
+        if (queue.length >= this.maxQueue) {
+            queue.shift();
+            this.dropped++;
+        }
+
+        queue.push(entry);
+
+        if (queue.length >= this.batchSize) {
+            this.flush().catch(() => {});
+        }
+    }
+
+    async flush() {
+        if (this.flushing) {
+            return this.flushing;
+        }
+
+        if (Date.now() < this.retryAt) {
+            return;
+        }
+
+        this.flushing = this.#drain().finally(() => {
+            this.flushing = null;
+        });
+
+        return this.flushing;
+    }
+
+    async close() {
+        clearInterval(this.timer);
+        this.retryAt = 0;
+        await this.flush();
+    }
+
+    async #drain() {
+        for (const type of Object.keys(this.queues)) {
+            const queue = this.queues[type];
+
+            while (queue.length > 0) {
+                const batch = queue.slice(0, this.batchSize);
+                let response;
+
+                try {
+                    response = await this.fetch(`${this.url}/${type}`, {
+                        method: 'POST',
+                        headers: {
+                            authorization: `Bearer ${this.token}`,
+                            'content-type': 'application/json',
+                        },
+                        body: JSON.stringify(batch),
+                        signal: AbortSignal.timeout(this.requestTimeout),
+                    });
+                } catch (err) {
+                    this.#backoff(err);
+                    return;
+                }
+
+                if (response.status >= 500) {
+                    this.#backoff(new Error(`Log Central responded ${response.status}`));
+                    return;
+                }
+
+                queue.splice(0, batch.length);
+                this.failures = 0;
+                this.retryAt = 0;
+
+                if (response.status >= 400) {
+                    const body = await response.text().catch(() => '');
+                    this.#report(new Error(`Log Central rejected a ${type} batch (${response.status}): ${body.slice(0, 200)}`));
+                }
+            }
+        }
+    }
+
+    #backoff(err) {
+        this.failures++;
+        this.retryAt = Date.now() + Math.min(2 ** this.failures * 1000, 60000);
+        this.#report(err);
+    }
+
+    #report(err) {
+        if (this.onError) {
+            try {
+                this.onError(err);
+            } catch {
+                // onError must never take the client down
+            }
+        }
+    }
+}
+
+for (const level of LEVELS) {
+    LogCentralClient.prototype[level] = function (message, context = {}, overrides = {}) {
+        this.log(level, message, context, overrides);
+    };
+}
+
+module.exports = { LogCentralClient, formatTimestamp, safeStringify, LEVELS, MAX_BATCH };

package/lib/index.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { LogCentralClient, formatTimestamp, safeStringify, LEVELS } = require('./client');
+
+module.exports = { LogCentralClient, formatTimestamp, safeStringify, LEVELS };

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "@webimpian/log-central-node",
+    "version": "1.0.0",
+    "description": "Ship logs and errors from Node.js applications to a Log Central server.",
+    "keywords": [
+        "logging",
+        "error-tracking",
+        "log-central"
+    ],
+    "license": "MIT",
+    "author": "Khairul Imran <infrastructure@webimpian.com>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/webimpian-os/log-central-node.git"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "main": "lib/index.js",
+    "exports": {
+        ".": "./lib/index.js"
+    },
+    "files": [
+        "lib",
+        "LICENSE.md",
+        "README.md"
+    ],
+    "scripts": {
+        "test": "node --test"
+    }
+}