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

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 type WotchiEventKind = "error" | "manual" | "process-monitor" | "runtime-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;
@@ -82,6 +160,16 @@ export interface WotchiConfig {
     queue?: {
         maxPendingAlerts?: number;
         concurrency?: 1;
+        notifierTimeoutMs?: number;
+        notifierCircuitBreaker?: {
+            failureThreshold?: number;
+            cooldownMs?: number;
+        };
+    };
+    overload?: {
+        maxEventsPerSecond?: number;
+        burst?: number;
+        alertCooldownMs?: number;
     };
     privacy?: {
         redactKeys?: string[];
@@ -100,12 +188,33 @@ export interface WotchiDiagnostics {
     alertsDropped: number;
     alertsSent: number;
     notifierFailures: number;
+    fingerprintCallbackFailures: number;
+    filterFailures: number;
+    beforeSendFailures: number;
+    eventsSuppressed: number;
+    eventsDroppedOverload: number;
+    capturesAfterShutdown: number;
     activeGroups: number;
     pendingAlerts: number;
+    notifierTimeouts: number;
+    notifierCircuitOpenSkips: 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>;
+    shutdown(timeoutMs?: number): Promise<void>;
     getDiagnostics(): Readonly<WotchiDiagnostics>;
 }

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

@@ -1,9 +1,15 @@
 import { createWotchi } from "./core/client.js";
 import { registerWotchiProcessMonitor } from "./core/process-monitor.js";
+import { createWotchiPrometheusExporter, PROMETHEUS_CONTENT_TYPE } from "./core/prometheus.js";
+import { registerWotchiRuntimeWatcher } from "./core/runtime-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 { WotchiPrometheusExporter } from "./core/prometheus.js";
+export type { WotchiRuntimeWatcherHandle, WotchiRuntimeWatcherOptions, } from "./core/runtime-monitor.js";
+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, createWotchiPrometheusExporter, PROMETHEUS_CONTENT_TYPE, registerWotchiProcessMonitor, registerWotchiRuntimeWatcher, 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/capture.d.cts

@@ -0,0 +1,4 @@
+import type { ArgumentsHost } from "@nestjs/common";
+import type { WotchiClient } from "../../core/types.js";
+import { type NestWotchiOptions } from "./request-context.js";
+export declare const captureWotchiNestException: (client: WotchiClient, exception: unknown, host: ArgumentsHost, options?: NestWotchiOptions) => void;

package/dist/types-cjs/integrations/nest/exception-filter.d.cts

@@ -1,10 +1,14 @@
 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";
+import type { NestExceptionFilterLike } from "./filter-wrapper.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);
+    private readonly previousGlobalFilters;
+    constructor(client: WotchiClient, applicationRef?: HttpServer, options?: NestWotchiOptions | undefined, previousGlobalFilters?: readonly NestExceptionFilterLike[]);
     catch(exception: unknown, host: ArgumentsHost): void;
+    private respondWithoutLoggingRawUnknownException;
+    private respondThroughExpressAdapter;
 }

package/dist/types-cjs/integrations/nest/filter-wrapper.d.cts

@@ -0,0 +1,7 @@
+import type { ArgumentsHost } from "@nestjs/common";
+import type { WotchiClient } from "../../core/types.js";
+import type { NestWotchiOptions } from "./request-context.js";
+export interface NestExceptionFilterLike {
+    catch(exception: unknown, host: ArgumentsHost): void;
+}
+export declare function withWotchiNestFilter<TFilter extends NestExceptionFilterLike>(client: WotchiClient, filter: TFilter, options?: NestWotchiOptions): TFilter;

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

@@ -1,5 +1,9 @@
-export { consoleNotifier, createWotchi, telegramNotifier } from "../../index.js";
+export { consoleNotifier, createWotchi, telegramNotifier, webhookNotifier } from "../../index.js";
+export { withWotchiNestFilter } from "./filter-wrapper.js";
+export { WotchiModule, WOTCHI_CLIENT } from "./module.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 { NestExceptionFilterLike } from "./filter-wrapper.js";
+export type { WotchiNestModuleOptions } from "./module.js";
 export type { WotchiStatusClass, WotchiStatusObserverOptions } from "../express/status-observer.js";

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

@@ -0,0 +1,9 @@
+import { type DynamicModule } from "@nestjs/common";
+import type { WotchiConfig } from "../../core/types.js";
+export declare const WOTCHI_CLIENT: unique symbol;
+export interface WotchiNestModuleOptions {
+    registerGlobalFilter?: boolean;
+}
+export declare class WotchiModule {
+    static forRoot(config: WotchiConfig, options?: WotchiNestModuleOptions): DynamicModule;
+}

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

@@ -8,6 +8,9 @@ export interface NestWotchiApplication {
     getHttpAdapter?: () => unknown;
     use?: (...middleware: unknown[]) => unknown;
     useGlobalFilters(...filters: unknown[]): unknown;
+    config?: {
+        getGlobalFilters?: () => unknown[];
+    };
 }
 export declare function registerWotchiNest(app: unknown, client: WotchiClient, options?: NestWotchiOptions): void;
 export declare function registerWotchiNestStatusObserver(app: unknown, client: WotchiClient, options?: WotchiStatusObserverOptions): void;

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.6",
+  "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",
@@ -32,6 +33,16 @@
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "express": [
+        "dist/types/integrations/express/index.d.ts"
+      ],
+      "nest": [
+        "dist/types/integrations/nest/index.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "types": {
@@ -62,7 +73,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 +84,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 .",
@@ -81,6 +93,7 @@
     "test": "npm run test:compile && node --test .test-dist/test/unit/*.test.js .test-dist/test/integration/express/*.test.js .test-dist/test/integration/nest/*.test.js .test-dist/test/security/*.test.js",
     "pack:dry-run": "npm run build && npm pack --dry-run --json",
     "verify:package": "npm run build && node scripts/verify-package.mjs",
+    "verify:published-metadata": "node scripts/verify-published-metadata.mjs",
     "test:compat": "npm run build && node test/compatibility/package-exports.smoke.cjs && node test/compatibility/framework-isolation.cjs",
     "test:compat:matrix": "npm run build && node scripts/run-compatibility-matrix.mjs",
     "benchmark": "npm run build && node --expose-gc scripts/run-benchmarks.mjs",