@futurewindai/wotchi 0.1.0-beta.5 → 0.1.0-beta.6

package/README.md

@@ -2,12 +2,12 @@
 
 > Low-noise error alerts for Node.js services.
 
-> **Status:** Public beta (`0.1.0-beta.5`). Install with the `beta` tag; the API may evolve before the first stable release.
+> **Status:** Public beta (`0.1.0-beta.6`). The API may evolve before the first stable release.
 
 [![CI](https://github.com/FutureWindAI/Wotchi/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/FutureWindAI/Wotchi/actions/workflows/ci.yml)
 [![CodeQL](https://github.com/FutureWindAI/Wotchi/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/FutureWindAI/Wotchi/actions/workflows/codeql.yml)
 [![npm](https://img.shields.io/npm/v/%40futurewindai%2Fwotchi?label=npm%20beta)](https://www.npmjs.com/package/@futurewindai/wotchi)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/FutureWindAI/Wotchi/blob/v0.1.0-beta.6/LICENSE)
 [![Node.js 18–26](https://img.shields.io/badge/node-18%E2%80%9326-339933?logo=node.js&logoColor=white)](https://nodejs.org/en/about/previous-releases)
 
 Wotchi captures application errors in-process, removes sensitive values, groups repeated failures, and delivers bounded console, Telegram, or HTTPS webhook alerts without changing framework response handling. It is a signal-conditioning layer, not a replacement for a full observability platform.
@@ -67,6 +67,45 @@ notifier.
 | Generic HTTPS webhook notifier            | Route bounded JSON alerts to an existing internal alert destination.                                           |
 | Actionable context and trace passthrough  | Include route, release, request/correlation IDs, operation/job, safe tags, links, and existing trace/span IDs. |
 | Optional status observation and JSON logs | Observe direct `401`/`403`/`429`/`5xx` responses and emit collector-friendly JSON.                             |
+| Optional diagnostics exporter             | Expose aggregate Wotchi health counters to an existing Prometheus-compatible `/metrics` endpoint.              |
+| Optional overload admission               | Drop capture work before normalization at a measured rate and emit one sanitized overload signal.              |
+| Notifier isolation and shutdown           | Bound slow destinations, open circuits after repeated failures, and drain safely during termination.           |
+| Optional runtime pressure watcher         | Threshold CPU, RSS, heap, event-loop delay, or pending alerts with numeric-only local samples.                 |
+
+## When to use Wotchi
+
+Use Wotchi when an Express or NestJS service needs low-noise, privacy-conscious alerts without
+adding a collector, database, or hosted account. Keep a full observability platform when you need
+durable incident history, cross-replica deduplication, dashboards, traces, or paging workflows.
+
+## Performance evidence
+
+The package has zero direct runtime dependencies and keeps capture, grouping, and notification work
+bounded. On a Node.js 22/macOS arm64 benchmark run of beta.6, capture p95/p99 was
+`0.036 ms`/`0.036 ms`, duplicate-storm retained heap was `0.194 MiB`, and the packed artifact was
+`60,534 bytes`. Prometheus rendering p95 was `0.0048 ms`. The queue benchmark admitted `101` alerts while a notifier was blocked, capped
+pending work at `100`, and kept Express and NestJS responses completing. These are reproducible local
+measurements, not production guarantees; repeat `npm run benchmark` and `npm run benchmark:queue`
+on your runtime and workload. See [performance evidence](docs/PERFORMANCE.md).
+
+The exporter does not open a server or send data. Attach it to a protected endpoint owned
+by the host application:
+
+```ts
+import { createWotchiPrometheusExporter } from "@futurewindai/wotchi";
+
+const metrics = createWotchiPrometheusExporter(wotchi);
+app.get("/metrics", (_request, response) => {
+  response.setHeader("Content-Type", metrics.contentType);
+  response.send(metrics.render());
+});
+```
+
+Beta.6 also supports opt-in admission control, notifier timeouts/circuits, graceful shutdown, and a
+numeric-only runtime watcher.
+
+It emits only aggregate counters and queue/group gauges. Prometheus, Grafana, or another existing
+collector remains responsible for scraping, authentication, retention, and dashboards.
 
 ## How it works
 
@@ -102,14 +141,29 @@ const wotchi = createWotchi({
 app.use(wotchiErrorHandler(wotchi));
 ```
 
-NestJS applications register the delegating global filter once after creating the application:
+NestJS applications can register Wotchi from the root module, keeping `main.ts` focused on
+application bootstrap:
 
 ```ts
-import { registerWotchiNest } from "@futurewindai/wotchi/nest";
-
-registerWotchiNest(app, wotchi);
+import { Module } from "@nestjs/common";
+import { consoleNotifier } from "@futurewindai/wotchi";
+import { WotchiModule } from "@futurewindai/wotchi/nest";
+
+@Module({
+  imports: [
+    WotchiModule.forRoot({
+      service: "orders-api",
+      environment: "production",
+      notifiers: [consoleNotifier()],
+    }),
+  ],
+})
+export class AppModule {}
 ```
 
+For a custom dependency-injected `APP_FILTER`, keep its response and logging behavior, disable the
+automatic Wotchi filter, and wrap it with `withWotchiNestFilter`. See the [NestJS API](docs/API.md#nestjs-entry-point).
+
 The package keeps compatibility with Node.js `>=18.18.0` and is tested across Node.js 18–26. Node.js 22 or 24 LTS is recommended for production. Express and NestJS adapters are optional subpath integrations, so applications only load the framework adapter they use.
 
 ## Telegram alerts
@@ -140,7 +194,7 @@ function requiredEnv(name: string): string {
 }
 ```
 
-Wotchi does not ship a shared bot token. Delivery is queued outside the request path and sends only the sanitized incident alert. See [configuration](docs/CONFIGURATION.md) for notifier and security options.
+Wotchi does not ship a shared bot token. Delivery is queued outside the request path and sends only the sanitized incident alert. See [configuration](https://github.com/FutureWindAI/Wotchi/blob/main/docs/CONFIGURATION.md) for notifier and security options.
 
 ## HTTPS webhook alerts
 
@@ -206,7 +260,7 @@ Wotchi keeps grouping and cooldown state in one process. Replicas have independe
 reset groups, and a serverless instance can terminate before asynchronous delivery completes. An
 in-process SDK cannot reliably detect an OOM kill, frozen event loop, host failure, or unavailable
 network. Pair it with an external uptime monitor and keep graceful shutdown explicit; see the
-[production recipe](examples/production-recipe/README.md).
+[production recipe](https://github.com/FutureWindAI/Wotchi/blob/main/examples/production-recipe/README.md).
 
 ## Process monitoring
 
@@ -230,25 +284,25 @@ const monitor = registerWotchiProcessMonitor(wotchi);
 
 ## Documentation
 
-- [Getting started](docs/GETTING_STARTED.md)
-- [Examples](docs/EXAMPLES.md)
-- [API reference](docs/API.md)
-- [Configuration](docs/CONFIGURATION.md)
-- [Compatibility](docs/COMPATIBILITY.md)
-- [Performance](docs/PERFORMANCE.md)
-- [Architecture](docs/ARCHITECTURE.md)
-- [Roadmap](docs/ROADMAP.md)
-- [Troubleshooting](docs/TROUBLESHOOTING.md)
-- [FAQ](docs/FAQ.md)
-- [Security and privacy](docs/SECURITY.md)
-- [Threat model](docs/THREAT_MODEL.md)
-- [Contributing](CONTRIBUTING.md)
-- [Changelog](CHANGELOG.md)
+- [Getting started](https://github.com/FutureWindAI/Wotchi/blob/main/docs/GETTING_STARTED.md)
+- [Examples](https://github.com/FutureWindAI/Wotchi/blob/main/docs/EXAMPLES.md)
+- [API reference](https://github.com/FutureWindAI/Wotchi/blob/main/docs/API.md)
+- [Configuration](https://github.com/FutureWindAI/Wotchi/blob/main/docs/CONFIGURATION.md)
+- [Compatibility](https://github.com/FutureWindAI/Wotchi/blob/main/docs/COMPATIBILITY.md)
+- [Performance](https://github.com/FutureWindAI/Wotchi/blob/main/docs/PERFORMANCE.md)
+- [Architecture](https://github.com/FutureWindAI/Wotchi/blob/main/docs/ARCHITECTURE.md)
+- [Roadmap](https://github.com/FutureWindAI/Wotchi/blob/main/docs/ROADMAP.md)
+- [Troubleshooting](https://github.com/FutureWindAI/Wotchi/blob/main/docs/TROUBLESHOOTING.md)
+- [FAQ](https://github.com/FutureWindAI/Wotchi/blob/main/docs/FAQ.md)
+- [Security and privacy](https://github.com/FutureWindAI/Wotchi/blob/main/docs/SECURITY.md)
+- [Threat model](https://github.com/FutureWindAI/Wotchi/blob/main/docs/THREAT_MODEL.md)
+- [Contributing](https://github.com/FutureWindAI/Wotchi/blob/main/CONTRIBUTING.md)
+- [Changelog](https://github.com/FutureWindAI/Wotchi/blob/main/CHANGELOG.md)
 - [GitHub releases](https://github.com/FutureWindAI/Wotchi/releases)
-- [Apache License 2.0](LICENSE)
+- [Apache License 2.0](https://github.com/FutureWindAI/Wotchi/blob/main/LICENSE)
 
 ## Security
 
-Do not include real secrets or customer error data in issues, examples, or test fixtures. Report security vulnerabilities privately using [SECURITY.md](SECURITY.md).
+Do not include real secrets or customer error data in issues, examples, or test fixtures. Report security vulnerabilities privately using the [security policy](https://github.com/FutureWindAI/Wotchi/blob/main/SECURITY.md).
 
 Wotchi is open source and maintained by FutureWind AI.

package/SECURITY.md

@@ -4,13 +4,13 @@
 
 Wotchi targets applications running Node.js `>=18.18.0` and is built and tested across the Node.js 18–26 matrix. Node.js versions below 18.18 are not supported.
 
-The current package contains the framework-independent capture core, console and Telegram notifiers, Express 4/5 middleware, NestJS 10/11 exception-filter integration, and opt-in process monitoring. Supported runtime and framework combinations are documented after packed-tarball compatibility and release-security checks.
+The current package contains the framework-independent capture core, console, Telegram, and generic HTTPS webhook notifiers, Express 4/5 middleware, NestJS 10/11 exception-filter integration, optional HTTP status observation, and opt-in process monitoring. Supported runtime and framework combinations are documented after packed-tarball compatibility and release-security checks.
 
 ## Reporting a Vulnerability
 
 Do not disclose a suspected vulnerability, exploit detail, credential, token, or real customer error in a public issue, discussion, pull request, or example.
 
-Use [GitHub private vulnerability reporting](https://github.com/FutureWindAI/wotchi/security/advisories/new) when it is available for this repository. If that private form is unavailable, open a public issue containing no sensitive detail and ask the maintainers to establish a private reporting channel.
+Use [GitHub private vulnerability reporting](https://github.com/FutureWindAI/Wotchi/security/advisories/new). Do not open a public issue for a suspected vulnerability.
 
 Include only the minimum sanitized information needed to reproduce the problem. Remove application secrets, personal data, proprietary source, production URLs, and raw customer payloads.
 

package/dist/cjs/core/admission.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCaptureAdmission = createCaptureAdmission;
+/** A small token bucket used before normalization to bound overload work. */
+function createCaptureAdmission(options) {
+    const now = options.now ?? Date.now;
+    let tokens = options.burst;
+    let lastRefill = now();
+    return {
+        tryAcquire: () => {
+            const timestamp = now();
+            const elapsedMs = Math.max(0, timestamp - lastRefill);
+            tokens = Math.min(options.burst, tokens + (elapsedMs * options.maxEventsPerSecond) / 1_000);
+            lastRefill = timestamp;
+            if (tokens < 1) {
+                return false;
+            }
+            tokens -= 1;
+            return true;
+        },
+    };
+}

package/dist/cjs/core/client.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWotchi = createWotchi;
 const config_js_1 = require("./config.js");
+const admission_js_1 = require("./admission.js");
 const diagnostics_js_1 = require("./diagnostics.js");
 const fingerprint_js_1 = require("./fingerprint.js");
 const group_store_js_1 = require("./group-store.js");
@@ -282,9 +283,19 @@ function createWotchi(config) {
     const queue = (0, notification_queue_js_1.createNotificationQueue)({
         maxPendingAlerts: normalized.queue.maxPendingAlerts,
         concurrency: normalized.queue.concurrency,
+        notifierTimeoutMs: normalized.queue.notifierTimeoutMs,
+        notifierCircuitBreaker: normalized.queue.notifierCircuitBreaker,
     });
+    const admission = normalized.overload === undefined
+        ? undefined
+        : (0, admission_js_1.createCaptureAdmission)({
+            maxEventsPerSecond: normalized.overload.maxEventsPerSecond,
+            burst: normalized.overload.burst,
+            now,
+        });
     const privacy = normalized.privacy;
     let eventSequence = 0;
+    let overloadLastAlertAt = 0;
     const matchingRule = (event) => normalized.rules.find((rule) => (rule.environment === undefined || rule.environment === event.environment) &&
         (rule.route === undefined || rule.route === event.request?.route));
     const captureSafeEvent = (error, metadata, context, request, eventKind = "error", alertThreshold = normalized.grouping.alertThreshold, fingerprintOverride, severityOverride, trace, correlationId, operation, job, tags) => {
@@ -405,11 +416,28 @@ function createWotchi(config) {
         }
         diagnostics.capturedEvents += 1;
     };
+    const emitOverloadSignal = (timestamp) => {
+        const cooldownMs = normalized.overload?.alertCooldownMs ?? 0;
+        if (cooldownMs > 0 && timestamp - overloadLastAlertAt < cooldownMs) {
+            return;
+        }
+        overloadLastAlertAt = timestamp;
+        captureSafeEvent(new Error("Wotchi capture overload: admission limit reached"), undefined, { droppedEvents: diagnostics.eventsDroppedOverload }, undefined, "runtime-monitor", 1, "wotchi.capture.overload", "high", undefined, undefined, "wotchi.overload", undefined, undefined);
+    };
     const captureException = (error, context, options) => {
         if (!normalized.enabled) {
             return;
         }
+        if (queue.isClosed()) {
+            diagnostics.capturesAfterShutdown += 1;
+            return;
+        }
         try {
+            if (admission !== undefined && !admission.tryAcquire()) {
+                diagnostics.eventsDroppedOverload += 1;
+                emitOverloadSignal(now());
+                return;
+            }
             captureSafeEvent(error, undefined, context, options?.request, "error", normalizeEventAlertThreshold(options?.alertThreshold) ?? normalized.grouping.alertThreshold, options?.fingerprint, options?.severity, options?.trace, options?.correlationId, options?.operation, options?.job, options?.tags);
         }
         catch {
@@ -420,6 +448,10 @@ function createWotchi(config) {
         if (!normalized.enabled) {
             return;
         }
+        if (queue.isClosed()) {
+            diagnostics.capturesAfterShutdown += 1;
+            return;
+        }
         try {
             if (event === null || typeof event !== "object" || event.level !== "error") {
                 throw new TypeError("event.level must be error");
@@ -428,6 +460,14 @@ function createWotchi(config) {
                 throw new TypeError("event.message must be a string");
             }
             const alertThreshold = normalizeEventAlertThreshold(event.alertThreshold);
+            if (admission !== undefined &&
+                event.kind !== "process-monitor" &&
+                event.kind !== "runtime-monitor" &&
+                !admission.tryAcquire()) {
+                diagnostics.eventsDroppedOverload += 1;
+                emitOverloadSignal(now());
+                return;
+            }
             captureSafeEvent(event.error ?? safeMessage(event.message, privacy), event.metadata, event.context, event.request, event.kind ?? "error", alertThreshold ?? normalized.grouping.alertThreshold, event.fingerprint, event.severity, event.trace, event.correlationId, event.operation, event.job, event.tags);
         }
         catch {
@@ -440,6 +480,8 @@ function createWotchi(config) {
         alertsDropped: queue.alertsDropped(),
         alertsSent: queue.alertsSent(),
         notifierFailures: queue.notifierFailures(),
+        notifierTimeouts: queue.notifierTimeouts(),
+        notifierCircuitOpenSkips: queue.notifierCircuitOpenSkips(),
         activeGroups: groupStore.size(),
         pendingAlerts: queue.pending(),
     });
@@ -503,11 +545,15 @@ function createWotchi(config) {
             ...(status === "notifier-failed" ? { error: "One or more notifiers failed." } : {}),
         };
     };
+    const shutdown = async (timeoutMs) => {
+        await queue.close(timeoutMs);
+    };
     return {
         captureException,
         captureEvent,
         testAlert,
         flush: (timeoutMs) => queue.flush(timeoutMs),
+        shutdown,
         getDiagnostics: readDiagnostics,
     };
 }

package/dist/cjs/core/config.js

@@ -232,7 +232,9 @@ function validateConfig(config) {
     }
     const grouping = readOptionalRecord(config.grouping, "grouping");
     const queue = readOptionalRecord(config.queue, "queue");
+    const notifierCircuitBreaker = readOptionalRecord(queue?.notifierCircuitBreaker, "queue.notifierCircuitBreaker");
     const privacy = readOptionalRecord(config.privacy, "privacy");
+    const overload = readOptionalRecord(config.overload, "overload");
     const links = normalizeLinks(config.links);
     const concurrency = queue?.concurrency;
     if (concurrency !== undefined && concurrency !== 1) {
@@ -259,7 +261,21 @@ function validateConfig(config) {
         queue: Object.freeze({
             maxPendingAlerts: readPositiveInteger(queue, "maxPendingAlerts", 100, limits_js_1.MAX_PENDING_ALERTS),
             concurrency: 1,
+            notifierTimeoutMs: readPositiveInteger(queue, "notifierTimeoutMs", 5_000, limits_js_1.MAX_NOTIFIER_TIMEOUT_MS),
+            notifierCircuitBreaker: Object.freeze({
+                failureThreshold: readPositiveInteger(notifierCircuitBreaker, "failureThreshold", 3, limits_js_1.MAX_CIRCUIT_BREAKER_FAILURES),
+                cooldownMs: readPositiveInteger(notifierCircuitBreaker, "cooldownMs", 30_000, limits_js_1.MAX_CIRCUIT_BREAKER_COOLDOWN_MS),
+            }),
         }),
+        ...(overload === undefined
+            ? {}
+            : {
+                overload: Object.freeze({
+                    maxEventsPerSecond: readPositiveInteger(overload, "maxEventsPerSecond", 1_000, limits_js_1.MAX_CAPTURE_RATE),
+                    burst: readPositiveInteger(overload, "burst", readPositiveInteger(overload, "maxEventsPerSecond", 1_000, limits_js_1.MAX_CAPTURE_RATE), limits_js_1.MAX_CAPTURE_RATE),
+                    alertCooldownMs: readPositiveInteger(overload, "alertCooldownMs", 60_000, limits_js_1.MAX_COOLDOWN_MS),
+                }),
+            }),
         privacy: Object.freeze({
             redactKeys: normalizeRedactKeys(privacy),
             maxDepth: readPositiveInteger(privacy, "maxDepth", 5, limits_js_1.MAX_NORMALIZATION_DEPTH),

package/dist/cjs/core/diagnostics.js

@@ -10,6 +10,8 @@ function createDiagnosticsState() {
         filterFailures: 0,
         beforeSendFailures: 0,
         eventsSuppressed: 0,
+        eventsDroppedOverload: 0,
+        capturesAfterShutdown: 0,
     };
 }
 function snapshotDiagnostics(state, values) {
@@ -20,6 +22,8 @@ function snapshotDiagnostics(state, values) {
         filterFailures: state.filterFailures,
         beforeSendFailures: state.beforeSendFailures,
         eventsSuppressed: state.eventsSuppressed,
+        eventsDroppedOverload: state.eventsDroppedOverload,
+        capturesAfterShutdown: state.capturesAfterShutdown,
         ...values,
     });
 }

package/dist/cjs/core/group-store.js

@@ -50,14 +50,9 @@ function createGroupStore(options) {
         severity: group.severity,
     });
     const evictLeastRecent = () => {
-        let candidate;
-        for (const group of groups.values()) {
-            if (candidate === undefined || group.lastSeenMs < candidate.lastSeenMs) {
-                candidate = group;
-            }
-        }
-        if (candidate !== undefined) {
-            groups.delete(candidate.fingerprint);
+        const oldestFingerprint = groups.keys().next().value;
+        if (typeof oldestFingerprint === "string") {
+            groups.delete(oldestFingerprint);
             evicted += 1;
         }
     };
@@ -83,6 +78,10 @@ function createGroupStore(options) {
             };
             groups.set(fingerprint, group);
         }
+        else {
+            groups.delete(fingerprint);
+            groups.set(fingerprint, group);
+        }
         group.lastSeenMs = timestamp;
         group.totalCount += 1;
         group.severity = severity;

package/dist/cjs/core/limits.js

@@ -1,12 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_NORMALIZATION_STACK_LENGTH = exports.MAX_NORMALIZATION_STRING_LENGTH = exports.MAX_NORMALIZATION_KEYS = exports.MAX_NORMALIZATION_DEPTH = exports.MAX_COOLDOWN_MS = exports.MAX_ALERT_THRESHOLD = exports.MAX_WINDOW_MS = exports.MAX_PENDING_ALERTS = exports.MAX_EVENTS_PER_WINDOW = exports.MAX_GROUPS = void 0;
+exports.MAX_NORMALIZATION_STACK_LENGTH = exports.MAX_NORMALIZATION_STRING_LENGTH = exports.MAX_NORMALIZATION_KEYS = exports.MAX_NORMALIZATION_DEPTH = exports.MAX_CIRCUIT_BREAKER_FAILURES = exports.MAX_CIRCUIT_BREAKER_COOLDOWN_MS = exports.MAX_NOTIFIER_TIMEOUT_MS = exports.MAX_CAPTURE_RATE = exports.MAX_COOLDOWN_MS = exports.MAX_ALERT_THRESHOLD = exports.MAX_WINDOW_MS = exports.MAX_PENDING_ALERTS = exports.MAX_EVENTS_PER_WINDOW = exports.MAX_GROUPS = void 0;
 exports.MAX_GROUPS = 10_000;
 exports.MAX_EVENTS_PER_WINDOW = 10_000;
 exports.MAX_PENDING_ALERTS = 10_000;
 exports.MAX_WINDOW_MS = 7 * 24 * 60 * 60 * 1_000;
 exports.MAX_ALERT_THRESHOLD = 1_000_000;
 exports.MAX_COOLDOWN_MS = 30 * 24 * 60 * 60 * 1_000;
+exports.MAX_CAPTURE_RATE = 1_000_000;
+exports.MAX_NOTIFIER_TIMEOUT_MS = 60_000;
+exports.MAX_CIRCUIT_BREAKER_COOLDOWN_MS = 24 * 60 * 60 * 1_000;
+exports.MAX_CIRCUIT_BREAKER_FAILURES = 100;
 exports.MAX_NORMALIZATION_DEPTH = 20;
 exports.MAX_NORMALIZATION_KEYS = 10_000;
 exports.MAX_NORMALIZATION_STRING_LENGTH = 32_768;

package/dist/cjs/core/normalize.js

@@ -98,7 +98,12 @@ const normalizeValue = (value, depth, state, limits) => {
             break;
         }
         state.keysVisited += 1;
-        result[truncate(key, limits.maxStringLength)] = normalizeValue(readProperty(value, key), depth + 1, state, limits);
+        const child = readProperty(value, key);
+        const normalizedKey = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+        result[truncate(key, limits.maxStringLength)] =
+            normalizedKey === "stack" && typeof child === "string"
+                ? truncate(child, limits.maxStackLength)
+                : normalizeValue(child, depth + 1, state, limits);
     }
     return result;
 };

package/dist/cjs/core/notification-queue.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createNotificationQueue = createNotificationQueue;
 const limits_js_1 = require("./limits.js");
 const DEFAULT_FLUSH_TIMEOUT_MS = 5_000;
+const DEFAULT_NOTIFIER_TIMEOUT_MS = 5_000;
+const DEFAULT_CIRCUIT_FAILURE_THRESHOLD = 3;
+const DEFAULT_CIRCUIT_COOLDOWN_MS = 30_000;
 function createNotificationQueue(options) {
     if (!Number.isSafeInteger(options.maxPendingAlerts) ||
         options.maxPendingAlerts <= 0 ||
@@ -12,6 +15,23 @@ function createNotificationQueue(options) {
     if (options.concurrency !== 1) {
         throw new RangeError("concurrency must be 1");
     }
+    if (options.notifierTimeoutMs !== undefined &&
+        (!Number.isSafeInteger(options.notifierTimeoutMs) ||
+            options.notifierTimeoutMs <= 0 ||
+            options.notifierTimeoutMs > limits_js_1.MAX_NOTIFIER_TIMEOUT_MS)) {
+        throw new RangeError("notifierTimeoutMs must be a positive integer");
+    }
+    if (options.notifierCircuitBreaker !== undefined) {
+        const { failureThreshold, cooldownMs } = options.notifierCircuitBreaker;
+        if (!Number.isSafeInteger(failureThreshold) ||
+            failureThreshold <= 0 ||
+            failureThreshold > limits_js_1.MAX_CIRCUIT_BREAKER_FAILURES ||
+            !Number.isSafeInteger(cooldownMs) ||
+            cooldownMs <= 0 ||
+            cooldownMs > limits_js_1.MAX_CIRCUIT_BREAKER_COOLDOWN_MS) {
+            throw new RangeError("notifierCircuitBreaker limits are invalid");
+        }
+    }
     const pendingJobs = [];
     let drainPromise;
     let resolveDrain;
@@ -20,6 +40,15 @@ function createNotificationQueue(options) {
     let dropped = 0;
     let sent = 0;
     let failures = 0;
+    let timeouts = 0;
+    let circuitOpenSkips = 0;
+    let closed = false;
+    const notifierStates = new Map();
+    const notifierTimeoutMs = options.notifierTimeoutMs ?? DEFAULT_NOTIFIER_TIMEOUT_MS;
+    const circuit = options.notifierCircuitBreaker ?? {
+        failureThreshold: DEFAULT_CIRCUIT_FAILURE_THRESHOLD,
+        cooldownMs: DEFAULT_CIRCUIT_COOLDOWN_MS,
+    };
     const notifyFailure = (error, notifier) => {
         failures += 1;
         try {
@@ -38,19 +67,51 @@ function createNotificationQueue(options) {
         resolveDrain = undefined;
     };
     const processJob = async (job) => {
-        let jobSent = 0;
-        let jobFailures = 0;
-        for (const notifier of job.notifiers) {
+        const results = await Promise.all(job.notifiers.map(async (notifier) => {
+            const state = notifierStates.get(notifier) ?? { failures: 0, openUntil: 0 };
+            const timestamp = Date.now();
+            if (state.openUntil > timestamp) {
+                circuitOpenSkips += 1;
+                notifyFailure(new Error(`Notifier circuit is open: ${notifier.name}`), notifier);
+                return { sent: 0, failed: 1 };
+            }
+            if (state.openUntil !== 0) {
+                state.openUntil = 0;
+                state.failures = 0;
+            }
+            let timer;
             try {
-                await notifier.send(job.alert);
+                const timeout = new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        timeouts += 1;
+                        reject(new Error(`Notifier timed out after ${notifierTimeoutMs}ms: ${notifier.name}`));
+                    }, notifierTimeoutMs);
+                    timer.unref?.();
+                });
+                await Promise.race([notifier.send(job.alert), timeout]);
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                }
+                state.failures = 0;
+                notifierStates.set(notifier, state);
                 sent += 1;
-                jobSent += 1;
+                return { sent: 1, failed: 0 };
             }
             catch (error) {
-                jobFailures += 1;
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                }
+                state.failures += 1;
+                if (state.failures >= circuit.failureThreshold) {
+                    state.openUntil = Date.now() + circuit.cooldownMs;
+                }
+                notifierStates.set(notifier, state);
                 notifyFailure(error, notifier);
+                return { sent: 0, failed: 1 };
             }
-        }
+        }));
+        const jobSent = results.reduce((total, result) => total + result.sent, 0);
+        const jobFailures = results.reduce((total, result) => total + result.failed, 0);
         try {
             job.onComplete?.({ notifierFailures: jobFailures, sent: jobSent });
         }
@@ -73,7 +134,7 @@ function createNotificationQueue(options) {
         }
     };
     const enqueue = (alert, notifiers, onComplete) => {
-        if (pendingJobs.length >= options.maxPendingAlerts) {
+        if (closed || pendingJobs.length >= options.maxPendingAlerts) {
             dropped += 1;
             return false;
         }
@@ -86,6 +147,10 @@ function createNotificationQueue(options) {
         pump();
         return true;
     };
+    const close = (timeoutMs = DEFAULT_FLUSH_TIMEOUT_MS) => {
+        closed = true;
+        return flush(timeoutMs);
+    };
     const flush = (timeoutMs = DEFAULT_FLUSH_TIMEOUT_MS) => {
         if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
             return Promise.reject(new RangeError("timeoutMs must be a positive integer"));
@@ -111,10 +176,14 @@ function createNotificationQueue(options) {
     return {
         enqueue,
         flush,
+        close,
+        isClosed: () => closed,
         pending: () => pendingJobs.length,
         alertsQueued: () => queued,
         alertsDropped: () => dropped,
         alertsSent: () => sent,
         notifierFailures: () => failures,
+        notifierTimeouts: () => timeouts,
+        notifierCircuitOpenSkips: () => circuitOpenSkips,
     };
 }