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

package/README.md

@@ -1,16 +1,16 @@
 # Wotchi
 
-> Bounded incident alerts for Node.js services.
+> Low-noise error alerts for Node.js services.
 
-> **Status:** Public beta (`0.1.0-beta.2`). Install with the `beta` tag; the API may evolve before the first stable release.
+> **Status:** Public beta (`0.1.0-beta.5`). Install with the `beta` tag; 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)
-[![Node.js >=18.18](https://img.shields.io/badge/node-%3E%3D18.18.0-339933?logo=node.js&logoColor=white)](https://nodejs.org/en/about/previous-releases)
+[![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 or Telegram alerts without changing framework response handling.
+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.
 
 ## Quick start
 
@@ -34,6 +34,8 @@ await wotchi.flush();
 
 The example uses a threshold of one so the alert is visible immediately. The default policy groups three matching errors in one minute and suppresses duplicate alerts during the cooldown. Capture is synchronous; call `flush()` when the host needs to wait for notifier work.
 
+To validate a notifier without deliberately throwing an application error, call `const result = await wotchi.testAlert()` in a controlled setup. The structured result reports whether the alert was queued, flushed, delivered, or rejected by a notifier; configuration errors still throw during `createWotchi`.
+
 Example console output:
 
 ```text
@@ -54,26 +56,27 @@ notifier.
 
 ## What you get
 
-| Capability                                | Result                                                                             |
-| ----------------------------------------- | ---------------------------------------------------------------------------------- |
-| Bounded capture and queueing              | Repeated failures cannot create unbounded in-memory work.                          |
-| Redaction before processing               | Sensitive values are removed before grouping, logging, or transmission.            |
-| Grouping and cooldowns                    | Repeated failures produce a small number of useful alerts.                         |
-| Express 4/5 and NestJS 10/11 adapters     | Errors are observed while the framework keeps response ownership.                  |
-| ESM, CommonJS, and TypeScript types       | Use the package with common Node.js module setups.                                 |
-| Console and optional Telegram notifiers   | Start locally or self-host delivery without a Wotchi control plane.                |
-| Optional status observation and JSON logs | Observe direct `401`/`403`/`429`/`5xx` responses and emit collector-friendly JSON. |
+| Capability                                | Result                                                                                                         |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Bounded capture and queueing              | Repeated failures cannot create unbounded in-memory work.                                                      |
+| Redaction before processing               | Sensitive values are removed before grouping, logging, or transmission.                                        |
+| Grouping and cooldowns                    | Repeated failures produce a small number of useful alerts.                                                     |
+| Express 4/5 and NestJS 10/11 adapters     | Errors are observed while the framework keeps response ownership.                                              |
+| ESM, CommonJS, and TypeScript types       | Use the package with common Node.js module setups.                                                             |
+| Console and optional Telegram notifiers   | Start locally or self-host delivery without a Wotchi control plane.                                            |
+| 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.                             |
 
 ## How it works
 
-```mermaid
-flowchart LR
-  A[Application error] --> B[Normalize and redact]
-  B --> C[Stable fingerprint]
-  C --> D[Threshold and cooldown]
-  D --> E[Bounded queue]
-  E --> F[Console]
-  E --> G[Telegram]
+```text
+Application error
+  -> normalize and redact
+  -> stable fingerprint and optional user rule
+  -> threshold and cooldown
+  -> bounded notification queue
+  -> console, Telegram, or HTTPS webhook
 ```
 
 The same bounded capture path can be called from HTTP handlers, background workers, and queue
@@ -107,7 +110,7 @@ import { registerWotchiNest } from "@futurewindai/wotchi/nest";
 registerWotchiNest(app, wotchi);
 ```
 
-The package supports Node.js `>=18.18.0`. Express and NestJS adapters are optional subpath integrations, so applications only load the framework adapter they use.
+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
 
@@ -122,15 +125,89 @@ const wotchi = createWotchi({
   notifiers: [
     consoleNotifier(),
     telegramNotifier({
-      botToken: process.env.WOTCHI_TELEGRAM_BOT_TOKEN ?? "",
-      chatId: process.env.WOTCHI_TELEGRAM_CHAT_ID ?? "",
+      botToken: requiredEnv("WOTCHI_TELEGRAM_BOT_TOKEN"),
+      chatId: requiredEnv("WOTCHI_TELEGRAM_CHAT_ID"),
     }),
   ],
 });
+
+function requiredEnv(name: string): string {
+  const value = process.env[name];
+  if (value === undefined || value.trim() === "") {
+    throw new Error(`${name} must be configured before enabling Telegram`);
+  }
+  return value;
+}
 ```
 
 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.
 
+## HTTPS webhook alerts
+
+Use the generic webhook when an existing internal alerting or automation endpoint accepts JSON. Wotchi requires HTTPS by default, bounds headers and payloads, emits a versioned `{ version: 1, type: "incident.alert", sentAt, alert }` envelope, times out delivery, and retries one `429`/`5xx` response. Explicit loopback HTTP can be enabled for a local collector with `allowHttpLoopback: true`:
+
+```ts
+import { createWotchi, webhookNotifier } from "@futurewindai/wotchi";
+
+const wotchi = createWotchi({
+  service: "orders-api",
+  environment: "production",
+  notifiers: [
+    webhookNotifier({
+      url: requiredEnv("WOTCHI_WEBHOOK_URL"),
+      headers: { Authorization: requiredEnv("WOTCHI_WEBHOOK_AUTH") },
+      payloadBuilder: (alert) => ({
+        incident: alert.fingerprint,
+        summary: alert.summary,
+      }),
+    }),
+  ],
+});
+
+function requiredEnv(name: string): string {
+  const value = process.env[name];
+  if (value === undefined || value.trim() === "") {
+    throw new Error(`${name} must be configured before enabling the webhook`);
+  }
+  return value;
+}
+```
+
+Keep the URL and authentication header outside source control. `payloadBuilder` receives a frozen, sanitized alert and its output is redacted and bounded before transport; it is not a hosted Wotchi collector.
+
+## Context, filtering, and existing traces
+
+Pass safe operational context and an existing OpenTelemetry trace/span ID explicitly; Wotchi does not install an OpenTelemetry SDK:
+
+```ts
+wotchi.captureEvent({
+  level: "error",
+  message: "payment provider failed",
+  error,
+  request: {
+    method: "POST",
+    route: "/orders/:id",
+    requestId: "req-123",
+    correlationId: "corr-456",
+    trace: { traceId, spanId },
+  },
+  operation: "orders.pay",
+  job: "payment-retry",
+  tags: { component: "checkout" },
+  context: { provider: "stripe" },
+});
+```
+
+Use `filter`, `fingerprint`, `beforeSend`, and bounded exact-match `rules` for service-specific noise and grouping controls. `filter` and fingerprint callbacks receive frozen, normalized, redacted events. `beforeSend` receives a frozen, sanitized `IncidentAlert`; return `null` to suppress it or a bounded alert to transform it. Hook failures are isolated and counted in diagnostics. Optional `links.log` and `links.trace` templates can use placeholders such as `{{service}}`, `{{requestId}}`, and `{{traceId}}`.
+
+## Deployment boundaries
+
+Wotchi keeps grouping and cooldown state in one process. Replicas have independent state, restarts
+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).
+
 ## Process monitoring
 
 Crash observation is opt-in:
@@ -147,7 +224,7 @@ const monitor = registerWotchiProcessMonitor(wotchi);
 - A full observability, APM, or log-management platform.
 - A hosted dashboard, collector, or persistent incident database.
 - An AI-generated incident-summary service in this release.
-- A Slack, Discord, email, or generic webhook notifier in this release.
+- A Slack, Discord, email, or full incident-workflow platform.
 - A Docker, Kubernetes, or Helm collector bundled into the npm SDK.
 - An automatic-remediation system.
 

package/dist/cjs/core/client.js

@@ -13,6 +13,34 @@ const redact_js_1 = require("./redact.js");
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const asString = (value) => typeof value === "string" ? value : undefined;
 const asStatusCode = (value) => typeof value === "number" && Number.isSafeInteger(value) ? value : undefined;
+const deepFreeze = (value) => {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value)) {
+        return value;
+    }
+    Object.freeze(value);
+    for (const child of Object.values(value)) {
+        deepFreeze(child);
+    }
+    return value;
+};
+const safeTrace = (value, privacy) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    const redacted = (0, redact_js_1.redactValue)(value, privacy);
+    if (!isRecord(redacted)) {
+        return undefined;
+    }
+    const traceId = asString(redacted.traceId);
+    const spanId = asString(redacted.spanId);
+    if (traceId === undefined && spanId === undefined) {
+        return undefined;
+    }
+    return {
+        ...(traceId === undefined ? {} : { traceId: traceId.slice(0, 128) }),
+        ...(spanId === undefined ? {} : { spanId: spanId.slice(0, 128) }),
+    };
+};
 const safeRecord = (value, privacy) => {
     if (value === undefined) {
         return undefined;
@@ -42,20 +70,48 @@ const safeRequest = (request, privacy) => {
     const method = asString(redacted.method);
     const route = asString(redacted.route);
     const requestId = asString(redacted.requestId);
+    const correlationId = asString(redacted.correlationId);
     const statusCode = asStatusCode(redacted.statusCode);
+    const trace = safeTrace(redacted.trace, privacy);
     if (method === undefined &&
         route === undefined &&
         requestId === undefined &&
-        statusCode === undefined) {
+        correlationId === undefined &&
+        statusCode === undefined &&
+        trace === undefined) {
         return undefined;
     }
     return {
         ...(method === undefined ? {} : { method }),
         ...(route === undefined ? {} : { route }),
         ...(requestId === undefined ? {} : { requestId }),
+        ...(correlationId === undefined ? {} : { correlationId }),
         ...(statusCode === undefined ? {} : { statusCode }),
+        ...(trace === undefined ? {} : { trace }),
     };
 };
+const safeTags = (value, privacy) => {
+    const redacted = (0, redact_js_1.redactValue)(value, { ...privacy, maxKeys: Math.min(privacy.maxKeys, 50) });
+    if (!isRecord(redacted)) {
+        return undefined;
+    }
+    const tags = {};
+    for (const [key, tagValue] of Object.entries(redacted)) {
+        if (key.length > 64 || typeof tagValue !== "string") {
+            continue;
+        }
+        tags[key] = tagValue.slice(0, 200);
+    }
+    return Object.keys(tags).length === 0 ? undefined : tags;
+};
+const safeShortString = (value, privacy, maxLength) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    const redacted = (0, redact_js_1.redactValue)(value, { ...privacy, maxStringLength: maxLength });
+    const text = asString(redacted);
+    return text === undefined ? undefined : text.slice(0, maxLength);
+};
 const safeMessage = (value, privacy) => {
     const normalized = (0, normalize_js_1.normalizeUnknown)(value, privacy);
     return typeof normalized === "string" ? normalized : "[unreadable value]";
@@ -69,6 +125,150 @@ const normalizeEventAlertThreshold = (value) => {
     }
     return value;
 };
+const safeErrorFromValue = (value, privacy) => {
+    const redacted = (0, redact_js_1.redactValue)(value, privacy);
+    if (!isRecord(redacted)) {
+        return undefined;
+    }
+    const name = asString(redacted.name);
+    const message = asString(redacted.message);
+    if (name === undefined || message === undefined) {
+        return undefined;
+    }
+    const stack = asString(redacted.stack);
+    const code = asString(redacted.code);
+    const applicationFrame = asString(redacted.applicationFrame);
+    return {
+        name,
+        message,
+        ...(stack === undefined ? {} : { stack }),
+        ...(code === undefined ? {} : { code }),
+        ...(applicationFrame === undefined
+            ? {}
+            : { applicationFrame: applicationFrame.slice(0, 1_000) }),
+    };
+};
+const safeAlertFromValue = (value, fallback, privacy) => {
+    const redacted = (0, redact_js_1.redactValue)(value, privacy);
+    if (!isRecord(redacted)) {
+        return undefined;
+    }
+    const title = asString(redacted.title);
+    const fingerprint = asString(redacted.fingerprint);
+    const summary = asString(redacted.summary);
+    const severity = asString(redacted.severity);
+    const firstSeenAt = asString(redacted.firstSeenAt);
+    const lastSeenAt = asString(redacted.lastSeenAt);
+    const service = asString(redacted.service);
+    const environment = asString(redacted.environment);
+    const occurrences = asStatusCode(redacted.occurrences);
+    if (title === undefined ||
+        fingerprint === undefined ||
+        summary === undefined ||
+        firstSeenAt === undefined ||
+        lastSeenAt === undefined ||
+        service === undefined ||
+        environment === undefined ||
+        occurrences === undefined ||
+        (severity !== "low" && severity !== "medium" && severity !== "high" && severity !== "critical")) {
+        return undefined;
+    }
+    const rawActions = redacted.suggestedActions;
+    if (!Array.isArray(rawActions)) {
+        return undefined;
+    }
+    const suggestedActions = rawActions
+        .filter((action) => typeof action === "string")
+        .slice(0, 5)
+        .map((action) => action.slice(0, 600));
+    const error = safeErrorFromValue(redacted.error, privacy);
+    const request = safeRequest(redacted.request, privacy);
+    const trace = safeTrace(redacted.trace, privacy);
+    const context = safeRecord(redacted.context, privacy);
+    const tags = safeTags(redacted.tags, privacy);
+    const linksValue = safeRecord(redacted.links, privacy);
+    const logLink = linksValue === undefined ? undefined : asString(linksValue.log);
+    const traceLink = linksValue === undefined ? undefined : asString(linksValue.trace);
+    const links = linksValue
+        ? {
+            ...(logLink === undefined ? {} : { log: logLink.slice(0, 2_048) }),
+            ...(traceLink === undefined ? {} : { trace: traceLink.slice(0, 2_048) }),
+        }
+        : undefined;
+    const instance = asString(redacted.instance);
+    const release = asString(redacted.release);
+    const correlationId = asString(redacted.correlationId);
+    const operation = asString(redacted.operation);
+    const job = asString(redacted.job);
+    return deepFreeze({
+        id: asString(redacted.id) ?? fallback.id,
+        fingerprint: fingerprint.slice(0, 200),
+        title: title.slice(0, 300),
+        severity,
+        summary: summary.slice(0, 2_000),
+        suggestedActions,
+        firstSeenAt: firstSeenAt.slice(0, 100),
+        lastSeenAt: lastSeenAt.slice(0, 100),
+        occurrences: Math.max(0, Math.min(occurrences, Number.MAX_SAFE_INTEGER)),
+        service: service.slice(0, 300),
+        environment: environment.slice(0, 300),
+        ...(instance === undefined ? {} : { instance: instance.slice(0, 200) }),
+        ...(release === undefined ? {} : { release: release.slice(0, 200) }),
+        ...(correlationId === undefined ? {} : { correlationId: correlationId.slice(0, 200) }),
+        ...(operation === undefined ? {} : { operation: operation.slice(0, 200) }),
+        ...(job === undefined ? {} : { job: job.slice(0, 200) }),
+        ...(tags === undefined ? {} : { tags }),
+        ...(error === undefined ? {} : { error }),
+        ...(request === undefined ? {} : { request }),
+        ...(trace === undefined ? {} : { trace }),
+        ...(context === undefined ? {} : { context }),
+        ...(links === undefined || Object.keys(links).length === 0 ? {} : { links }),
+    });
+};
+const normalizeFingerprintOverride = (override, event) => {
+    if (override === undefined) {
+        return undefined;
+    }
+    const value = typeof override === "function" ? override(event) : override;
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string" || value.trim().length === 0 || value.length > 200) {
+        throw new TypeError("fingerprint must be a non-empty string no longer than 200 characters");
+    }
+    return value.trim();
+};
+const renderLinks = (templates, event, fingerprint) => {
+    if (templates === undefined) {
+        return undefined;
+    }
+    const values = {
+        service: event.service,
+        environment: event.environment,
+        release: event.release ?? "",
+        instance: event.instance ?? "",
+        fingerprint,
+        requestId: event.request?.requestId ?? "",
+        correlationId: event.correlationId ?? event.request?.correlationId ?? "",
+        traceId: event.trace?.traceId ?? event.request?.trace?.traceId ?? "",
+        spanId: event.trace?.spanId ?? event.request?.trace?.spanId ?? "",
+        route: event.request?.route ?? "",
+        statusCode: event.request?.statusCode === undefined ? "" : String(event.request.statusCode),
+    };
+    const render = (template) => {
+        const expanded = template.replace(/\{\{([^{}]+)\}\}/g, (_match, key) => encodeURIComponent(values[key] ?? ""));
+        const redacted = (0, redact_js_1.redactValue)(expanded, { maxStringLength: 2_048 });
+        return typeof redacted === "string" ? redacted.slice(0, 2_048) : "";
+    };
+    const result = {};
+    if (templates.log !== undefined) {
+        result.log = render(templates.log);
+    }
+    if (templates.trace !== undefined && (values.traceId !== "" || values.spanId !== "")) {
+        result.trace = render(templates.trace);
+    }
+    return Object.keys(result).length === 0 ? undefined : result;
+};
 function createWotchi(config) {
     const normalized = (0, config_js_1.validateConfig)(config);
     const now = Date.now;
@@ -85,45 +285,132 @@ function createWotchi(config) {
     });
     const privacy = normalized.privacy;
     let eventSequence = 0;
-    const captureSafeEvent = (error, metadata, context, request, eventKind = "error", alertThreshold = normalized.grouping.alertThreshold) => {
+    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) => {
         const timestamp = now();
         const safeError = (0, redact_js_1.redactError)((0, normalize_js_1.normalizeError)(error, privacy), privacy);
         const requestContext = safeRequest(request, privacy);
         const eventContext = mergeContext(metadata, context, privacy);
+        const requestTrace = safeTrace(trace ?? requestContext?.trace, privacy);
+        const eventCorrelationId = safeShortString(correlationId ?? requestContext?.correlationId, privacy, 200);
+        const operationValue = safeShortString(operation ?? eventContext?.operation, privacy, 200);
+        const jobValue = safeShortString(job ?? eventContext?.job ?? eventContext?.queue, privacy, 200);
+        const eventTags = safeTags(tags, privacy);
         const safeEvent = {
             id: `event-${eventSequence + 1}`,
             timestamp: new Date(timestamp).toISOString(),
             service: normalized.service,
             environment: normalized.environment,
+            ...(normalized.instance === undefined ? {} : { instance: normalized.instance }),
             ...(normalized.release === undefined ? {} : { release: normalized.release }),
+            ...(eventCorrelationId === undefined ? {} : { correlationId: eventCorrelationId }),
+            ...(operationValue === undefined ? {} : { operation: operationValue.slice(0, 200) }),
+            ...(jobValue === undefined ? {} : { job: jobValue.slice(0, 200) }),
+            ...(eventTags === undefined ? {} : { tags: eventTags }),
             error: safeError,
             ...(requestContext === undefined ? {} : { request: requestContext }),
+            ...(requestTrace === undefined ? {} : { trace: requestTrace }),
             ...(eventContext === undefined ? {} : { context: eventContext }),
         };
         eventSequence += 1;
-        const fingerprint = (0, fingerprint_js_1.fingerprintSafeErrorEvent)(safeEvent);
-        const group = groupStore.record(fingerprint, safeEvent);
-        const decision = (0, incident_policy_js_1.evaluateIncidentPolicy)({
+        const filteredEvent = deepFreeze(safeEvent);
+        if (normalized.filter !== undefined) {
+            try {
+                const accepted = normalized.filter(filteredEvent);
+                if (typeof accepted !== "boolean") {
+                    diagnostics.filterFailures += 1;
+                    diagnostics.eventsSuppressed += 1;
+                    return;
+                }
+                if (!accepted) {
+                    diagnostics.eventsSuppressed += 1;
+                    return;
+                }
+            }
+            catch {
+                diagnostics.filterFailures += 1;
+                diagnostics.eventsSuppressed += 1;
+                return;
+            }
+        }
+        const rule = matchingRule(filteredEvent);
+        if (rule?.ignore === true) {
+            diagnostics.eventsSuppressed += 1;
+            return;
+        }
+        let fingerprint;
+        try {
+            fingerprint = normalizeFingerprintOverride(fingerprintOverride, filteredEvent);
+        }
+        catch {
+            diagnostics.fingerprintCallbackFailures += 1;
+        }
+        if (fingerprint === undefined && normalized.fingerprint !== undefined) {
+            try {
+                fingerprint = normalizeFingerprintOverride(normalized.fingerprint, filteredEvent);
+            }
+            catch {
+                diagnostics.fingerprintCallbackFailures += 1;
+            }
+        }
+        fingerprint ??= (0, fingerprint_js_1.fingerprintSafeErrorEvent)(filteredEvent);
+        const group = groupStore.record(fingerprint, filteredEvent, rule?.severity ?? severityOverride ?? "medium");
+        const policyInput = {
             group,
             now: timestamp,
-            alertThreshold,
+            alertThreshold: rule?.alertThreshold ?? alertThreshold,
             cooldownMs: normalized.grouping.cooldownMs,
             eventKind,
-        });
+        };
+        const manualSeverity = rule?.severity ?? severityOverride;
+        const decision = manualSeverity === undefined
+            ? (0, incident_policy_js_1.evaluateIncidentPolicy)(policyInput)
+            : (0, incident_policy_js_1.evaluateIncidentPolicy)({ ...policyInput, manualSeverity });
         if (decision.shouldAlert) {
-            const alert = (0, incident_builder_js_1.buildIncidentAlert)(group, decision);
-            if (queue.enqueue(alert, normalized.notifiers)) {
+            const builtAlert = (0, incident_builder_js_1.buildIncidentAlert)(group, decision);
+            const links = renderLinks(normalized.links, filteredEvent, fingerprint);
+            const alert = deepFreeze({
+                ...builtAlert,
+                ...(links === undefined ? {} : { links }),
+            });
+            let finalAlert = alert;
+            if (normalized.beforeSend !== undefined) {
+                let transformed;
+                try {
+                    transformed = normalized.beforeSend(alert);
+                }
+                catch {
+                    diagnostics.beforeSendFailures += 1;
+                    diagnostics.eventsSuppressed += 1;
+                    return;
+                }
+                if (transformed === null) {
+                    diagnostics.eventsSuppressed += 1;
+                    return;
+                }
+                if (transformed !== undefined) {
+                    const sanitized = safeAlertFromValue(transformed, alert, privacy);
+                    if (sanitized === undefined) {
+                        diagnostics.beforeSendFailures += 1;
+                        diagnostics.eventsSuppressed += 1;
+                        return;
+                    }
+                    finalAlert = sanitized;
+                }
+            }
+            if (queue.enqueue(finalAlert, normalized.notifiers)) {
                 groupStore.markAlerted(fingerprint, timestamp);
             }
         }
         diagnostics.capturedEvents += 1;
     };
-    const captureException = (error, context) => {
+    const captureException = (error, context, options) => {
         if (!normalized.enabled) {
             return;
         }
         try {
-            captureSafeEvent(error, undefined, context, undefined);
+            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 {
             diagnostics.captureFailures += 1;
@@ -141,24 +428,86 @@ function createWotchi(config) {
                 throw new TypeError("event.message must be a string");
             }
             const alertThreshold = normalizeEventAlertThreshold(event.alertThreshold);
-            captureSafeEvent(event.error ?? safeMessage(event.message, privacy), event.metadata, event.context, event.request, event.kind ?? "error", alertThreshold ?? normalized.grouping.alertThreshold);
+            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 {
             diagnostics.captureFailures += 1;
         }
     };
+    const readDiagnostics = () => (0, diagnostics_js_1.snapshotDiagnostics)(diagnostics, {
+        groupsEvicted: groupStore.groupsEvicted(),
+        alertsQueued: queue.alertsQueued(),
+        alertsDropped: queue.alertsDropped(),
+        alertsSent: queue.alertsSent(),
+        notifierFailures: queue.notifierFailures(),
+        activeGroups: groupStore.size(),
+        pendingAlerts: queue.pending(),
+    });
+    const testAlert = async () => {
+        const timestamp = new Date(now()).toISOString();
+        const alert = {
+            id: `wotchi-test-${timestamp}`,
+            fingerprint: "wotchi-test-alert",
+            title: "Wotchi — Test alert",
+            severity: "low",
+            summary: "This is a notifier configuration test alert.",
+            suggestedActions: ["Confirm this destination received the test alert."],
+            firstSeenAt: timestamp,
+            lastSeenAt: timestamp,
+            occurrences: 1,
+            service: normalized.service,
+            environment: normalized.environment,
+            ...(normalized.instance === undefined ? {} : { instance: normalized.instance }),
+            ...(normalized.release === undefined ? {} : { release: normalized.release }),
+        };
+        let jobResult;
+        if (!queue.enqueue(alert, normalized.notifiers, (result) => {
+            jobResult = result;
+        })) {
+            return {
+                status: "queue-full",
+                configurationAccepted: true,
+                queued: false,
+                flushed: false,
+                delivered: false,
+                notifierFailures: 0,
+                diagnostics: readDiagnostics(),
+                error: "Notification queue is full; test alert was not queued.",
+            };
+        }
+        try {
+            await queue.flush();
+        }
+        catch {
+            return {
+                status: "timeout",
+                configurationAccepted: true,
+                queued: true,
+                flushed: false,
+                delivered: false,
+                notifierFailures: jobResult?.notifierFailures ?? 0,
+                diagnostics: readDiagnostics(),
+                error: "Notification queue flush timed out.",
+            };
+        }
+        const notifierFailures = jobResult?.notifierFailures ?? 0;
+        const status = notifierFailures > 0 ? "notifier-failed" : "sent";
+        return {
+            status,
+            configurationAccepted: true,
+            queued: true,
+            flushed: true,
+            delivered: status === "sent",
+            notifierFailures,
+            diagnostics: readDiagnostics(),
+            ...(status === "notifier-failed" ? { error: "One or more notifiers failed." } : {}),
+        };
+    };
     return {
         captureException,
         captureEvent,
+        testAlert,
         flush: (timeoutMs) => queue.flush(timeoutMs),
-        getDiagnostics: () => (0, diagnostics_js_1.snapshotDiagnostics)(diagnostics, {
-            groupsEvicted: groupStore.groupsEvicted(),
-            alertsQueued: queue.alertsQueued(),
-            alertsDropped: queue.alertsDropped(),
-            alertsSent: queue.alertsSent(),
-            notifierFailures: queue.notifierFailures(),
-            activeGroups: groupStore.size(),
-            pendingAlerts: queue.pending(),
-        }),
+        getDiagnostics: readDiagnostics,
     };
 }