@futurewindai/wotchi 0.1.0-beta.1

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

@@ -0,0 +1,144 @@
+import https from "node:https";
+const DEFAULT_TIMEOUT_MS = 3_000;
+const MAX_RESPONSE_BYTES = 8_192;
+const MAX_RETRY_DELAY_MS = 1_000;
+const wait = (delayMs) => new Promise((resolve) => {
+    setTimeout(resolve, delayMs);
+});
+const failRequest = () => {
+    throw new Error("Telegram request failed");
+};
+const parseRetryAfter = (body) => {
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed !== "object" || parsed === null) {
+            return 0;
+        }
+        const parameters = parsed.parameters;
+        if (typeof parameters !== "object" || parameters === null) {
+            return 0;
+        }
+        const retryAfter = parameters.retry_after;
+        return typeof retryAfter === "number" && Number.isSafeInteger(retryAfter) && retryAfter > 0
+            ? Math.min(retryAfter * 1_000, MAX_RETRY_DELAY_MS)
+            : 0;
+    }
+    catch {
+        return 0;
+    }
+};
+const isSuccessResponse = (response) => {
+    if (response.statusCode < 200 || response.statusCode >= 300) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(response.body);
+        return (typeof parsed === "object" && parsed !== null && parsed.ok === true);
+    }
+    catch {
+        return false;
+    }
+};
+const createRequestOptions = (botToken) => ({
+    protocol: "https:",
+    hostname: "api.telegram.org",
+    method: "POST",
+    path: `/bot${botToken}/sendMessage`,
+    headers: {},
+});
+const httpsRequest = (options, body, timeoutMs) => new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (callback) => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        callback();
+    };
+    const request = https.request(options, (response) => {
+        const chunks = [];
+        let size = 0;
+        response.on("data", (chunk) => {
+            size += Buffer.byteLength(chunk);
+            if (size > MAX_RESPONSE_BYTES) {
+                request.destroy();
+                finish(() => reject(new Error("Telegram response body exceeded limit")));
+                return;
+            }
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        });
+        response.once("error", (error) => finish(() => reject(error)));
+        response.once("end", () => finish(() => resolve({
+            statusCode: response.statusCode ?? 0,
+            headers: response.headers,
+            body: Buffer.concat(chunks).toString("utf8"),
+        })));
+    });
+    request.once("error", (error) => finish(() => reject(error)));
+    request.setTimeout(timeoutMs, () => {
+        request.destroy();
+        finish(() => reject(new Error("Telegram request timed out")));
+    });
+    request.end(body);
+});
+const requestWithTimeout = async (request, options, body, timeoutMs) => {
+    let timer;
+    try {
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error("Telegram request timed out")), timeoutMs);
+        });
+        return await Promise.race([request(options, body, timeoutMs), timeout]);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "Telegram request timed out") {
+            throw error;
+        }
+        if (error instanceof Error && error.message === "Telegram response body exceeded limit") {
+            throw error;
+        }
+        return failRequest();
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+};
+export async function sendTelegramMessage(options, request = httpsRequest) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 30_000) {
+        throw new TypeError("timeoutMs is invalid");
+    }
+    const body = JSON.stringify({
+        chat_id: options.chatId,
+        text: options.text,
+        parse_mode: "HTML",
+        disable_web_page_preview: true,
+    });
+    const requestOptions = createRequestOptions(options.botToken);
+    requestOptions.headers = {
+        "content-type": "application/json",
+        "content-length": Buffer.byteLength(body, "utf8"),
+    };
+    let rateLimitRetries = 0;
+    let serverRetries = 0;
+    while (true) {
+        const response = await requestWithTimeout(request, requestOptions, body, timeoutMs);
+        if (Buffer.byteLength(response.body, "utf8") > MAX_RESPONSE_BYTES) {
+            throw new Error("Telegram response body exceeded limit");
+        }
+        if (isSuccessResponse(response)) {
+            return;
+        }
+        if (response.statusCode === 429 && rateLimitRetries === 0) {
+            rateLimitRetries += 1;
+            await wait(parseRetryAfter(response.body));
+            continue;
+        }
+        if (response.statusCode >= 500 && response.statusCode <= 599 && serverRetries === 0) {
+            serverRetries += 1;
+            continue;
+        }
+        throw new Error(`Telegram API request failed with status ${response.statusCode}`);
+    }
+}

package/dist/esm/notifiers/telegram.js

@@ -0,0 +1,34 @@
+import { formatTelegramAlert } from "./telegram-format.js";
+import { sendTelegramMessage, } from "./telegram-http.js";
+const validateValue = (value, field) => {
+    if (typeof value !== "string" ||
+        value.trim().length === 0 ||
+        value.length > 200 ||
+        /[\s/?#]/.test(value)) {
+        throw new TypeError(`${field} is invalid`);
+    }
+    return value.trim();
+};
+export function createTelegramNotifier(options, request) {
+    const botToken = validateValue(options.botToken, "botToken");
+    const chatId = validateValue(options.chatId, "chatId");
+    const sendOptions = {
+        botToken,
+        chatId,
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    };
+    return {
+        name: "telegram",
+        async send(alert) {
+            const message = { ...sendOptions, text: formatTelegramAlert(alert) };
+            if (request === undefined) {
+                await sendTelegramMessage(message);
+                return;
+            }
+            await sendTelegramMessage(message, request);
+        },
+    };
+}
+export function telegramNotifier(options) {
+    return createTelegramNotifier(options);
+}

package/dist/types/core/client.d.ts

@@ -0,0 +1,2 @@
+import type { WotchiClient, WotchiConfig } from "./types.js";
+export declare function createWotchi(config: WotchiConfig): WotchiClient;

package/dist/types/core/config.d.ts

@@ -0,0 +1,29 @@
+import type { WotchiConfig, WotchiNotifier } from "./types.js";
+import { WotchiConfigurationError } from "./errors.js";
+export { WotchiConfigurationError };
+export interface NormalizedWotchiConfig {
+    readonly service: string;
+    readonly environment: string;
+    readonly release?: string;
+    readonly enabled: boolean;
+    readonly grouping: {
+        readonly windowMs: number;
+        readonly alertThreshold: number;
+        readonly cooldownMs: number;
+        readonly maxGroups: number;
+        readonly maxEventsPerWindow: number;
+    };
+    readonly queue: {
+        readonly maxPendingAlerts: number;
+        readonly concurrency: 1;
+    };
+    readonly privacy: {
+        readonly redactKeys: readonly string[];
+        readonly maxDepth: number;
+        readonly maxKeys: number;
+        readonly maxStringLength: number;
+        readonly maxStackLength: number;
+    };
+    readonly notifiers: readonly WotchiNotifier[];
+}
+export declare function validateConfig(config: WotchiConfig): Readonly<NormalizedWotchiConfig>;

package/dist/types/core/diagnostics.d.ts

@@ -0,0 +1,7 @@
+import type { WotchiDiagnostics } from "./types.js";
+export interface DiagnosticsState {
+    capturedEvents: number;
+    captureFailures: number;
+}
+export declare function createDiagnosticsState(): DiagnosticsState;
+export declare function snapshotDiagnostics(state: DiagnosticsState, values: Omit<WotchiDiagnostics, "capturedEvents" | "captureFailures">): Readonly<WotchiDiagnostics>;

package/dist/types/core/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class WotchiConfigurationError extends Error {
+    constructor(message: string);
+}

package/dist/types/core/fingerprint.d.ts

@@ -0,0 +1,3 @@
+import type { SafeErrorEvent } from "./types.js";
+export declare function normalizeDynamicSegments(value: string): string;
+export declare function fingerprintSafeErrorEvent(event: SafeErrorEvent): string;

package/dist/types/core/group-store.d.ts

@@ -0,0 +1,15 @@
+import type { IncidentGroup, IncidentSeverity, SafeErrorEvent } from "./types.js";
+export interface GroupStoreOptions {
+    maxGroups: number;
+    maxEventsPerWindow: number;
+    windowMs: number;
+    now?: () => number;
+}
+export interface GroupStore {
+    record(fingerprint: string, event: SafeErrorEvent, severity?: IncidentSeverity): IncidentGroup;
+    get(fingerprint: string): IncidentGroup | undefined;
+    markAlerted(fingerprint: string, timestamp?: number): IncidentGroup | undefined;
+    size(): number;
+    groupsEvicted(): number;
+}
+export declare function createGroupStore(options: GroupStoreOptions): GroupStore;

package/dist/types/core/incident-builder.d.ts

@@ -0,0 +1,3 @@
+import type { IncidentAlert, IncidentGroup } from "./types.js";
+import type { IncidentPolicyDecision } from "./incident-policy.js";
+export declare function buildIncidentAlert(group: IncidentGroup, decision: IncidentPolicyDecision): IncidentAlert;

package/dist/types/core/incident-policy.d.ts

@@ -0,0 +1,15 @@
+import type { IncidentGroup, IncidentSeverity } from "./types.js";
+export type IncidentEventKind = "error" | "manual" | "process-monitor";
+export interface IncidentPolicyInput {
+    group: IncidentGroup;
+    now: number;
+    alertThreshold: number;
+    cooldownMs: number;
+    eventKind?: IncidentEventKind;
+    manualSeverity?: IncidentSeverity;
+}
+export interface IncidentPolicyDecision {
+    shouldAlert: boolean;
+    severity: IncidentSeverity;
+}
+export declare function evaluateIncidentPolicy(input: IncidentPolicyInput): IncidentPolicyDecision;

package/dist/types/core/normalize.d.ts

@@ -0,0 +1,17 @@
+export interface NormalizationLimits {
+    maxDepth: number;
+    maxKeys: number;
+    maxStringLength: number;
+    maxStackLength: number;
+}
+export type SafeNormalizedValue = null | boolean | number | string | SafeNormalizedValue[] | {
+    [key: string]: SafeNormalizedValue;
+};
+export interface NormalizedError {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string;
+}
+export declare function normalizeUnknown(value: unknown, limits?: Partial<NormalizationLimits>): SafeNormalizedValue;
+export declare function normalizeError(error: unknown, limits?: Partial<NormalizationLimits>): NormalizedError;

package/dist/types/core/notification-queue.d.ts

@@ -0,0 +1,16 @@
+import type { IncidentAlert, WotchiNotifier } from "./types.js";
+export interface NotificationQueueOptions {
+    maxPendingAlerts: number;
+    concurrency: 1;
+    onNotifierError?: (error: unknown, notifier: WotchiNotifier) => void;
+}
+export interface NotificationQueue {
+    enqueue(alert: IncidentAlert, notifiers: readonly WotchiNotifier[]): boolean;
+    flush(timeoutMs?: number): Promise<void>;
+    pending(): number;
+    alertsQueued(): number;
+    alertsDropped(): number;
+    alertsSent(): number;
+    notifierFailures(): number;
+}
+export declare function createNotificationQueue(options: NotificationQueueOptions): NotificationQueue;

package/dist/types/core/process-monitor.d.ts

@@ -0,0 +1,5 @@
+import type { WotchiClient } from "./types.js";
+export interface ProcessMonitorHandle {
+    unregister(): void;
+}
+export declare function registerWotchiProcessMonitor(client: WotchiClient): ProcessMonitorHandle;

package/dist/types/core/redact.d.ts

@@ -0,0 +1,11 @@
+import type { NormalizedError, SafeNormalizedValue } from "./normalize.js";
+export declare const REDACTED = "[REDACTED]";
+export interface RedactionOptions {
+    redactKeys?: readonly string[];
+    maxDepth?: number;
+    maxKeys?: number;
+    maxStringLength?: number;
+    maxStackLength?: number;
+}
+export declare function redactValue(value: unknown, options?: RedactionOptions): SafeNormalizedValue;
+export declare function redactError(error: NormalizedError, options?: RedactionOptions): NormalizedError;

package/dist/types/core/rolling-window.d.ts

@@ -0,0 +1,12 @@
+export interface RollingWindowOptions {
+    maxEvents: number;
+    windowMs: number;
+    now?: () => number;
+}
+export interface RollingWindow {
+    add(timestamp?: number): void;
+    count(timestamp?: number): number;
+    size(timestamp?: number): number;
+    timestamps(timestamp?: number): readonly number[];
+}
+export declare function createRollingWindow(options: RollingWindowOptions): RollingWindow;

package/dist/types/core/stack-frame.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeStackFrame(frame: string): string;
+export declare function selectApplicationFrame(stack?: string): string | undefined;

package/dist/types/core/types.d.ts

@@ -0,0 +1,109 @@
+export type IncidentSeverity = "low" | "medium" | "high" | "critical";
+export type WotchiEventKind = "error" | "manual" | "process-monitor";
+export interface WotchiRequestContext extends Record<string, unknown> {
+    method?: string;
+    route?: string;
+    statusCode?: number;
+    requestId?: string;
+}
+export interface WotchiEventInput {
+    level: "error";
+    kind?: WotchiEventKind;
+    message: string;
+    error?: unknown;
+    metadata?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+    request?: WotchiRequestContext;
+}
+export interface SafeErrorEvent {
+    id: string;
+    timestamp: string;
+    service: string;
+    environment: string;
+    release?: string;
+    error: {
+        name: string;
+        message: string;
+        stack?: string;
+        code?: string;
+    };
+    request?: WotchiRequestContext;
+    context?: Record<string, unknown>;
+}
+export interface IncidentGroup {
+    fingerprint: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    totalCount: number;
+    windowCount: number;
+    sample: SafeErrorEvent;
+    lastAlertedAt?: string;
+    severity: IncidentSeverity;
+}
+export interface IncidentAlert {
+    id: string;
+    fingerprint: string;
+    title: string;
+    severity: IncidentSeverity;
+    summary: string;
+    suggestedActions: string[];
+    firstSeenAt: string;
+    lastSeenAt: string;
+    occurrences: number;
+    service: string;
+    environment: string;
+}
+export interface WotchiNotifier {
+    readonly name: string;
+    send(alert: IncidentAlert): Promise<void>;
+}
+export interface ConsoleNotifierOptions {
+    write?: (line: string) => void;
+}
+export interface TelegramNotifierOptions {
+    botToken: string;
+    chatId: string;
+    timeoutMs?: number;
+}
+export interface WotchiConfig {
+    service: string;
+    environment: string;
+    release?: string;
+    enabled?: boolean;
+    grouping?: {
+        windowMs?: number;
+        alertThreshold?: number;
+        cooldownMs?: number;
+        maxGroups?: number;
+        maxEventsPerWindow?: number;
+    };
+    queue?: {
+        maxPendingAlerts?: number;
+        concurrency?: 1;
+    };
+    privacy?: {
+        redactKeys?: string[];
+        maxDepth?: number;
+        maxKeys?: number;
+        maxStringLength?: number;
+        maxStackLength?: number;
+    };
+    notifiers: WotchiNotifier[];
+}
+export interface WotchiDiagnostics {
+    capturedEvents: number;
+    captureFailures: number;
+    groupsEvicted: number;
+    alertsQueued: number;
+    alertsDropped: number;
+    alertsSent: number;
+    notifierFailures: number;
+    activeGroups: number;
+    pendingAlerts: number;
+}
+export interface WotchiClient {
+    captureException(error: unknown, context?: Record<string, unknown>): void;
+    captureEvent(event: WotchiEventInput): void;
+    flush(timeoutMs?: number): Promise<void>;
+    getDiagnostics(): Readonly<WotchiDiagnostics>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,9 @@
+import { createWotchi } from "./core/client.js";
+import { registerWotchiProcessMonitor } from "./core/process-monitor.js";
+import { consoleNotifier } from "./notifiers/console.js";
+import { telegramNotifier } from "./notifiers/telegram.js";
+export { WotchiConfigurationError } from "./core/errors.js";
+export type { ProcessMonitorHandle } from "./core/process-monitor.js";
+export type { NormalizedWotchiConfig } from "./core/config.js";
+export type { ConsoleNotifierOptions, IncidentAlert, IncidentGroup, IncidentSeverity, SafeErrorEvent, TelegramNotifierOptions, WotchiClient, WotchiConfig, WotchiDiagnostics, WotchiEventInput, WotchiEventKind, WotchiNotifier, WotchiRequestContext, } from "./core/types.js";
+export { consoleNotifier, createWotchi, registerWotchiProcessMonitor, telegramNotifier };

package/dist/types/integrations/express/error-handler.d.ts

@@ -0,0 +1,4 @@
+import type { ErrorRequestHandler } from "express";
+import type { WotchiClient } from "../../core/types.js";
+import { type ExpressWotchiOptions } from "./request-context.js";
+export declare function createExpressErrorHandler(client: WotchiClient, options?: ExpressWotchiOptions): ErrorRequestHandler;

package/dist/types/integrations/express/index.d.ts

@@ -0,0 +1,7 @@
+import type { WotchiClient } from "../../core/types.js";
+import { createExpressErrorHandler } from "./error-handler.js";
+import type { ExpressWotchiOptions } from "./request-context.js";
+export { consoleNotifier, createWotchi, telegramNotifier } from "../../index.js";
+export type { ConsoleNotifierOptions, IncidentAlert, IncidentGroup, IncidentSeverity, SafeErrorEvent, TelegramNotifierOptions, WotchiClient, WotchiConfig, WotchiDiagnostics, WotchiEventInput, WotchiNotifier, WotchiRequestContext, } from "../../index.js";
+export type { ExpressWotchiOptions } from "./request-context.js";
+export declare function wotchiErrorHandler(client: WotchiClient, options?: ExpressWotchiOptions): ReturnType<typeof createExpressErrorHandler>;

package/dist/types/integrations/express/request-context.d.ts

@@ -0,0 +1,5 @@
+import type { Request, Response } from "express";
+import { type RequestContextOptions } from "../request-context.js";
+import type { WotchiRequestContext } from "../../core/types.js";
+export type ExpressWotchiOptions = RequestContextOptions;
+export declare function getExpressRequestContext(request: Request, response: Response, options?: ExpressWotchiOptions): WotchiRequestContext | undefined;

package/dist/types/integrations/nest/exception-filter.d.ts

@@ -0,0 +1,10 @@
+import { type ArgumentsHost, type HttpServer } from "@nestjs/common";
+import { BaseExceptionFilter } from "@nestjs/core";
+import type { WotchiClient } from "../../core/types.js";
+import { type NestWotchiOptions } from "./request-context.js";
+export declare class WotchiNestExceptionFilter extends BaseExceptionFilter<unknown> {
+    private readonly client;
+    private readonly options?;
+    constructor(client: WotchiClient, applicationRef: HttpServer, options?: NestWotchiOptions | undefined);
+    catch(exception: unknown, host: ArgumentsHost): void;
+}

package/dist/types/integrations/nest/index.d.ts

@@ -0,0 +1,4 @@
+export { consoleNotifier, createWotchi, telegramNotifier } from "../../index.js";
+export { registerWotchiNest } from "./register.js";
+export type { ConsoleNotifierOptions, IncidentAlert, IncidentGroup, IncidentSeverity, SafeErrorEvent, TelegramNotifierOptions, WotchiClient, WotchiConfig, WotchiDiagnostics, WotchiEventInput, WotchiNotifier, WotchiRequestContext, } from "../../index.js";
+export type { NestWotchiApplication, NestWotchiOptions } from "./register.js";

package/dist/types/integrations/nest/register.d.ts

@@ -0,0 +1,10 @@
+import { HttpAdapterHost } from "@nestjs/core";
+import type { WotchiClient } from "../../core/types.js";
+import type { NestWotchiOptions } from "./request-context.js";
+export type { NestWotchiOptions } from "./request-context.js";
+export interface NestWotchiApplication {
+    get(token: typeof HttpAdapterHost): InstanceType<typeof HttpAdapterHost>;
+    getHttpAdapter?: () => unknown;
+    useGlobalFilters(...filters: unknown[]): unknown;
+}
+export declare function registerWotchiNest(app: unknown, client: WotchiClient, options?: NestWotchiOptions): void;

package/dist/types/integrations/nest/request-context.d.ts

@@ -0,0 +1,5 @@
+import type { ArgumentsHost } from "@nestjs/common";
+import { type RequestContextOptions } from "../request-context.js";
+import type { WotchiRequestContext } from "../../core/types.js";
+export type NestWotchiOptions = RequestContextOptions;
+export declare function getNestRequestContext(host: ArgumentsHost, exception: unknown, options?: NestWotchiOptions): WotchiRequestContext | undefined;

package/dist/types/integrations/request-context.d.ts

@@ -0,0 +1,13 @@
+import type { WotchiRequestContext } from "../core/types.js";
+export interface RequestContextOptions {
+    requestIdProperty?: string;
+}
+export declare function normalizeRoutePath(value: unknown): string | undefined;
+export interface RequestContextInput {
+    request?: unknown;
+    method?: unknown;
+    route?: unknown;
+    statusCode?: unknown;
+    options?: RequestContextOptions;
+}
+export declare function buildRequestContext(input: RequestContextInput): WotchiRequestContext | undefined;

package/dist/types/notifiers/console.d.ts

@@ -0,0 +1,3 @@
+import type { ConsoleNotifierOptions, IncidentAlert, WotchiNotifier } from "../core/types.js";
+export declare function formatConsoleAlert(alert: IncidentAlert): string;
+export declare function consoleNotifier(options?: ConsoleNotifierOptions): WotchiNotifier;

package/dist/types/notifiers/telegram-format.d.ts

@@ -0,0 +1,2 @@
+import type { IncidentAlert } from "../core/types.js";
+export declare function formatTelegramAlert(alert: IncidentAlert): string;

package/dist/types/notifiers/telegram-http.d.ts

@@ -0,0 +1,21 @@
+import type { RequestOptions } from "node:https";
+export interface TelegramHttpRequestOptions extends RequestOptions {
+    protocol: "https:";
+    hostname: "api.telegram.org";
+    method: "POST";
+    path: string;
+    headers: Record<string, string | number>;
+}
+export interface TelegramHttpResponse {
+    statusCode: number;
+    headers: Record<string, string | string[] | undefined>;
+    body: string;
+}
+export type TelegramRequestFunction = (options: TelegramHttpRequestOptions, body: string, timeoutMs: number) => Promise<TelegramHttpResponse>;
+export interface TelegramSendOptions {
+    botToken: string;
+    chatId: string;
+    text: string;
+    timeoutMs?: number;
+}
+export declare function sendTelegramMessage(options: TelegramSendOptions, request?: TelegramRequestFunction): Promise<void>;

package/dist/types/notifiers/telegram.d.ts

@@ -0,0 +1,4 @@
+import type { TelegramNotifierOptions, WotchiNotifier } from "../core/types.js";
+import { type TelegramRequestFunction } from "./telegram-http.js";
+export declare function createTelegramNotifier(options: TelegramNotifierOptions, request?: TelegramRequestFunction): WotchiNotifier;
+export declare function telegramNotifier(options: TelegramNotifierOptions): WotchiNotifier;