@futurewindai/wotchi 0.1.0-beta.1

package/dist/esm/core/client.js

@@ -0,0 +1,151 @@
+import { validateConfig } from "./config.js";
+import { createDiagnosticsState, snapshotDiagnostics } from "./diagnostics.js";
+import { fingerprintSafeErrorEvent } from "./fingerprint.js";
+import { createGroupStore } from "./group-store.js";
+import { buildIncidentAlert } from "./incident-builder.js";
+import { evaluateIncidentPolicy } from "./incident-policy.js";
+import { normalizeError, normalizeUnknown } from "./normalize.js";
+import { createNotificationQueue } from "./notification-queue.js";
+import { redactError, redactValue } from "./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 safeRecord = (value, privacy) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    const redacted = redactValue(value, privacy);
+    return isRecord(redacted) ? redacted : undefined;
+};
+const mergeContext = (metadata, context, privacy) => {
+    if (metadata === undefined && context === undefined) {
+        return undefined;
+    }
+    const metadataValue = safeRecord(metadata, privacy);
+    const contextValue = safeRecord(context, privacy);
+    if (metadataValue === undefined && contextValue === undefined) {
+        return undefined;
+    }
+    return { ...(metadataValue ?? {}), ...(contextValue ?? {}) };
+};
+const safeRequest = (request, privacy) => {
+    if (request === undefined) {
+        return undefined;
+    }
+    const redacted = redactValue(request, privacy);
+    if (!isRecord(redacted)) {
+        return undefined;
+    }
+    const method = asString(redacted.method);
+    const route = asString(redacted.route);
+    const requestId = asString(redacted.requestId);
+    const statusCode = asStatusCode(redacted.statusCode);
+    if (method === undefined &&
+        route === undefined &&
+        requestId === undefined &&
+        statusCode === undefined) {
+        return undefined;
+    }
+    return {
+        ...(method === undefined ? {} : { method }),
+        ...(route === undefined ? {} : { route }),
+        ...(requestId === undefined ? {} : { requestId }),
+        ...(statusCode === undefined ? {} : { statusCode }),
+    };
+};
+const safeMessage = (value, privacy) => {
+    const normalized = normalizeUnknown(value, privacy);
+    return typeof normalized === "string" ? normalized : "[unreadable value]";
+};
+export function createWotchi(config) {
+    const normalized = validateConfig(config);
+    const now = Date.now;
+    const groupStore = createGroupStore({
+        maxGroups: normalized.grouping.maxGroups,
+        maxEventsPerWindow: normalized.grouping.maxEventsPerWindow,
+        windowMs: normalized.grouping.windowMs,
+        now,
+    });
+    const diagnostics = createDiagnosticsState();
+    const queue = createNotificationQueue({
+        maxPendingAlerts: normalized.queue.maxPendingAlerts,
+        concurrency: normalized.queue.concurrency,
+    });
+    const privacy = normalized.privacy;
+    let eventSequence = 0;
+    const captureSafeEvent = (error, metadata, context, request, eventKind = "error") => {
+        const timestamp = now();
+        const safeError = redactError(normalizeError(error, privacy), privacy);
+        const requestContext = safeRequest(request, privacy);
+        const eventContext = mergeContext(metadata, context, privacy);
+        const safeEvent = {
+            id: `event-${eventSequence + 1}`,
+            timestamp: new Date(timestamp).toISOString(),
+            service: normalized.service,
+            environment: normalized.environment,
+            ...(normalized.release === undefined ? {} : { release: normalized.release }),
+            error: safeError,
+            ...(requestContext === undefined ? {} : { request: requestContext }),
+            ...(eventContext === undefined ? {} : { context: eventContext }),
+        };
+        eventSequence += 1;
+        const fingerprint = fingerprintSafeErrorEvent(safeEvent);
+        const group = groupStore.record(fingerprint, safeEvent);
+        const decision = evaluateIncidentPolicy({
+            group,
+            now: timestamp,
+            alertThreshold: normalized.grouping.alertThreshold,
+            cooldownMs: normalized.grouping.cooldownMs,
+            eventKind,
+        });
+        if (decision.shouldAlert) {
+            const alert = buildIncidentAlert(group, decision);
+            if (queue.enqueue(alert, normalized.notifiers)) {
+                groupStore.markAlerted(fingerprint, timestamp);
+            }
+        }
+        diagnostics.capturedEvents += 1;
+    };
+    const captureException = (error, context) => {
+        if (!normalized.enabled) {
+            return;
+        }
+        try {
+            captureSafeEvent(error, undefined, context, undefined);
+        }
+        catch {
+            diagnostics.captureFailures += 1;
+        }
+    };
+    const captureEvent = (event) => {
+        if (!normalized.enabled) {
+            return;
+        }
+        try {
+            if (event === null || typeof event !== "object" || event.level !== "error") {
+                throw new TypeError("event.level must be error");
+            }
+            if (typeof event.message !== "string") {
+                throw new TypeError("event.message must be a string");
+            }
+            captureSafeEvent(event.error ?? safeMessage(event.message, privacy), event.metadata, event.context, event.request, event.kind ?? "error");
+        }
+        catch {
+            diagnostics.captureFailures += 1;
+        }
+    };
+    return {
+        captureException,
+        captureEvent,
+        flush: (timeoutMs) => queue.flush(timeoutMs),
+        getDiagnostics: () => snapshotDiagnostics(diagnostics, {
+            groupsEvicted: groupStore.groupsEvicted(),
+            alertsQueued: queue.alertsQueued(),
+            alertsDropped: queue.alertsDropped(),
+            alertsSent: queue.alertsSent(),
+            notifierFailures: queue.notifierFailures(),
+            activeGroups: groupStore.size(),
+            pendingAlerts: queue.pending(),
+        }),
+    };
+}

package/dist/esm/core/config.js

@@ -0,0 +1,110 @@
+import { WotchiConfigurationError } from "./errors.js";
+export { WotchiConfigurationError };
+const MAX_REDACT_KEYS = 100;
+const isRecord = (value) => typeof value === "object" && value !== null;
+const fail = (field) => {
+    throw new WotchiConfigurationError(`${field} is invalid`);
+};
+const readPositiveInteger = (parent, field, defaultValue) => {
+    const value = parent?.[field];
+    if (value === undefined) {
+        return defaultValue;
+    }
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+        return fail(field);
+    }
+    return value;
+};
+const readOptionalRecord = (value, field) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isRecord(value)) {
+        return fail(field);
+    }
+    return value;
+};
+const normalizeRedactKeys = (privacy) => {
+    const value = privacy?.redactKeys;
+    if (value === undefined) {
+        return Object.freeze([]);
+    }
+    if (!Array.isArray(value) || value.length > MAX_REDACT_KEYS) {
+        return fail("privacy.redactKeys");
+    }
+    const keys = value.map((key, index) => {
+        if (typeof key !== "string" || key.trim().length === 0) {
+            return fail(`privacy.redactKeys[${index}]`);
+        }
+        return key.trim();
+    });
+    return Object.freeze([...new Set(keys)]);
+};
+const normalizeNotifiers = (value) => {
+    if (!Array.isArray(value) || value.length === 0) {
+        return fail("notifiers");
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        const notifier = value[index];
+        if (!isRecord(notifier) ||
+            typeof notifier.name !== "string" ||
+            notifier.name.trim().length === 0 ||
+            typeof notifier.send !== "function") {
+            return fail(`notifiers[${index}]`);
+        }
+    }
+    return Object.freeze([...value]);
+};
+export function validateConfig(config) {
+    if (!isRecord(config)) {
+        return fail("config");
+    }
+    const service = config.service;
+    if (typeof service !== "string" || service.trim().length === 0) {
+        return fail("service");
+    }
+    const environment = config.environment;
+    if (typeof environment !== "string" || environment.trim().length === 0) {
+        return fail("environment");
+    }
+    if (config.release !== undefined &&
+        (typeof config.release !== "string" || config.release.trim().length === 0)) {
+        return fail("release");
+    }
+    if (config.enabled !== undefined && typeof config.enabled !== "boolean") {
+        return fail("enabled");
+    }
+    const grouping = readOptionalRecord(config.grouping, "grouping");
+    const queue = readOptionalRecord(config.queue, "queue");
+    const privacy = readOptionalRecord(config.privacy, "privacy");
+    const concurrency = queue?.concurrency;
+    if (concurrency !== undefined && concurrency !== 1) {
+        return fail("queue.concurrency");
+    }
+    const normalized = {
+        service: service.trim(),
+        environment: environment.trim(),
+        ...(config.release === undefined ? {} : { release: config.release.trim() }),
+        enabled: config.enabled ?? true,
+        grouping: Object.freeze({
+            windowMs: readPositiveInteger(grouping, "windowMs", 60_000),
+            alertThreshold: readPositiveInteger(grouping, "alertThreshold", 3),
+            cooldownMs: readPositiveInteger(grouping, "cooldownMs", 900_000),
+            maxGroups: readPositiveInteger(grouping, "maxGroups", 200),
+            maxEventsPerWindow: readPositiveInteger(grouping, "maxEventsPerWindow", 100),
+        }),
+        queue: Object.freeze({
+            maxPendingAlerts: readPositiveInteger(queue, "maxPendingAlerts", 100),
+            concurrency: 1,
+        }),
+        privacy: Object.freeze({
+            redactKeys: normalizeRedactKeys(privacy),
+            maxDepth: readPositiveInteger(privacy, "maxDepth", 5),
+            maxKeys: readPositiveInteger(privacy, "maxKeys", 100),
+            maxStringLength: readPositiveInteger(privacy, "maxStringLength", 500),
+            maxStackLength: readPositiveInteger(privacy, "maxStackLength", 4_000),
+        }),
+        notifiers: normalizeNotifiers(config.notifiers),
+    };
+    return Object.freeze(normalized);
+}

package/dist/esm/core/diagnostics.js

@@ -0,0 +1,10 @@
+export function createDiagnosticsState() {
+    return { capturedEvents: 0, captureFailures: 0 };
+}
+export function snapshotDiagnostics(state, values) {
+    return Object.freeze({
+        capturedEvents: state.capturedEvents,
+        captureFailures: state.captureFailures,
+        ...values,
+    });
+}

package/dist/esm/core/errors.js

@@ -0,0 +1,7 @@
+export class WotchiConfigurationError extends Error {
+    constructor(message) {
+        super(`Invalid Wotchi configuration: ${message}`);
+        this.name = "WotchiConfigurationError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}

package/dist/esm/core/fingerprint.js

@@ -0,0 +1,33 @@
+import { createHash } from "node:crypto";
+import { redactValue } from "./redact.js";
+import { selectApplicationFrame } from "./stack-frame.js";
+const UUID_PATTERN = /\b[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\b/gi;
+const HEX_PATTERN = /\b(?:0x)?[0-9a-f]{8,}\b/gi;
+const NUMBER_PATTERN = /\b\d+\b/g;
+export function normalizeDynamicSegments(value) {
+    return value
+        .replace(UUID_PATTERN, "<uuid>")
+        .replace(HEX_PATTERN, "<hex>")
+        .replace(NUMBER_PATTERN, "<number>")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+}
+const safeText = (value) => {
+    const redacted = redactValue(value, { maxStringLength: 4_000 });
+    return typeof redacted === "string" ? redacted : "[unreadable value]";
+};
+const encodePart = (value) => `${value.length}:${value}`;
+export function fingerprintSafeErrorEvent(event) {
+    const service = normalizeDynamicSegments(safeText(event.service));
+    const environment = normalizeDynamicSegments(safeText(event.environment));
+    const errorName = normalizeDynamicSegments(safeText(event.error.name));
+    const message = normalizeDynamicSegments(safeText(event.error.message));
+    const method = normalizeDynamicSegments(safeText(event.request?.method ?? ""));
+    const route = normalizeDynamicSegments(safeText(event.request?.route ?? ""));
+    const frame = normalizeDynamicSegments(selectApplicationFrame(event.error.stack) ?? "");
+    const canonical = [service, environment, errorName, message, method, route, frame]
+        .map(encodePart)
+        .join("|");
+    return createHash("sha256").update(canonical, "utf8").digest("hex");
+}

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

@@ -0,0 +1,92 @@
+import { normalizeUnknown } from "./normalize.js";
+import { createRollingWindow } from "./rolling-window.js";
+const cloneSafeEvent = (event) => {
+    const context = event.context === undefined ? undefined : normalizeUnknown(event.context);
+    return {
+        id: event.id,
+        timestamp: event.timestamp,
+        service: event.service,
+        environment: event.environment,
+        ...(event.release === undefined ? {} : { release: event.release }),
+        error: { ...event.error },
+        ...(event.request === undefined ? {} : { request: { ...event.request } }),
+        ...(context === undefined ? {} : { context: context }),
+    };
+};
+export function createGroupStore(options) {
+    if (!Number.isSafeInteger(options.maxGroups) || options.maxGroups <= 0) {
+        throw new RangeError("maxGroups must be a positive integer");
+    }
+    const now = options.now ?? Date.now;
+    const groups = new Map();
+    let evicted = 0;
+    const snapshot = (group) => ({
+        fingerprint: group.fingerprint,
+        firstSeenAt: new Date(group.firstSeenMs).toISOString(),
+        lastSeenAt: new Date(group.lastSeenMs).toISOString(),
+        totalCount: group.totalCount,
+        windowCount: group.window.count(group.lastSeenMs),
+        sample: cloneSafeEvent(group.sample),
+        ...(group.lastAlertedMs === undefined
+            ? {}
+            : { lastAlertedAt: new Date(group.lastAlertedMs).toISOString() }),
+        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);
+            evicted += 1;
+        }
+    };
+    const record = (fingerprint, event, severity = "medium") => {
+        const timestamp = now();
+        let group = groups.get(fingerprint);
+        if (group === undefined) {
+            if (groups.size >= options.maxGroups) {
+                evictLeastRecent();
+            }
+            group = {
+                fingerprint,
+                firstSeenMs: timestamp,
+                lastSeenMs: timestamp,
+                totalCount: 0,
+                sample: cloneSafeEvent(event),
+                severity,
+                window: createRollingWindow({
+                    maxEvents: options.maxEventsPerWindow,
+                    windowMs: options.windowMs,
+                    now,
+                }),
+            };
+            groups.set(fingerprint, group);
+        }
+        group.lastSeenMs = timestamp;
+        group.totalCount += 1;
+        group.severity = severity;
+        group.window.add(timestamp);
+        return snapshot(group);
+    };
+    return {
+        record,
+        get: (fingerprint) => {
+            const group = groups.get(fingerprint);
+            return group === undefined ? undefined : snapshot(group);
+        },
+        markAlerted: (fingerprint, timestamp = now()) => {
+            const group = groups.get(fingerprint);
+            if (group === undefined) {
+                return undefined;
+            }
+            group.lastAlertedMs = timestamp;
+            return snapshot(group);
+        },
+        size: () => groups.size,
+        groupsEvicted: () => evicted,
+    };
+}

package/dist/esm/core/incident-builder.js

@@ -0,0 +1,43 @@
+const titleCase = (value) => `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+const suggestedActions = (group) => {
+    const text = `${group.sample.error.name} ${group.sample.error.message}`.toLowerCase();
+    if (text.includes("database") || text.includes("query") || text.includes("sql")) {
+        return [
+            "Check database availability, connection saturation, and recent schema changes.",
+            "Check the affected query and its dependency health before increasing capacity.",
+        ];
+    }
+    if (text.includes("timeout") || text.includes("timed out")) {
+        return [
+            "Check upstream latency, timeout settings, and recent dependency changes.",
+            "Check whether retries or a dependency outage are increasing request pressure.",
+        ];
+    }
+    if (text.includes("auth") || text.includes("permission") || text.includes("unauthor")) {
+        return [
+            "Check authentication configuration, credentials, and recent access-policy changes.",
+            "Check whether the affected route is receiving an unexpected caller or token.",
+        ];
+    }
+    return [
+        "Check the application logs and the selected stack frame for the first failing operation.",
+        "Check recent deployments, dependency health, and the affected request path.",
+    ];
+};
+export function buildIncidentAlert(group, decision) {
+    const message = group.sample.error.message;
+    const errorName = group.sample.error.name;
+    return {
+        id: `wotchi-${group.fingerprint}-${group.lastSeenAt}`,
+        fingerprint: group.fingerprint,
+        title: `Wotchi — ${titleCase(decision.severity)} incident`,
+        severity: decision.severity,
+        summary: `Observed ${group.windowCount} occurrences of ${errorName}: ${message}.`,
+        suggestedActions: suggestedActions(group),
+        firstSeenAt: group.firstSeenAt,
+        lastSeenAt: group.lastSeenAt,
+        occurrences: group.windowCount,
+        service: group.sample.service,
+        environment: group.sample.environment,
+    };
+}

package/dist/esm/core/incident-policy.js

@@ -0,0 +1,28 @@
+const hasCooldown = (group, now, cooldownMs) => {
+    if (group.lastAlertedAt === undefined) {
+        return false;
+    }
+    const lastAlerted = Date.parse(group.lastAlertedAt);
+    return Number.isFinite(lastAlerted) && now - lastAlerted < cooldownMs;
+};
+const hasUnavailableResponse = (group) => group.sample.request?.statusCode === 503;
+export function evaluateIncidentPolicy(input) {
+    const eventKind = input.eventKind ?? "error";
+    const isCritical = eventKind === "process-monitor";
+    const isHigh = input.group.windowCount >= 20 || hasUnavailableResponse(input.group);
+    const severity = isCritical
+        ? "critical"
+        : isHigh
+            ? "high"
+            : eventKind === "manual"
+                ? (input.manualSeverity ?? "low")
+                : "medium";
+    const eligible = isCritical ||
+        isHigh ||
+        eventKind === "manual" ||
+        input.group.windowCount >= input.alertThreshold;
+    return {
+        shouldAlert: eligible && !hasCooldown(input.group, input.now, input.cooldownMs),
+        severity,
+    };
+}

package/dist/esm/core/normalize.js

@@ -0,0 +1,134 @@
+const UNREADABLE_VALUE = "[unreadable value]";
+const MAX_DEPTH_VALUE = "[MaxDepth]";
+const CIRCULAR_VALUE = "[Circular]";
+const MAX_KEYS_VALUE = "[MaxKeys]";
+const defaultLimits = {
+    maxDepth: 5,
+    maxKeys: 100,
+    maxStringLength: 500,
+    maxStackLength: 4_000,
+};
+const boundedLimit = (value, fallback) => Number.isSafeInteger(value) && value > 0 ? value : fallback;
+const normalizeLimits = (limits) => ({
+    maxDepth: boundedLimit(limits?.maxDepth ?? defaultLimits.maxDepth, defaultLimits.maxDepth),
+    maxKeys: boundedLimit(limits?.maxKeys ?? defaultLimits.maxKeys, defaultLimits.maxKeys),
+    maxStringLength: boundedLimit(limits?.maxStringLength ?? defaultLimits.maxStringLength, defaultLimits.maxStringLength),
+    maxStackLength: boundedLimit(limits?.maxStackLength ?? defaultLimits.maxStackLength, defaultLimits.maxStackLength),
+});
+const truncate = (value, limit) => value.slice(0, limit);
+const readProperty = (value, key) => {
+    try {
+        return value[key];
+    }
+    catch {
+        return UNREADABLE_VALUE;
+    }
+};
+const normalizePrimitive = (value, limits) => {
+    if (value === null) {
+        return null;
+    }
+    switch (typeof value) {
+        case "string":
+            return truncate(value, limits.maxStringLength);
+        case "boolean":
+            return value;
+        case "number":
+            return Number.isFinite(value) ? value : "[non-finite number]";
+        case "undefined":
+            return "[undefined]";
+        case "bigint":
+            return "[bigint]";
+        case "symbol":
+            return "[symbol]";
+        case "function":
+            return "[function]";
+        default:
+            return UNREADABLE_VALUE;
+    }
+};
+const normalizeValue = (value, depth, state, limits) => {
+    if (value === null || typeof value !== "object") {
+        return normalizePrimitive(value, limits);
+    }
+    if (depth >= limits.maxDepth) {
+        return MAX_DEPTH_VALUE;
+    }
+    if (state.seen.has(value)) {
+        return CIRCULAR_VALUE;
+    }
+    state.seen.add(value);
+    if (Array.isArray(value)) {
+        const result = [];
+        let length;
+        try {
+            length = Math.min(value.length, limits.maxKeys - state.keysVisited);
+        }
+        catch {
+            return UNREADABLE_VALUE;
+        }
+        for (let index = 0; index < length; index += 1) {
+            if (state.keysVisited >= limits.maxKeys) {
+                break;
+            }
+            state.keysVisited += 1;
+            result.push(normalizeValue(readProperty(value, String(index)), depth + 1, state, limits));
+        }
+        return result;
+    }
+    let keys;
+    try {
+        keys = Object.keys(value);
+    }
+    catch {
+        return UNREADABLE_VALUE;
+    }
+    const result = {};
+    for (const key of keys) {
+        if (state.keysVisited >= limits.maxKeys - 1) {
+            result["[truncated]"] = MAX_KEYS_VALUE;
+            break;
+        }
+        state.keysVisited += 1;
+        result[truncate(key, limits.maxStringLength)] = normalizeValue(readProperty(value, key), depth + 1, state, limits);
+    }
+    return result;
+};
+export function normalizeUnknown(value, limits) {
+    const normalizedLimits = normalizeLimits(limits);
+    try {
+        return normalizeValue(value, 0, { seen: new WeakSet(), keysVisited: 0 }, normalizedLimits);
+    }
+    catch {
+        return UNREADABLE_VALUE;
+    }
+}
+const safeStringProperty = (value, key, fallback, limit) => {
+    const property = readProperty(value, key);
+    return typeof property === "string" ? truncate(property, limit) : fallback;
+};
+export function normalizeError(error, limits) {
+    const normalizedLimits = normalizeLimits(limits);
+    let isError;
+    try {
+        isError = error instanceof Error;
+    }
+    catch {
+        isError = false;
+    }
+    if (isError && error !== null && typeof error === "object") {
+        const name = safeStringProperty(error, "name", "Error", normalizedLimits.maxStringLength);
+        const message = safeStringProperty(error, "message", UNREADABLE_VALUE, normalizedLimits.maxStringLength);
+        const stack = safeStringProperty(error, "stack", "", normalizedLimits.maxStackLength);
+        const code = safeStringProperty(error, "code", "", normalizedLimits.maxStringLength);
+        return {
+            name: name || "Error",
+            message,
+            ...(stack ? { stack } : {}),
+            ...(code ? { code } : {}),
+        };
+    }
+    const normalized = normalizeUnknown(error, normalizedLimits);
+    const message = typeof normalized === "string" ? normalized : UNREADABLE_VALUE;
+    return { name: "UnknownError", message };
+}