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

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

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

package/dist/types/notifiers/alert-payload.d.ts

@@ -0,0 +1,5 @@
+import type { SafeNormalizedValue } from "../core/normalize.js";
+import type { IncidentAlert } from "../core/types.js";
+export type BoundedAlertPayload = Record<string, SafeNormalizedValue>;
+export declare function toBoundedPayload(value: unknown): BoundedAlertPayload;
+export declare function toBoundedAlertPayload(alert: IncidentAlert): BoundedAlertPayload;

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

@@ -0,0 +1,37 @@
+import type { IncidentAlert, WebhookNotifierOptions } from "../core/types.js";
+export interface WebhookRequestOptions {
+    protocol: "http:" | "https:";
+    hostname: string;
+    port?: string;
+    method: "POST";
+    path: string;
+    headers: Record<string, string | number>;
+    allowPrivateDestinations?: boolean;
+    signal?: AbortSignal;
+}
+export interface WebhookResponse {
+    statusCode: number;
+    headers: Record<string, string | string[] | undefined>;
+    body: string;
+}
+export type WebhookRequestFunction = (options: WebhookRequestOptions, body: string, timeoutMs: number) => Promise<WebhookResponse>;
+export interface WebhookSendOptions {
+    url: string;
+    alert: IncidentAlert;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    maxRetries?: number;
+    allowHttpLoopback?: boolean;
+    allowPrivateDestinations?: boolean;
+    payloadBuilder?: (alert: Readonly<IncidentAlert>) => unknown;
+}
+export declare function normalizeWebhookOptions(options: WebhookNotifierOptions): {
+    url: URL;
+    headers?: Record<string, string>;
+    timeoutMs: number;
+    maxRetries: number;
+    allowHttpLoopback: boolean;
+    allowPrivateDestinations: boolean;
+    payloadBuilder?: WebhookNotifierOptions["payloadBuilder"];
+};
+export declare function sendWebhookAlert(options: WebhookSendOptions, request?: WebhookRequestFunction): Promise<void>;

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

@@ -0,0 +1,4 @@
+import type { WebhookNotifierOptions, WotchiNotifier } from "../core/types.js";
+import { type WebhookRequestFunction } from "./webhook-http.js";
+export declare function createWebhookNotifier(options: WebhookNotifierOptions, request?: WebhookRequestFunction): WotchiNotifier;
+export declare function webhookNotifier(options: WebhookNotifierOptions): WotchiNotifier;

package/dist/types-cjs/core/config.d.cts

@@ -1,11 +1,17 @@
-import type { WotchiConfig, WotchiNotifier } from "./types.js";
+import type { WotchiConfig, WotchiIncidentRule, WotchiLinkTemplates, WotchiNotifier } from "./types.js";
 import { WotchiConfigurationError } from "./errors.js";
 export { WotchiConfigurationError };
 export interface NormalizedWotchiConfig {
     readonly service: string;
     readonly environment: string;
+    readonly instance?: string;
     readonly release?: string;
     readonly enabled: boolean;
+    readonly filter?: WotchiConfig["filter"];
+    readonly fingerprint?: WotchiConfig["fingerprint"];
+    readonly beforeSend?: WotchiConfig["beforeSend"];
+    readonly links?: Readonly<WotchiLinkTemplates>;
+    readonly rules: readonly WotchiIncidentRule[];
     readonly grouping: {
         readonly windowMs: number;
         readonly alertThreshold: number;

package/dist/types-cjs/core/diagnostics.d.cts

@@ -2,6 +2,10 @@ import type { WotchiDiagnostics } from "./types.js";
 export interface DiagnosticsState {
     capturedEvents: number;
     captureFailures: number;
+    fingerprintCallbackFailures: number;
+    filterFailures: number;
+    beforeSendFailures: number;
+    eventsSuppressed: number;
 }
 export declare function createDiagnosticsState(): DiagnosticsState;
-export declare function snapshotDiagnostics(state: DiagnosticsState, values: Omit<WotchiDiagnostics, "capturedEvents" | "captureFailures">): Readonly<WotchiDiagnostics>;
+export declare function snapshotDiagnostics(state: DiagnosticsState, values: Omit<WotchiDiagnostics, "capturedEvents" | "captureFailures" | "fingerprintCallbackFailures" | "filterFailures" | "beforeSendFailures" | "eventsSuppressed">): Readonly<WotchiDiagnostics>;

package/dist/types-cjs/core/limits.d.cts

@@ -0,0 +1,10 @@
+export declare const MAX_GROUPS = 10000;
+export declare const MAX_EVENTS_PER_WINDOW = 10000;
+export declare const MAX_PENDING_ALERTS = 10000;
+export declare const MAX_WINDOW_MS: number;
+export declare const MAX_ALERT_THRESHOLD = 1000000;
+export declare const MAX_COOLDOWN_MS: number;
+export declare const MAX_NORMALIZATION_DEPTH = 20;
+export declare const MAX_NORMALIZATION_KEYS = 10000;
+export declare const MAX_NORMALIZATION_STRING_LENGTH = 32768;
+export declare const MAX_NORMALIZATION_STACK_LENGTH = 32768;

package/dist/types-cjs/core/notification-queue.d.cts

@@ -4,8 +4,12 @@ export interface NotificationQueueOptions {
     concurrency: 1;
     onNotifierError?: (error: unknown, notifier: WotchiNotifier) => void;
 }
+export interface NotificationJobResult {
+    notifierFailures: number;
+    sent: number;
+}
 export interface NotificationQueue {
-    enqueue(alert: IncidentAlert, notifiers: readonly WotchiNotifier[]): boolean;
+    enqueue(alert: IncidentAlert, notifiers: readonly WotchiNotifier[], onComplete?: (result: NotificationJobResult) => void): boolean;
     flush(timeoutMs?: number): Promise<void>;
     pending(): number;
     alertsQueued(): number;

package/dist/types-cjs/core/types.d.cts

@@ -1,10 +1,40 @@
 export type IncidentSeverity = "low" | "medium" | "high" | "critical";
 export type WotchiEventKind = "error" | "manual" | "process-monitor";
+export interface WotchiTraceContext {
+    traceId?: string;
+    spanId?: string;
+}
 export interface WotchiRequestContext extends Record<string, unknown> {
     method?: string;
     route?: string;
     statusCode?: number;
     requestId?: string;
+    correlationId?: string;
+    trace?: WotchiTraceContext;
+}
+export type WotchiTags = Readonly<Record<string, string>>;
+export interface WotchiLinkTemplates {
+    log?: string;
+    trace?: string;
+}
+export interface WotchiLinks {
+    log?: string;
+    trace?: string;
+}
+export type WotchiFingerprintCallback = (event: Readonly<SafeErrorEvent>) => string | undefined;
+export type WotchiFingerprintOverride = string | WotchiFingerprintCallback;
+export type WotchiEventFilter = (event: Readonly<SafeErrorEvent>) => boolean;
+export type WotchiBeforeSend = (alert: Readonly<IncidentAlert>) => IncidentAlert | null | undefined;
+export interface WotchiCaptureOptions {
+    fingerprint?: WotchiFingerprintOverride;
+    severity?: IncidentSeverity;
+    alertThreshold?: number;
+    request?: WotchiRequestContext;
+    trace?: WotchiTraceContext;
+    correlationId?: string;
+    operation?: string;
+    job?: string;
+    tags?: Record<string, unknown>;
 }
 export interface WotchiEventInput {
     level: "error";
@@ -12,16 +42,28 @@ export interface WotchiEventInput {
     message: string;
     error?: unknown;
     alertThreshold?: number;
+    severity?: IncidentSeverity;
+    fingerprint?: WotchiFingerprintOverride;
     metadata?: Record<string, unknown>;
     context?: Record<string, unknown>;
     request?: WotchiRequestContext;
+    trace?: WotchiTraceContext;
+    correlationId?: string;
+    operation?: string;
+    job?: string;
+    tags?: Record<string, unknown>;
 }
 export interface SafeErrorEvent {
     id: string;
     timestamp: string;
     service: string;
     environment: string;
+    instance?: string;
     release?: string;
+    correlationId?: string;
+    operation?: string;
+    job?: string;
+    tags?: WotchiTags;
     error: {
         name: string;
         message: string;
@@ -29,6 +71,7 @@ export interface SafeErrorEvent {
         code?: string;
     };
     request?: WotchiRequestContext;
+    trace?: WotchiTraceContext;
     context?: Record<string, unknown>;
 }
 export interface IncidentGroup {
@@ -53,6 +96,19 @@ export interface IncidentAlert {
     occurrences: number;
     service: string;
     environment: string;
+    instance?: string;
+    release?: string;
+    correlationId?: string;
+    operation?: string;
+    job?: string;
+    tags?: WotchiTags;
+    error?: SafeErrorEvent["error"] & {
+        applicationFrame?: string;
+    };
+    request?: WotchiRequestContext;
+    trace?: WotchiTraceContext;
+    context?: Record<string, unknown>;
+    links?: WotchiLinks;
 }
 export interface WotchiNotifier {
     readonly name: string;
@@ -67,11 +123,33 @@ export interface TelegramNotifierOptions {
     chatId: string;
     timeoutMs?: number;
 }
+export interface WebhookNotifierOptions {
+    url: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    maxRetries?: number;
+    allowHttpLoopback?: boolean;
+    allowPrivateDestinations?: boolean;
+    payloadBuilder?: (alert: Readonly<IncidentAlert>) => unknown;
+}
+export interface WotchiIncidentRule {
+    environment?: string;
+    route?: string;
+    ignore?: boolean;
+    alertThreshold?: number;
+    severity?: IncidentSeverity;
+}
 export interface WotchiConfig {
     service: string;
     environment: string;
+    instance?: string;
     release?: string;
     enabled?: boolean;
+    filter?: WotchiEventFilter;
+    fingerprint?: WotchiFingerprintCallback;
+    beforeSend?: WotchiBeforeSend;
+    links?: WotchiLinkTemplates;
+    rules?: readonly WotchiIncidentRule[];
     grouping?: {
         windowMs?: number;
         alertThreshold?: number;
@@ -100,12 +178,28 @@ export interface WotchiDiagnostics {
     alertsDropped: number;
     alertsSent: number;
     notifierFailures: number;
+    fingerprintCallbackFailures: number;
+    filterFailures: number;
+    beforeSendFailures: number;
+    eventsSuppressed: number;
     activeGroups: number;
     pendingAlerts: number;
 }
+export type WotchiTestAlertStatus = "sent" | "queue-full" | "timeout" | "notifier-failed";
+export interface WotchiTestAlertResult {
+    status: WotchiTestAlertStatus;
+    configurationAccepted: true;
+    queued: boolean;
+    flushed: boolean;
+    delivered: boolean;
+    notifierFailures: number;
+    diagnostics: Readonly<WotchiDiagnostics>;
+    error?: string;
+}
 export interface WotchiClient {
-    captureException(error: unknown, context?: Record<string, unknown>): void;
+    captureException(error: unknown, context?: Record<string, unknown>, options?: WotchiCaptureOptions): void;
     captureEvent(event: WotchiEventInput): void;
+    testAlert(): Promise<WotchiTestAlertResult>;
     flush(timeoutMs?: number): Promise<void>;
     getDiagnostics(): Readonly<WotchiDiagnostics>;
 }

package/dist/types-cjs/index.d.cts

@@ -2,8 +2,10 @@ 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";
+import { webhookNotifier } from "./notifiers/webhook.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 };
+export type { ConsoleNotifierOptions, IncidentAlert, IncidentGroup, IncidentSeverity, SafeErrorEvent, TelegramNotifierOptions, WebhookNotifierOptions, WotchiBeforeSend, WotchiCaptureOptions, WotchiClient, WotchiConfig, WotchiDiagnostics, WotchiEventFilter, WotchiEventInput, WotchiEventKind, WotchiFingerprintOverride, WotchiFingerprintCallback, WotchiIncidentRule, WotchiLinkTemplates, WotchiLinks, WotchiNotifier, WotchiRequestContext, WotchiTags, WotchiTestAlertResult, WotchiTestAlertStatus, WotchiTraceContext, } from "./core/types.js";
+export type { WebhookRequestFunction, WebhookRequestOptions, WebhookResponse, } from "./notifiers/webhook-http.js";
+export { consoleNotifier, createWotchi, registerWotchiProcessMonitor, telegramNotifier, webhookNotifier, };

package/dist/types-cjs/integrations/express/index.d.cts

@@ -1,8 +1,8 @@
 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 { consoleNotifier, createWotchi, telegramNotifier, webhookNotifier } from "../../index.js";
+export type { ConsoleNotifierOptions, IncidentAlert, IncidentGroup, IncidentSeverity, SafeErrorEvent, TelegramNotifierOptions, WebhookNotifierOptions, WotchiBeforeSend, WotchiCaptureOptions, WotchiClient, WotchiConfig, WotchiDiagnostics, WotchiEventFilter, WotchiEventInput, WotchiFingerprintCallback, WotchiFingerprintOverride, WotchiIncidentRule, WotchiLinkTemplates, WotchiLinks, WotchiNotifier, WotchiRequestContext, WotchiTags, WotchiTestAlertResult, WotchiTestAlertStatus, WotchiTraceContext, } from "../../index.js";
 export type { ExpressWotchiOptions } from "./request-context.js";
 export type { WotchiStatusClass, WotchiStatusObserverOptions } from "./status-observer.js";
 export { wotchiStatusObserver } from "./status-observer.js";

package/dist/types-cjs/integrations/nest/index.d.cts

@@ -1,5 +1,5 @@
-export { consoleNotifier, createWotchi, telegramNotifier } from "../../index.js";
+export { consoleNotifier, createWotchi, telegramNotifier, webhookNotifier } from "../../index.js";
 export { registerWotchiNest, registerWotchiNestStatusObserver } from "./register.js";
-export type { ConsoleNotifierOptions, IncidentAlert, IncidentGroup, IncidentSeverity, SafeErrorEvent, TelegramNotifierOptions, WotchiClient, WotchiConfig, WotchiDiagnostics, WotchiEventInput, WotchiNotifier, WotchiRequestContext, } from "../../index.js";
+export type { ConsoleNotifierOptions, IncidentAlert, IncidentGroup, IncidentSeverity, SafeErrorEvent, TelegramNotifierOptions, WebhookNotifierOptions, WotchiBeforeSend, WotchiCaptureOptions, WotchiClient, WotchiConfig, WotchiDiagnostics, WotchiEventFilter, WotchiEventInput, WotchiFingerprintCallback, WotchiFingerprintOverride, WotchiIncidentRule, WotchiLinkTemplates, WotchiLinks, WotchiNotifier, WotchiRequestContext, WotchiTags, WotchiTestAlertResult, WotchiTestAlertStatus, WotchiTraceContext, } from "../../index.js";
 export type { NestWotchiApplication, NestWotchiOptions } from "./register.js";
 export type { WotchiStatusClass, WotchiStatusObserverOptions } from "../express/status-observer.js";

package/dist/types-cjs/integrations/request-context.d.cts

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

package/dist/types-cjs/notifiers/alert-payload.d.cts

@@ -0,0 +1,5 @@
+import type { SafeNormalizedValue } from "../core/normalize.js";
+import type { IncidentAlert } from "../core/types.js";
+export type BoundedAlertPayload = Record<string, SafeNormalizedValue>;
+export declare function toBoundedPayload(value: unknown): BoundedAlertPayload;
+export declare function toBoundedAlertPayload(alert: IncidentAlert): BoundedAlertPayload;

package/dist/types-cjs/notifiers/webhook-http.d.cts

@@ -0,0 +1,37 @@
+import type { IncidentAlert, WebhookNotifierOptions } from "../core/types.js";
+export interface WebhookRequestOptions {
+    protocol: "http:" | "https:";
+    hostname: string;
+    port?: string;
+    method: "POST";
+    path: string;
+    headers: Record<string, string | number>;
+    allowPrivateDestinations?: boolean;
+    signal?: AbortSignal;
+}
+export interface WebhookResponse {
+    statusCode: number;
+    headers: Record<string, string | string[] | undefined>;
+    body: string;
+}
+export type WebhookRequestFunction = (options: WebhookRequestOptions, body: string, timeoutMs: number) => Promise<WebhookResponse>;
+export interface WebhookSendOptions {
+    url: string;
+    alert: IncidentAlert;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    maxRetries?: number;
+    allowHttpLoopback?: boolean;
+    allowPrivateDestinations?: boolean;
+    payloadBuilder?: (alert: Readonly<IncidentAlert>) => unknown;
+}
+export declare function normalizeWebhookOptions(options: WebhookNotifierOptions): {
+    url: URL;
+    headers?: Record<string, string>;
+    timeoutMs: number;
+    maxRetries: number;
+    allowHttpLoopback: boolean;
+    allowPrivateDestinations: boolean;
+    payloadBuilder?: WebhookNotifierOptions["payloadBuilder"];
+};
+export declare function sendWebhookAlert(options: WebhookSendOptions, request?: WebhookRequestFunction): Promise<void>;

package/dist/types-cjs/notifiers/webhook.d.cts

@@ -0,0 +1,4 @@
+import type { WebhookNotifierOptions, WotchiNotifier } from "../core/types.js";
+import { type WebhookRequestFunction } from "./webhook-http.js";
+export declare function createWebhookNotifier(options: WebhookNotifierOptions, request?: WebhookRequestFunction): WotchiNotifier;
+export declare function webhookNotifier(options: WebhookNotifierOptions): WotchiNotifier;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@futurewindai/wotchi",
-  "version": "0.1.0-beta.2",
-  "description": "Bounded incident alerts for Node.js, Express, and NestJS applications",
+  "version": "0.1.0-beta.5",
+  "description": "Low-noise error alerts for Node.js, Express, and NestJS applications",
   "keywords": [
     "nodejs",
     "typescript",
@@ -11,7 +11,8 @@
     "incident-management",
     "alerting",
     "observability",
-    "telegram"
+    "telegram",
+    "webhook"
   ],
   "license": "Apache-2.0",
   "type": "module",
@@ -62,7 +63,7 @@
     "type": "git",
     "url": "git+ssh://git@github.com/FutureWindAI/Wotchi.git"
   },
-  "homepage": "https://www.npmjs.com/package/@futurewindai/wotchi",
+  "homepage": "https://github.com/FutureWindAI/Wotchi",
   "bugs": {
     "url": "https://github.com/FutureWindAI/Wotchi/issues"
   },
@@ -73,6 +74,7 @@
     "build:types": "tsc -p tsconfig.types.json",
     "build": "npm run clean && npm run build:esm && npm run build:cjs && npm run build:types && node scripts/prepare-package.mjs",
     "stand": "node scripts/start-test-stand.mjs",
+    "stand:production": "node scripts/start-nest-production-stand.mjs",
     "typecheck": "tsc -p tsconfig.base.json --noEmit",
     "lint": "eslint .",
     "format": "prettier --write .",