@lib-acr/node 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Application Control Room
+
+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

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @lib-acr/node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ACR SDK for Node.js: everything in @lib-acr/core, plus runtime heartbeats (CPU, memory, event loop, GC), capture of uncaught exceptions and unhandled rejections, and a flush on exit.
+
+## Install
+
+```bash
+npm install @lib-acr/node
+```
+
+## Quick start
+
+```ts
+import { ACR } from '@lib-acr/node';
+
+const acr = new ACR({
+  apiKey: process.env.ACR_API_KEY!,
+  apiSecret: process.env.ACR_API_SECRET!,
+  endpoint: 'https://acr.example.com/v1',
+  environment: 'production',
+  appVersion: '1.0.0',
+});
+
+acr.startHeartbeat();           // runtime snapshot every 30 s (configurable)
+acr.captureProcessErrors();     // uncaught exceptions flush, then exit(1) when no other handler exists
+acr.flushOnExit();              // flush once the event loop empties
+acr.trackEvent('order_created', { orderId: '123' });
+```
+
+## Notes
+
+Heartbeats are sent through `POST /ingest/heartbeat`. Each carries `instanceId` (default `<hostname>:<pid>`) and the runtime snapshot as attributes. Heartbeats follow the enable state: requested with `startHeartbeat()` while the client is disabled, they start as soon as `setEnabled(true)` is called, and pause again on `setEnabled(false)`.
+
+All core options apply, including `minLogLevel` (default `debug`) to drop low-level logs before they are buffered.
+
+## Remote control
+
+The client polls the control snapshot with the server key (see `@lib-acr/core`); the timers are unref'd and
+`shutdown()` stops them. The kill switch (`sdk.enabled: false`) pauses collection, flushing and heartbeats until it
+is lifted. Read maintenance and other state with `acr.getControlState()`, or answer `503` automatically with
+`maintenanceMiddleware` from `@lib-acr/express` or `ACRMaintenanceGuard` from `@lib-acr/nestjs`.
+
+## Feature flags
+
+```ts
+const enabled = acr.flag('new-checkout', false, { userId: req.user?.id });
+```
+
+Pass the request's user id: a server process has no current user. Without one, only flags rolled out to 100 % serve
+their value; partial rollouts serve the default.
+
+## Wire protocol
+
+Every SDK sends the same protocol: `POST {endpoint}/ingest/{events|logs|errors|heartbeat}` with the `X-ACR-Api-Key`
+header (and `X-ACR-Secret-Key` for server keys). The credential determines the app and environment. The body is
+`{ schemaVersion: 1, sdk, items[1..500] }`.
+Each item has a client `id`, which lets the server drop duplicates when a batch is retried.
+
+Retries use exponential backoff with jitter for network errors, 429 and 5xx responses. Other 4xx responses are not retried.
+Telemetry is buffered in a bounded in-memory queue. When it is full, the oldest items are dropped and counted in `stats()`.
+SDK code never throws into the host application.
+
+Metrics (`increment`, `gauge`, `histogram`) and traces are not yet available.

package/dist/cjs/acr.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACR = void 0;
+const node_os_1 = require("node:os");
+const core_1 = require("@lib-acr/core");
+const version_js_1 = require("./version.js");
+const runtime_js_1 = require("./runtime.js");
+/**
+ * Node.js client. Adds runtime heartbeats (CPU, memory, event loop, GC) and capture of unhandled errors on top of the
+ * shared core client.
+ */
+class ACR extends core_1.AcrClient {
+    /** `sdk` lets framework wrappers (Express, NestJS) report their own package name and version. */
+    constructor(options, sdk = version_js_1.NODE_SDK) {
+        super(options, sdk);
+        this.runtime = new runtime_js_1.RuntimeMonitor();
+        this.heartbeatTimer = null;
+        /** startHeartbeat() was called and stopHeartbeat() was not: heartbeats run whenever the client is enabled. */
+        this.heartbeatRequested = false;
+        this.processHooksInstalled = false;
+        this.instanceId = options.instanceId ?? `${(0, node_os_1.hostname)()}:${process.pid}`;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? 30000;
+        if (!Number.isFinite(this.heartbeatIntervalMs) || this.heartbeatIntervalMs < 1000) {
+            throw new Error('[acr] heartbeatIntervalMs must be at least 1000');
+        }
+    }
+    /**
+     * Sends one heartbeat with a runtime snapshot now, then one per interval. Safe to call twice. While the client is
+     * disabled no heartbeats are sent; they start as soon as it is enabled again.
+     */
+    startHeartbeat() {
+        this.heartbeatRequested = true;
+        this.resumeHeartbeat();
+    }
+    stopHeartbeat() {
+        this.heartbeatRequested = false;
+        this.pauseHeartbeat();
+    }
+    /**
+     * Starts or pauses heartbeats requested with startHeartbeat() whenever collection is switched on or off, locally
+     * (setEnabled) or by the remote kill switch.
+     */
+    onEnabledChange() {
+        if (!this.heartbeatRequested)
+            return;
+        if (this.isEnabled)
+            this.resumeHeartbeat();
+        else
+            this.pauseHeartbeat();
+    }
+    /** Current runtime snapshot, without sending anything. */
+    runtimeSnapshot() {
+        return this.runtime.snapshot();
+    }
+    /**
+     * Reports uncaught exceptions and unhandled promise rejections. Telemetry is flushed before an uncaught exception
+     * ends the process. When this SDK is the only handler, the process exits with code 1 as Node would have done.
+     */
+    captureProcessErrors(options = {}) {
+        if (this.processHooksInstalled)
+            return;
+        this.processHooksInstalled = true;
+        const exitOnUncaught = options.exitOnUncaughtException ?? true;
+        const timeoutMs = options.exitTimeoutMs ?? 2000;
+        const hadHandlers = process.listenerCount('uncaughtException') > 0;
+        process.on('uncaughtException', (error) => {
+            this.captureError(error, { handled: false, source: 'backend', attributes: { kind: 'uncaught_exception' } });
+            void this.flushWithin(timeoutMs).then(() => {
+                if (exitOnUncaught && !hadHandlers)
+                    process.exit(1);
+            });
+        });
+        process.on('unhandledRejection', (reason) => {
+            this.captureError(reason, { handled: false, source: 'backend', attributes: { kind: 'unhandled_rejection' } });
+        });
+    }
+    /** Flushes once when the event loop empties, so short-lived scripts do not lose their last batch. */
+    flushOnExit(timeoutMs = 2000) {
+        process.once('beforeExit', () => {
+            void this.flushWithin(timeoutMs);
+        });
+    }
+    async shutdown(timeoutMs) {
+        this.stopHeartbeat();
+        await super.shutdown(timeoutMs);
+    }
+    /** Flush that gives up after `timeoutMs` without closing the client. */
+    flushWithin(timeoutMs) {
+        let timer;
+        return Promise.race([
+            this.flush().catch(() => undefined),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, timeoutMs);
+                timer.unref?.();
+            }),
+        ]).finally(() => {
+            if (timer)
+                clearTimeout(timer);
+        });
+    }
+    /** Convenience for errors caught in application code. */
+    captureException(error, options = {}) {
+        this.captureError(error, { source: 'backend', ...options });
+    }
+    resumeHeartbeat() {
+        if (this.heartbeatTimer || !this.isEnabled)
+            return;
+        this.runtime.start();
+        this.beat();
+        this.heartbeatTimer = setInterval(() => this.beat(), this.heartbeatIntervalMs);
+        this.heartbeatTimer.unref?.();
+    }
+    pauseHeartbeat() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+        this.runtime.stop();
+    }
+    beat() {
+        const s = this.runtime.snapshot();
+        const { uptimeSeconds, ...attributes } = s;
+        this.heartbeat({ instanceId: this.instanceId, uptimeSeconds, attributes });
+    }
+}
+exports.ACR = ACR;
+//# sourceMappingURL=acr.js.map

package/dist/cjs/acr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acr.js","sourceRoot":"","sources":["../../src/acr.ts"],"names":[],"mappings":"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"}

package/dist/cjs/index.js

@@ -0,0 +1,25 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NODE_SDK = exports.RuntimeMonitor = exports.ACR = void 0;
+var acr_js_1 = require("./acr.js");
+Object.defineProperty(exports, "ACR", { enumerable: true, get: function () { return acr_js_1.ACR; } });
+var runtime_js_1 = require("./runtime.js");
+Object.defineProperty(exports, "RuntimeMonitor", { enumerable: true, get: function () { return runtime_js_1.RuntimeMonitor; } });
+var version_js_1 = require("./version.js");
+Object.defineProperty(exports, "NODE_SDK", { enumerable: true, get: function () { return version_js_1.NODE_SDK; } });
+__exportStar(require("@lib-acr/core"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,mCAA+B;AAAtB,6FAAA,GAAG,OAAA;AAEZ,2CAA8C;AAArC,4GAAA,cAAc,OAAA;AAEvB,2CAAwC;AAA/B,sGAAA,QAAQ,OAAA;AACjB,gDAA8B"}

package/dist/cjs/runtime.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeMonitor = void 0;
+const node_perf_hooks_1 = require("node:perf_hooks");
+/**
+ * Samples process health between calls to snapshot(). CPU, event loop utilization and GC counts cover the time since
+ * the previous snapshot, so each heartbeat reports its own interval.
+ */
+class RuntimeMonitor {
+    constructor() {
+        this.delay = (0, node_perf_hooks_1.monitorEventLoopDelay)({ resolution: 20 });
+        this.observer = null;
+        this.gcCount = 0;
+        this.lastCpu = process.cpuUsage();
+        this.lastHr = process.hrtime.bigint();
+        this.lastElu = node_perf_hooks_1.performance.eventLoopUtilization();
+        this.startedAt = Date.now();
+    }
+    start() {
+        this.delay.enable();
+        if (this.observer)
+            return;
+        try {
+            this.observer = new node_perf_hooks_1.PerformanceObserver((list) => {
+                this.gcCount += list.getEntries().length;
+            });
+            this.observer.observe({ entryTypes: ['gc'] });
+        }
+        catch {
+            this.observer = null;
+        }
+    }
+    stop() {
+        this.delay.disable();
+        this.observer?.disconnect();
+        this.observer = null;
+    }
+    snapshot(now = Date.now()) {
+        const mem = process.memoryUsage();
+        const cpu = process.cpuUsage(this.lastCpu);
+        const hr = process.hrtime.bigint();
+        const elapsedMicros = Number(hr - this.lastHr) / 1000;
+        const elu = node_perf_hooks_1.performance.eventLoopUtilization(this.lastElu);
+        const cpuPercent = elapsedMicros > 0 ? ((cpu.user + cpu.system) / elapsedMicros) * 100 : 0;
+        const p99 = this.delay.count > 0 ? this.delay.percentile(99) / 1e6 : 0;
+        this.delay.reset();
+        const gc = this.gcCount;
+        this.gcCount = 0;
+        this.lastCpu = process.cpuUsage();
+        this.lastHr = hr;
+        this.lastElu = node_perf_hooks_1.performance.eventLoopUtilization();
+        const handles = process.getActiveResourcesInfo?.().length ?? 0;
+        return {
+            uptimeSeconds: Math.max(0, Math.floor((now - this.startedAt) / 1000)),
+            rssBytes: mem.rss,
+            heapUsedBytes: mem.heapUsed,
+            heapTotalBytes: mem.heapTotal,
+            externalBytes: mem.external,
+            cpuPercent: round(Math.min(cpuPercent, 100 * 64)),
+            eventLoopUtilization: round(elu.utilization, 4),
+            eventLoopDelayP99Ms: round(Number.isFinite(p99) ? p99 : 0),
+            gcCount: gc,
+            activeHandles: handles,
+        };
+    }
+}
+exports.RuntimeMonitor = RuntimeMonitor;
+function round(value, digits = 2) {
+    const f = 10 ** digits;
+    return Math.round(value * f) / f;
+}
+//# sourceMappingURL=runtime.js.map

package/dist/cjs/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/cjs/sdk-info.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_INFO = void 0;
+// Generated by scripts/sync-sdk-info.mjs from package.json. Do not edit by hand.
+exports.SDK_INFO = { name: '@lib-acr/node', version: '0.0.1' };
+//# sourceMappingURL=sdk-info.js.map

package/dist/cjs/sdk-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-info.js","sourceRoot":"","sources":["../../src/sdk-info.ts"],"names":[],"mappings":";;;AAAA,iFAAiF;AACpE,QAAA,QAAQ,GAAG,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,OAAO,EAAW,CAAC"}

package/dist/cjs/version.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NODE_SDK = void 0;
+var sdk_info_js_1 = require("./sdk-info.js");
+Object.defineProperty(exports, "NODE_SDK", { enumerable: true, get: function () { return sdk_info_js_1.SDK_INFO; } });
+//# sourceMappingURL=version.js.map

package/dist/cjs/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":";;;AAAA,6CAAqD;AAA5C,uGAAA,QAAQ,OAAY"}

package/dist/esm/acr.js

@@ -0,0 +1,122 @@
+import { hostname } from 'node:os';
+import { AcrClient } from '@lib-acr/core';
+import { NODE_SDK } from './version.js';
+import { RuntimeMonitor } from './runtime.js';
+/**
+ * Node.js client. Adds runtime heartbeats (CPU, memory, event loop, GC) and capture of unhandled errors on top of the
+ * shared core client.
+ */
+export class ACR extends AcrClient {
+    /** `sdk` lets framework wrappers (Express, NestJS) report their own package name and version. */
+    constructor(options, sdk = NODE_SDK) {
+        super(options, sdk);
+        this.runtime = new RuntimeMonitor();
+        this.heartbeatTimer = null;
+        /** startHeartbeat() was called and stopHeartbeat() was not: heartbeats run whenever the client is enabled. */
+        this.heartbeatRequested = false;
+        this.processHooksInstalled = false;
+        this.instanceId = options.instanceId ?? `${hostname()}:${process.pid}`;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? 30000;
+        if (!Number.isFinite(this.heartbeatIntervalMs) || this.heartbeatIntervalMs < 1000) {
+            throw new Error('[acr] heartbeatIntervalMs must be at least 1000');
+        }
+    }
+    /**
+     * Sends one heartbeat with a runtime snapshot now, then one per interval. Safe to call twice. While the client is
+     * disabled no heartbeats are sent; they start as soon as it is enabled again.
+     */
+    startHeartbeat() {
+        this.heartbeatRequested = true;
+        this.resumeHeartbeat();
+    }
+    stopHeartbeat() {
+        this.heartbeatRequested = false;
+        this.pauseHeartbeat();
+    }
+    /**
+     * Starts or pauses heartbeats requested with startHeartbeat() whenever collection is switched on or off, locally
+     * (setEnabled) or by the remote kill switch.
+     */
+    onEnabledChange() {
+        if (!this.heartbeatRequested)
+            return;
+        if (this.isEnabled)
+            this.resumeHeartbeat();
+        else
+            this.pauseHeartbeat();
+    }
+    /** Current runtime snapshot, without sending anything. */
+    runtimeSnapshot() {
+        return this.runtime.snapshot();
+    }
+    /**
+     * Reports uncaught exceptions and unhandled promise rejections. Telemetry is flushed before an uncaught exception
+     * ends the process. When this SDK is the only handler, the process exits with code 1 as Node would have done.
+     */
+    captureProcessErrors(options = {}) {
+        if (this.processHooksInstalled)
+            return;
+        this.processHooksInstalled = true;
+        const exitOnUncaught = options.exitOnUncaughtException ?? true;
+        const timeoutMs = options.exitTimeoutMs ?? 2000;
+        const hadHandlers = process.listenerCount('uncaughtException') > 0;
+        process.on('uncaughtException', (error) => {
+            this.captureError(error, { handled: false, source: 'backend', attributes: { kind: 'uncaught_exception' } });
+            void this.flushWithin(timeoutMs).then(() => {
+                if (exitOnUncaught && !hadHandlers)
+                    process.exit(1);
+            });
+        });
+        process.on('unhandledRejection', (reason) => {
+            this.captureError(reason, { handled: false, source: 'backend', attributes: { kind: 'unhandled_rejection' } });
+        });
+    }
+    /** Flushes once when the event loop empties, so short-lived scripts do not lose their last batch. */
+    flushOnExit(timeoutMs = 2000) {
+        process.once('beforeExit', () => {
+            void this.flushWithin(timeoutMs);
+        });
+    }
+    async shutdown(timeoutMs) {
+        this.stopHeartbeat();
+        await super.shutdown(timeoutMs);
+    }
+    /** Flush that gives up after `timeoutMs` without closing the client. */
+    flushWithin(timeoutMs) {
+        let timer;
+        return Promise.race([
+            this.flush().catch(() => undefined),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, timeoutMs);
+                timer.unref?.();
+            }),
+        ]).finally(() => {
+            if (timer)
+                clearTimeout(timer);
+        });
+    }
+    /** Convenience for errors caught in application code. */
+    captureException(error, options = {}) {
+        this.captureError(error, { source: 'backend', ...options });
+    }
+    resumeHeartbeat() {
+        if (this.heartbeatTimer || !this.isEnabled)
+            return;
+        this.runtime.start();
+        this.beat();
+        this.heartbeatTimer = setInterval(() => this.beat(), this.heartbeatIntervalMs);
+        this.heartbeatTimer.unref?.();
+    }
+    pauseHeartbeat() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+        this.runtime.stop();
+    }
+    beat() {
+        const s = this.runtime.snapshot();
+        const { uptimeSeconds, ...attributes } = s;
+        this.heartbeat({ instanceId: this.instanceId, uptimeSeconds, attributes });
+    }
+}
+//# sourceMappingURL=acr.js.map

package/dist/esm/acr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acr.js","sourceRoot":"","sources":["../../src/acr.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,SAAS,EAAoD,MAAM,eAAe,CAAC;AAC5F,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,cAAc,EAAwB,MAAM,cAAc,CAAC;AAgBpE;;;GAGG;AACH,MAAM,OAAO,GAAI,SAAQ,SAAS;IAShC,iGAAiG;IACjG,YAAY,OAAuB,EAAE,MAAe,QAAQ;QAC1D,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QATL,YAAO,GAAG,IAAI,cAAc,EAAE,CAAC;QACxC,mBAAc,GAA0C,IAAI,CAAC;QACrE,8GAA8G;QACtG,uBAAkB,GAAG,KAAK,CAAC;QAC3B,0BAAqB,GAAG,KAAK,CAAC;QAMpC,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,GAAG,QAAQ,EAAE,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QACvE,IAAI,CAAC,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,IAAI,KAAM,CAAC;QACjE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,mBAAmB,CAAC,IAAI,IAAI,CAAC,mBAAmB,GAAG,IAAI,EAAE,CAAC;YAClF,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,cAAc;QACZ,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAC/B,IAAI,CAAC,eAAe,EAAE,CAAC;IACzB,CAAC;IAED,aAAa;QACX,IAAI,CAAC,kBAAkB,GAAG,KAAK,CAAC;QAChC,IAAI,CAAC,cAAc,EAAE,CAAC;IACxB,CAAC;IAED;;;OAGG;IACgB,eAAe;QAChC,IAAI,CAAC,IAAI,CAAC,kBAAkB;YAAE,OAAO;QACrC,IAAI,IAAI,CAAC,SAAS;YAAE,IAAI,CAAC,eAAe,EAAE,CAAC;;YACtC,IAAI,CAAC,cAAc,EAAE,CAAC;IAC7B,CAAC;IAED,0DAA0D;IAC1D,eAAe;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;IAED;;;OAGG;IACH,oBAAoB,CAAC,UAAuC,EAAE;QAC5D,IAAI,IAAI,CAAC,qBAAqB;YAAE,OAAO;QACvC,IAAI,CAAC,qBAAqB,GAAG,IAAI,CAAC;QAClC,MAAM,cAAc,GAAG,OAAO,CAAC,uBAAuB,IAAI,IAAI,CAAC;QAC/D,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC;QAChD,MAAM,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;QAEnE,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,KAAK,EAAE,EAAE;YACxC,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,EAAE,CAAC,CAAC;YAC5G,KAAK,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;gBACzC,IAAI,cAAc,IAAI,CAAC,WAAW;oBAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACtD,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE;YAC1C,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,qBAAqB,EAAE,EAAE,CAAC,CAAC;QAChH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,qGAAqG;IACrG,WAAW,CAAC,SAAS,GAAG,IAAI;QAC1B,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,EAAE;YAC9B,KAAK,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;IACL,CAAC;IAEQ,KAAK,CAAC,QAAQ,CAAC,SAAkB;QACxC,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,MAAM,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;IAED,wEAAwE;IACxE,WAAW,CAAC,SAAiB;QAC3B,IAAI,KAAgD,CAAC;QACrD,OAAO,OAAO,CAAC,IAAI,CAAC;YAClB,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;YACnC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBAC5B,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;gBACtC,KAAgC,CAAC,KAAK,EAAE,EAAE,CAAC;YAC9C,CAAC,CAAC;SACH,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE;YACd,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;IACL,CAAC;IAED,yDAAyD;IACzD,gBAAgB,CAAC,KAAc,EAAE,UAAwB,EAAE;QACzD,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IAC9D,CAAC;IAEO,eAAe;QACrB,IAAI,IAAI,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO;QACnD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,IAAI,CAAC,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAC9E,IAAI,CAAC,cAAyC,CAAC,KAAK,EAAE,EAAE,CAAC;IAC5D,CAAC;IAEO,cAAc;QACpB,IAAI,IAAI,CAAC,cAAc;YAAE,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC5D,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;IAEO,IAAI;QACV,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QAClC,MAAM,EAAE,aAAa,EAAE,GAAG,UAAU,EAAE,GAAG,CAAC,CAAC;QAC3C,IAAI,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IAC7E,CAAC;CACF"}

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+export { ACR } from './acr.js';
+export { RuntimeMonitor } from './runtime.js';
+export { NODE_SDK } from './version.js';
+export * from '@lib-acr/core';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,cAAc,eAAe,CAAC"}

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/runtime.js

@@ -0,0 +1,68 @@
+import { monitorEventLoopDelay, performance, PerformanceObserver } from 'node:perf_hooks';
+/**
+ * Samples process health between calls to snapshot(). CPU, event loop utilization and GC counts cover the time since
+ * the previous snapshot, so each heartbeat reports its own interval.
+ */
+export class RuntimeMonitor {
+    constructor() {
+        this.delay = monitorEventLoopDelay({ resolution: 20 });
+        this.observer = null;
+        this.gcCount = 0;
+        this.lastCpu = process.cpuUsage();
+        this.lastHr = process.hrtime.bigint();
+        this.lastElu = performance.eventLoopUtilization();
+        this.startedAt = Date.now();
+    }
+    start() {
+        this.delay.enable();
+        if (this.observer)
+            return;
+        try {
+            this.observer = new PerformanceObserver((list) => {
+                this.gcCount += list.getEntries().length;
+            });
+            this.observer.observe({ entryTypes: ['gc'] });
+        }
+        catch {
+            this.observer = null;
+        }
+    }
+    stop() {
+        this.delay.disable();
+        this.observer?.disconnect();
+        this.observer = null;
+    }
+    snapshot(now = Date.now()) {
+        const mem = process.memoryUsage();
+        const cpu = process.cpuUsage(this.lastCpu);
+        const hr = process.hrtime.bigint();
+        const elapsedMicros = Number(hr - this.lastHr) / 1000;
+        const elu = performance.eventLoopUtilization(this.lastElu);
+        const cpuPercent = elapsedMicros > 0 ? ((cpu.user + cpu.system) / elapsedMicros) * 100 : 0;
+        const p99 = this.delay.count > 0 ? this.delay.percentile(99) / 1e6 : 0;
+        this.delay.reset();
+        const gc = this.gcCount;
+        this.gcCount = 0;
+        this.lastCpu = process.cpuUsage();
+        this.lastHr = hr;
+        this.lastElu = performance.eventLoopUtilization();
+        const handles = process.getActiveResourcesInfo?.().length ?? 0;
+        return {
+            uptimeSeconds: Math.max(0, Math.floor((now - this.startedAt) / 1000)),
+            rssBytes: mem.rss,
+            heapUsedBytes: mem.heapUsed,
+            heapTotalBytes: mem.heapTotal,
+            externalBytes: mem.external,
+            cpuPercent: round(Math.min(cpuPercent, 100 * 64)),
+            eventLoopUtilization: round(elu.utilization, 4),
+            eventLoopDelayP99Ms: round(Number.isFinite(p99) ? p99 : 0),
+            gcCount: gc,
+            activeHandles: handles,
+        };
+    }
+}
+function round(value, digits = 2) {
+    const f = 10 ** digits;
+    return Math.round(value * f) / f;
+}
+//# sourceMappingURL=runtime.js.map

package/dist/esm/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/esm/sdk-info.js

@@ -0,0 +1,3 @@
+// Generated by scripts/sync-sdk-info.mjs from package.json. Do not edit by hand.
+export const SDK_INFO = { name: '@lib-acr/node', version: '0.0.1' };
+//# sourceMappingURL=sdk-info.js.map

package/dist/esm/sdk-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-info.js","sourceRoot":"","sources":["../../src/sdk-info.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,CAAC,MAAM,QAAQ,GAAG,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,OAAO,EAAW,CAAC"}

package/dist/esm/version.js

@@ -0,0 +1,2 @@
+export { SDK_INFO as NODE_SDK } from './sdk-info.js';
+//# sourceMappingURL=version.js.map

package/dist/esm/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/types/acr.d.ts

@@ -0,0 +1,57 @@
+import { AcrClient, type AcrOptions, type ErrorOptions, type SdkInfo } from '@lib-acr/core';
+import { type RuntimeSnapshot } from './runtime.js';
+export interface NodeAcrOptions extends AcrOptions {
+    /** Identifies this process in heartbeats. Default `<hostname>:<pid>`. */
+    instanceId?: string;
+    /** Milliseconds between runtime heartbeats. Default 30 000. */
+    heartbeatIntervalMs?: number;
+}
+export interface CaptureProcessErrorsOptions {
+    /** Exit with code 1 after an uncaught exception, once the telemetry is flushed. Default true. */
+    exitOnUncaughtException?: boolean;
+    /** Longest wait for the flush before exiting. Default 2 000 ms. */
+    exitTimeoutMs?: number;
+}
+/**
+ * Node.js client. Adds runtime heartbeats (CPU, memory, event loop, GC) and capture of unhandled errors on top of the
+ * shared core client.
+ */
+export declare class ACR extends AcrClient {
+    readonly instanceId: string;
+    private readonly runtime;
+    private heartbeatTimer;
+    /** startHeartbeat() was called and stopHeartbeat() was not: heartbeats run whenever the client is enabled. */
+    private heartbeatRequested;
+    private processHooksInstalled;
+    private readonly heartbeatIntervalMs;
+    /** `sdk` lets framework wrappers (Express, NestJS) report their own package name and version. */
+    constructor(options: NodeAcrOptions, sdk?: SdkInfo);
+    /**
+     * Sends one heartbeat with a runtime snapshot now, then one per interval. Safe to call twice. While the client is
+     * disabled no heartbeats are sent; they start as soon as it is enabled again.
+     */
+    startHeartbeat(): void;
+    stopHeartbeat(): void;
+    /**
+     * Starts or pauses heartbeats requested with startHeartbeat() whenever collection is switched on or off, locally
+     * (setEnabled) or by the remote kill switch.
+     */
+    protected onEnabledChange(): void;
+    /** Current runtime snapshot, without sending anything. */
+    runtimeSnapshot(): RuntimeSnapshot;
+    /**
+     * Reports uncaught exceptions and unhandled promise rejections. Telemetry is flushed before an uncaught exception
+     * ends the process. When this SDK is the only handler, the process exits with code 1 as Node would have done.
+     */
+    captureProcessErrors(options?: CaptureProcessErrorsOptions): void;
+    /** Flushes once when the event loop empties, so short-lived scripts do not lose their last batch. */
+    flushOnExit(timeoutMs?: number): void;
+    shutdown(timeoutMs?: number): Promise<void>;
+    /** Flush that gives up after `timeoutMs` without closing the client. */
+    flushWithin(timeoutMs: number): Promise<void>;
+    /** Convenience for errors caught in application code. */
+    captureException(error: unknown, options?: ErrorOptions): void;
+    private resumeHeartbeat;
+    private pauseHeartbeat;
+    private beat;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export { ACR } from './acr.js';
+export type { CaptureProcessErrorsOptions, NodeAcrOptions } from './acr.js';
+export { RuntimeMonitor } from './runtime.js';
+export type { RuntimeSnapshot } from './runtime.js';
+export { NODE_SDK } from './version.js';
+export * from '@lib-acr/core';

package/dist/types/runtime.d.ts

@@ -0,0 +1,28 @@
+export interface RuntimeSnapshot {
+    uptimeSeconds: number;
+    rssBytes: number;
+    heapUsedBytes: number;
+    heapTotalBytes: number;
+    externalBytes: number;
+    cpuPercent: number;
+    eventLoopUtilization: number;
+    eventLoopDelayP99Ms: number;
+    gcCount: number;
+    activeHandles: number;
+}
+/**
+ * Samples process health between calls to snapshot(). CPU, event loop utilization and GC counts cover the time since
+ * the previous snapshot, so each heartbeat reports its own interval.
+ */
+export declare class RuntimeMonitor {
+    private readonly delay;
+    private observer;
+    private gcCount;
+    private lastCpu;
+    private lastHr;
+    private lastElu;
+    private readonly startedAt;
+    start(): void;
+    stop(): void;
+    snapshot(now?: number): RuntimeSnapshot;
+}

package/dist/types/sdk-info.d.ts

@@ -0,0 +1,4 @@
+export declare const SDK_INFO: {
+    readonly name: "@lib-acr/node";
+    readonly version: "0.0.1";
+};

package/dist/types/version.d.ts

@@ -0,0 +1 @@
+export { SDK_INFO as NODE_SDK } from './sdk-info.js';

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@lib-acr/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "ACR SDK for Node.js: runtime heartbeats, runtime metrics, unhandled error capture and custom events and logs.",
+  "license": "MIT",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "@lib-acr/core": "0.0.1"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/application-control-room/application.git",
+    "directory": "packages/node"
+  },
+  "homepage": "https://github.com/application-control-room/application/tree/main/packages/node#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}