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

package/dist/esm/integrations/express/status-observer.js

@@ -0,0 +1,83 @@
+import { getExpressRequestContext } from "./request-context.js";
+import { wasExpressErrorCaptured } from "./state.js";
+const DEFAULT_STATUS_CODES = [401, 403, 429];
+const DEFAULT_STATUS_CLASSES = ["5xx"];
+const MAX_STATUS_CODES = 100;
+const normalizeStatuses = (values, defaults) => {
+    const selected = values ?? defaults;
+    if (selected.length > MAX_STATUS_CODES) {
+        throw new TypeError("statusCodes must contain at most 100 values");
+    }
+    for (const status of selected) {
+        if (!Number.isSafeInteger(status) || status < 100 || status > 599) {
+            throw new TypeError("statusCodes must contain HTTP status codes from 100 through 599");
+        }
+    }
+    return new Set(selected);
+};
+const normalizeStatusClasses = (values) => {
+    const selected = values ?? DEFAULT_STATUS_CLASSES;
+    for (const statusClass of selected) {
+        if (statusClass !== "4xx" && statusClass !== "5xx") {
+            throw new TypeError('statusClasses must contain only "4xx" or "5xx"');
+        }
+    }
+    return new Set(selected);
+};
+const normalizeAlertThreshold = (value) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Number.isSafeInteger(value) || value <= 0 || value > 1_000_000) {
+        throw new TypeError("alertThreshold must be a positive integer no greater than 1000000");
+    }
+    return value;
+};
+const normalizeOptions = (options) => {
+    const alertThreshold = normalizeAlertThreshold(options?.alertThreshold);
+    return {
+        ...(options?.requestIdProperty === undefined
+            ? {}
+            : { requestIdProperty: options.requestIdProperty }),
+        ...(options?.correlationIdProperty === undefined
+            ? {}
+            : { correlationIdProperty: options.correlationIdProperty }),
+        ...(options?.traceContextProperty === undefined
+            ? {}
+            : { traceContextProperty: options.traceContextProperty }),
+        statusCodes: normalizeStatuses(options?.statusCodes, DEFAULT_STATUS_CODES),
+        statusClasses: normalizeStatusClasses(options?.statusClasses),
+        ignoreStatusCodes: normalizeStatuses(options?.ignoreStatusCodes, []),
+        ...(alertThreshold === undefined ? {} : { alertThreshold }),
+    };
+};
+const isObservedStatus = (statusCode, options) => !options.ignoreStatusCodes.has(statusCode) &&
+    (options.statusCodes.has(statusCode) ||
+        (statusCode >= 400 && statusCode < 500 && options.statusClasses.has("4xx")) ||
+        (statusCode >= 500 && statusCode < 600 && options.statusClasses.has("5xx")));
+export function wotchiStatusObserver(client, options) {
+    const normalizedOptions = normalizeOptions(options);
+    return (request, response, next) => {
+        response.once("finish", () => {
+            const statusCode = response.statusCode;
+            if (wasExpressErrorCaptured(request) || !isObservedStatus(statusCode, normalizedOptions)) {
+                return;
+            }
+            try {
+                const requestContext = getExpressRequestContext(request, response, normalizedOptions);
+                client.captureEvent({
+                    level: "error",
+                    message: `HTTP ${statusCode} response`,
+                    ...(normalizedOptions.alertThreshold === undefined
+                        ? {}
+                        : { alertThreshold: normalizedOptions.alertThreshold }),
+                    ...(requestContext === undefined ? {} : { request: requestContext }),
+                });
+            }
+            catch {
+                // Status observation must never change the host response lifecycle.
+            }
+        });
+        next();
+    };
+}

package/dist/esm/integrations/nest/exception-filter.js

@@ -9,6 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 };
 import { Catch } from "@nestjs/common";
 import { BaseExceptionFilter } from "@nestjs/core";
+import { markExpressErrorCaptured } from "../express/state.js";
 import { getNestRequestContext } from "./request-context.js";
 let WotchiNestExceptionFilter = class WotchiNestExceptionFilter extends BaseExceptionFilter {
     constructor(client, applicationRef, options) {
@@ -18,7 +19,14 @@ let WotchiNestExceptionFilter = class WotchiNestExceptionFilter extends BaseExce
     }
     catch(exception, host) {
         try {
-            this.client.captureException(exception, getNestRequestContext(host, exception, this.options));
+            markExpressErrorCaptured(host.switchToHttp().getRequest());
+        }
+        catch {
+            // Non-HTTP NestJS contexts do not expose an Express request to mark.
+        }
+        try {
+            const requestContext = getNestRequestContext(host, exception, this.options);
+            this.client.captureException(exception, undefined, requestContext === undefined ? undefined : { request: requestContext });
         }
         catch {
             // A capture failure must never change NestJS exception handling.

package/dist/esm/integrations/nest/index.js

@@ -1,2 +1,2 @@
-export { consoleNotifier, createWotchi, telegramNotifier } from "../../index.js";
-export { registerWotchiNest } from "./register.js";
+export { consoleNotifier, createWotchi, telegramNotifier, webhookNotifier } from "../../index.js";
+export { registerWotchiNest, registerWotchiNestStatusObserver } from "./register.js";

package/dist/esm/integrations/nest/register.js

@@ -1,5 +1,6 @@
 import { HttpAdapterHost } from "@nestjs/core";
 import { WotchiNestExceptionFilter } from "./exception-filter.js";
+import { wotchiStatusObserver } from "../express/status-observer.js";
 export function registerWotchiNest(app, client, options) {
     const application = app;
     const directAdapter = application.getHttpAdapter?.();
@@ -8,3 +9,10 @@ export function registerWotchiNest(app, client, options) {
         : directAdapter;
     application.useGlobalFilters(new WotchiNestExceptionFilter(client, httpAdapter, options));
 }
+export function registerWotchiNestStatusObserver(app, client, options) {
+    const application = app;
+    if (typeof application.use !== "function") {
+        throw new TypeError("Nest application does not expose use(); an Express-based adapter is required");
+    }
+    application.use(wotchiStatusObserver(client, options));
+}

package/dist/esm/integrations/request-context.js

@@ -1,5 +1,6 @@
 const MAX_ROUTE_LENGTH = 500;
 const MAX_REQUEST_ID_LENGTH = 200;
+const MAX_CORRELATION_ID_LENGTH = 200;
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const HEX_PATTERN = /^[0-9a-f]{8,}$/i;
 const isRecord = (value) => typeof value === "object" && value !== null;
@@ -28,6 +29,24 @@ const normalizeRequestIdProperty = (property) => {
     }
     return property;
 };
+const normalizeTraceContextProperty = (property) => {
+    if (property === undefined) {
+        return undefined;
+    }
+    if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(property)) {
+        throw new TypeError("traceContextProperty must be a simple property name");
+    }
+    return property;
+};
+const normalizeCorrelationIdProperty = (property) => {
+    if (property === undefined) {
+        return undefined;
+    }
+    if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(property)) {
+        throw new TypeError("correlationIdProperty must be a simple property name");
+    }
+    return property;
+};
 const readRequestId = (request, property) => {
     if (property === undefined || !isRecord(request)) {
         return undefined;
@@ -43,8 +62,51 @@ const readRequestId = (request, property) => {
         return undefined;
     }
 };
+const readTraceContext = (request, property) => {
+    if (property === undefined || !isRecord(request)) {
+        return undefined;
+    }
+    try {
+        if (!Object.prototype.hasOwnProperty.call(request, property)) {
+            return undefined;
+        }
+        const value = request[property];
+        if (!isRecord(value)) {
+            return undefined;
+        }
+        const traceId = typeof value.traceId === "string" ? value.traceId.slice(0, 128) : undefined;
+        const spanId = typeof value.spanId === "string" ? value.spanId.slice(0, 128) : undefined;
+        if (traceId === undefined && spanId === undefined) {
+            return undefined;
+        }
+        return {
+            ...(traceId === undefined ? {} : { traceId }),
+            ...(spanId === undefined ? {} : { spanId }),
+        };
+    }
+    catch {
+        return undefined;
+    }
+};
+const readCorrelationId = (request, property) => {
+    if (property === undefined || !isRecord(request)) {
+        return undefined;
+    }
+    try {
+        if (!Object.prototype.hasOwnProperty.call(request, property)) {
+            return undefined;
+        }
+        const value = request[property];
+        return typeof value === "string" ? value.slice(0, MAX_CORRELATION_ID_LENGTH) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
 export function buildRequestContext(input) {
     const requestIdProperty = normalizeRequestIdProperty(input.options?.requestIdProperty);
+    const correlationIdProperty = normalizeCorrelationIdProperty(input.options?.correlationIdProperty);
+    const traceContextProperty = normalizeTraceContextProperty(input.options?.traceContextProperty);
     let requestId;
     try {
         requestId = readRequestId(input.request, requestIdProperty);
@@ -52,6 +114,22 @@ export function buildRequestContext(input) {
     catch {
         requestId = undefined;
     }
+    let correlationId;
+    try {
+        correlationId = readCorrelationId(input.request, correlationIdProperty);
+    }
+    catch {
+        correlationId = undefined;
+    }
+    let trace;
+    try {
+        const explicitTrace = input.trace;
+        trace = readTraceContext({ trace: explicitTrace }, "trace");
+        trace ??= readTraceContext(input.request, traceContextProperty);
+    }
+    catch {
+        trace = undefined;
+    }
     const method = typeof input.method === "string" ? input.method.slice(0, 16) : undefined;
     const route = normalizeRoutePath(input.route);
     const statusCode = typeof input.statusCode === "number" && Number.isSafeInteger(input.statusCode)
@@ -60,7 +138,9 @@ export function buildRequestContext(input) {
     if (method === undefined &&
         route === undefined &&
         statusCode === undefined &&
-        requestId === undefined) {
+        requestId === undefined &&
+        correlationId === undefined &&
+        trace === undefined) {
         return undefined;
     }
     return {
@@ -68,5 +148,7 @@ export function buildRequestContext(input) {
         ...(route === undefined ? {} : { route }),
         ...(statusCode === undefined ? {} : { statusCode }),
         ...(requestId === undefined ? {} : { requestId }),
+        ...(correlationId === undefined ? {} : { correlationId }),
+        ...(trace === undefined ? {} : { trace }),
     };
 }

package/dist/esm/notifiers/alert-payload.js

@@ -0,0 +1,16 @@
+import { redactValue } from "../core/redact.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export function toBoundedPayload(value) {
+    const redacted = redactValue(value, {
+        maxDepth: 6,
+        maxKeys: 100,
+        maxStringLength: 1_000,
+        maxStackLength: 4_000,
+    });
+    return isRecord(redacted)
+        ? redacted
+        : { title: "Wotchi alert", summary: "Incident details were unavailable." };
+}
+export function toBoundedAlertPayload(alert) {
+    return toBoundedPayload(alert);
+}

package/dist/esm/notifiers/console.js

@@ -1,19 +1,109 @@
+import { redactValue } from "../core/redact.js";
+import { toBoundedAlertPayload } from "./alert-payload.js";
 const MAX_FIELD_LENGTH = 1_000;
 const MAX_ACTIONS = 5;
 const limit = (value, maxLength = MAX_FIELD_LENGTH) => value.slice(0, maxLength);
-export function formatConsoleAlert(alert) {
+const safeText = (value, maxLength = MAX_FIELD_LENGTH) => {
+    const redacted = redactValue(value, { maxStringLength: maxLength });
+    return typeof redacted === "string" ? limit(redacted, maxLength) : "[unreadable value]";
+};
+const safeJson = (value) => {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "[unreadable value]";
+    }
+};
+const boundedAlert = (alert) => {
+    const payload = toBoundedAlertPayload(alert);
+    return {
+        ...payload,
+        title: safeText(typeof payload.title === "string" ? payload.title : alert.title),
+        fingerprint: safeText(typeof payload.fingerprint === "string" ? payload.fingerprint : alert.fingerprint),
+        severity: alert.severity,
+        summary: safeText(typeof payload.summary === "string" ? payload.summary : alert.summary),
+        suggestedActions: alert.suggestedActions
+            .slice(0, MAX_ACTIONS)
+            .map((action) => safeText(action, 300)),
+        firstSeenAt: safeText(alert.firstSeenAt, 100),
+        lastSeenAt: safeText(alert.lastSeenAt, 100),
+        occurrences: Number.isSafeInteger(alert.occurrences) && alert.occurrences >= 0 ? alert.occurrences : 0,
+        service: safeText(alert.service, 300),
+        environment: safeText(alert.environment, 300),
+    };
+};
+const textDetails = (alert) => {
+    const lines = [];
+    if (alert.release !== undefined) {
+        lines.push(`Release: ${safeText(alert.release, 200)}`);
+    }
+    if (alert.instance !== undefined) {
+        lines.push(`Instance: ${safeText(alert.instance, 200)}`);
+    }
+    if (alert.operation !== undefined) {
+        lines.push(`Operation: ${safeText(alert.operation, 200)}`);
+    }
+    if (alert.job !== undefined) {
+        lines.push(`Job: ${safeText(alert.job, 200)}`);
+    }
+    if (alert.correlationId !== undefined) {
+        lines.push(`Correlation ID: ${safeText(alert.correlationId, 200)}`);
+    }
+    if (alert.tags !== undefined) {
+        lines.push(`Tags: ${safeText(safeJson(alert.tags), 600)}`);
+    }
+    if (alert.error !== undefined) {
+        lines.push(`Error: ${safeText(alert.error.name, 300)} — ${safeText(alert.error.message, 600)}`);
+        if (alert.error.applicationFrame !== undefined) {
+            lines.push(`Application frame: ${safeText(alert.error.applicationFrame, 500)}`);
+        }
+    }
+    if (alert.request !== undefined) {
+        const request = [alert.request.method, alert.request.route].filter((value) => typeof value === "string");
+        if (alert.request.statusCode !== undefined) {
+            request.push(`status ${alert.request.statusCode}`);
+        }
+        if (request.length > 0) {
+            lines.push(`Request: ${request.join(" ")}`);
+        }
+        if (alert.request.requestId !== undefined) {
+            lines.push(`Request ID: ${safeText(alert.request.requestId, 200)}`);
+        }
+        if (alert.request.correlationId !== undefined) {
+            lines.push(`Correlation ID: ${safeText(alert.request.correlationId, 200)}`);
+        }
+    }
+    const trace = alert.trace ?? alert.request?.trace;
+    if (trace?.traceId !== undefined || trace?.spanId !== undefined) {
+        lines.push(`Trace: ${safeText(trace.traceId ?? "", 128)}${trace.spanId === undefined ? "" : ` span ${safeText(trace.spanId, 128)}`}`);
+    }
+    if (alert.context !== undefined) {
+        lines.push(`Context: ${safeText(safeJson(alert.context), 1_000)}`);
+    }
+    if (alert.links !== undefined) {
+        lines.push(`Links: ${safeText(safeJson(alert.links), 600)}`);
+    }
+    return lines;
+};
+export function formatConsoleAlert(alert, format = "text") {
+    const bounded = boundedAlert(alert);
+    if (format === "json") {
+        return JSON.stringify(bounded);
+    }
     const actions = alert.suggestedActions
         .slice(0, MAX_ACTIONS)
-        .map((action) => `- ${limit(action, 300)}`)
+        .map((action) => `- ${safeText(action, 300)}`)
         .join("\n");
     return [
-        limit(alert.title),
-        `Service: ${limit(alert.service, 300)}`,
-        `Environment: ${limit(alert.environment, 300)}`,
-        `Summary: ${limit(alert.summary)}`,
-        `Occurrences: ${alert.occurrences}`,
-        `First seen: ${limit(alert.firstSeenAt, 100)}`,
-        `Last seen: ${limit(alert.lastSeenAt, 100)}`,
+        bounded.title,
+        `Service: ${bounded.service}`,
+        `Environment: ${bounded.environment}`,
+        `Summary: ${bounded.summary}`,
+        `Occurrences: ${bounded.occurrences}`,
+        `First seen: ${bounded.firstSeenAt}`,
+        `Last seen: ${bounded.lastSeenAt}`,
+        ...textDetails(alert),
         "Suggested checks:",
         actions,
     ].join("\n");
@@ -23,7 +113,7 @@ export function consoleNotifier(options) {
     return {
         name: "console",
         async send(alert) {
-            write(formatConsoleAlert(alert));
+            write(formatConsoleAlert(alert, options?.format ?? "text"));
         },
     };
 }

package/dist/esm/notifiers/telegram-format.js

@@ -1,3 +1,4 @@
+import { redactValue } from "../core/redact.js";
 const MAX_MESSAGE_LENGTH = 4_096;
 const MAX_ACTIONS = 5;
 const MAX_TITLE_LENGTH = 300;
@@ -5,9 +6,76 @@ const MAX_SERVICE_LENGTH = 300;
 const MAX_ENVIRONMENT_LENGTH = 300;
 const MAX_SUMMARY_LENGTH = 2_000;
 const MAX_ACTION_LENGTH = 600;
+const MAX_DETAIL_LENGTH = 900;
 const escapeHtml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 const limit = (value, maxLength) => value.slice(0, maxLength);
-const render = (title, service, environment, summary, actions, firstSeenAt, lastSeenAt, occurrences) => {
+const safeText = (value, maxLength) => {
+    const redacted = redactValue(value, { maxStringLength: maxLength });
+    return typeof redacted === "string" ? limit(redacted, maxLength) : "[unreadable value]";
+};
+const safeJson = (value) => {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return "[unreadable value]";
+    }
+};
+const details = (alert) => {
+    const lines = [];
+    if (alert.release !== undefined) {
+        lines.push(`Release: ${safeText(alert.release, 200)}`);
+    }
+    if (alert.instance !== undefined) {
+        lines.push(`Instance: ${safeText(alert.instance, 200)}`);
+    }
+    if (alert.operation !== undefined) {
+        lines.push(`Operation: ${safeText(alert.operation, 200)}`);
+    }
+    if (alert.job !== undefined) {
+        lines.push(`Job: ${safeText(alert.job, 200)}`);
+    }
+    if (alert.correlationId !== undefined) {
+        lines.push(`Correlation ID: ${safeText(alert.correlationId, 200)}`);
+    }
+    if (alert.tags !== undefined) {
+        lines.push(`Tags: ${safeText(safeJson(alert.tags), MAX_DETAIL_LENGTH)}`);
+    }
+    if (alert.error !== undefined) {
+        lines.push(`Error: ${safeText(alert.error.name, 250)} — ${safeText(alert.error.message, 500)}`);
+        if (alert.error.applicationFrame !== undefined) {
+            lines.push(`Application frame: ${safeText(alert.error.applicationFrame, 500)}`);
+        }
+    }
+    if (alert.request !== undefined) {
+        const request = [alert.request.method, alert.request.route].filter((value) => typeof value === "string");
+        if (alert.request.statusCode !== undefined) {
+            request.push(`status ${alert.request.statusCode}`);
+        }
+        if (request.length > 0) {
+            lines.push(`Request: ${request.join(" ")}`);
+        }
+        if (alert.request.requestId !== undefined) {
+            lines.push(`Request ID: ${safeText(alert.request.requestId, 200)}`);
+        }
+        if (alert.request.correlationId !== undefined) {
+            lines.push(`Correlation ID: ${safeText(alert.request.correlationId, 200)}`);
+        }
+    }
+    const trace = alert.trace ?? alert.request?.trace;
+    if (trace?.traceId !== undefined || trace?.spanId !== undefined) {
+        lines.push(`Trace: ${safeText(trace.traceId ?? "", 128)}${trace.spanId === undefined ? "" : ` span ${safeText(trace.spanId, 128)}`}`);
+    }
+    if (alert.context !== undefined) {
+        const redacted = redactValue(alert.context, { maxDepth: 4, maxKeys: 40, maxStringLength: 300 });
+        lines.push(`Context: ${safeText(safeJson(redacted), MAX_DETAIL_LENGTH)}`);
+    }
+    if (alert.links !== undefined) {
+        lines.push(`Links: ${safeText(safeJson(alert.links), MAX_DETAIL_LENGTH)}`);
+    }
+    return lines.map((line) => limit(line, MAX_DETAIL_LENGTH));
+};
+const render = (title, service, environment, summary, actions, context, firstSeenAt, lastSeenAt, occurrences) => {
     const actionText = actions.length === 0
         ? "- No suggested checks."
         : actions.map((action) => `- ${escapeHtml(action)}`).join("\n");
@@ -19,6 +87,7 @@ const render = (title, service, environment, summary, actions, firstSeenAt, last
         `Occurrences: ${occurrences}`,
         `First seen: ${escapeHtml(firstSeenAt)}`,
         `Last seen: ${escapeHtml(lastSeenAt)}`,
+        ...context.map((line) => escapeHtml(line)),
         "Suggested checks:",
         actionText,
     ].join("\n");
@@ -33,17 +102,18 @@ export function formatTelegramAlert(alert) {
     let actions = alert.suggestedActions
         .slice(0, MAX_ACTIONS)
         .map((action) => limit(action, MAX_ACTION_LENGTH));
-    let formatted = render(title, service, environment, summary, actions, firstSeenAt, lastSeenAt, alert.occurrences);
+    const context = details(alert);
+    let formatted = render(title, service, environment, summary, actions, context, firstSeenAt, lastSeenAt, alert.occurrences);
     while (formatted.length > MAX_MESSAGE_LENGTH && actions.length > 0) {
         actions = actions.slice(0, -1);
-        formatted = render(title, service, environment, summary, actions, firstSeenAt, lastSeenAt, alert.occurrences);
+        formatted = render(title, service, environment, summary, actions, context, firstSeenAt, lastSeenAt, alert.occurrences);
     }
     while (formatted.length > MAX_MESSAGE_LENGTH && summary.length > 0) {
         summary = summary.slice(0, Math.max(0, summary.length - 200));
-        formatted = render(title, service, environment, summary, actions, firstSeenAt, lastSeenAt, alert.occurrences);
+        formatted = render(title, service, environment, summary, actions, context, firstSeenAt, lastSeenAt, alert.occurrences);
     }
     if (formatted.length > MAX_MESSAGE_LENGTH) {
-        formatted = render(limit(title, 100), limit(service, 100), limit(environment, 100), "Incident details were truncated.", [], firstSeenAt, lastSeenAt, alert.occurrences);
+        formatted = render(limit(title, 100), limit(service, 100), limit(environment, 100), "Incident details were truncated.", [], [], firstSeenAt, lastSeenAt, alert.occurrences);
     }
     return formatted;
 }