@obsunified/collector 2.3.0 → 2.4.3

package/dist/{ingest-auth-BmP5-f96.d.ts → ingest-auth-BTowieER.d.ts}

@@ -1,4 +1,62 @@
 import { Hono, Context, MiddlewareHandler } from 'hono';
+import { AlertState } from '@obsunified/types';
+
+/**
+ * Email alert channel: the runtime-neutral half.
+ *
+ * The collector package runs on Cloudflare Workers as well as Node, and a
+ * Worker cannot open an SMTP connection. So the package only defines what an
+ * email transport must do (`AlertEmailTransport`) and how an alert reads as
+ * mail (`formatAlertEmail`); a host that can speak SMTP binds a transport as
+ * `env.ALERT_EMAIL` (the Node collector does, from `ALERT_SMTP_*`, see
+ * apps/collector-node/src/alert-email.ts). Without that binding, rules with
+ * an email channel are refused at create/update time and an email channel on
+ * an existing rule counts as a failed delivery at fire time.
+ */
+
+interface AlertEmailMessage {
+    to: string[];
+    subject: string;
+    text: string;
+}
+interface AlertEmailTransport {
+    /**
+     * Sends one message. Resolves only when the SMTP server accepted it for
+     * every recipient; rejects otherwise.
+     */
+    send(message: AlertEmailMessage): Promise<void>;
+}
+/** What every channel is told about a transition (the webhook JSON body). */
+interface AlertNotificationPayload {
+    rule: {
+        id: string;
+        name: string;
+        signal: string;
+    };
+    value: number;
+    threshold: number;
+    comparison: string;
+    state: AlertState;
+    evaluatedAt: string;
+    projectId: string;
+    /**
+     * RFC 0002 Stage 6 — populated when the rule is bound to an Analysis
+     * (`rule.analysisId` set). The narrative is the gated, LLM-generated
+     * sentence the dashboard panel was last showing — what's actually
+     * happening, in plain English. Webhooks consuming this can put the
+     * narrative in the Slack/PagerDuty body directly.
+     */
+    analysis?: {
+        id: string;
+        narrative: string | null;
+        status: string | null;
+    };
+}
+declare const isValidEmailAddress: (addr: string) => boolean;
+declare function formatAlertEmail(payload: AlertNotificationPayload): {
+    subject: string;
+    text: string;
+};
 
 /**
  * Pluggable logger interface for the collector framework.
@@ -69,6 +127,12 @@ interface CollectorEnv {
     /** Durable Object namespace for live-tail SSE pub/sub. Optional — when
      *  unbound the /internal/telemetry/tail endpoint returns 503. */
     TAIL_HUB?: DurableObjectNamespace;
+    /**
+     * SMTP transport for email alert channels. Bound by hosts that can send
+     * mail (the Node collector, from `ALERT_SMTP_*`); never set on Cloudflare
+     * Workers. Without it, rules with an email channel are refused.
+     */
+    ALERT_EMAIL?: AlertEmailTransport;
     /** Write-only API key for SDK ingest endpoints (/v1/*) */
     INGEST_KEY?: string;
     /** Password for dashboard login */
@@ -155,7 +219,7 @@ declare const COLLECTOR_STRING_ENV_MANIFEST: {
 type CollectorOptionalStringEnvKey = (typeof COLLECTOR_OPTIONAL_STRING_ENV_KEYS)[number];
 type CollectorHostManagedEnvKey = (typeof COLLECTOR_HOST_MANAGED_ENV_KEYS)[number];
 type CollectorManifestStringEnvKey = CollectorOptionalStringEnvKey | CollectorHostManagedEnvKey;
-type CollectorObjectBindingKey = "DB" | "REPLAYS_BUCKET" | "PROFILES_BUCKET" | "TAIL_HUB";
+type CollectorObjectBindingKey = "DB" | "REPLAYS_BUCKET" | "PROFILES_BUCKET" | "TAIL_HUB" | "ALERT_EMAIL";
 type CollectorStringEnvKey = Exclude<keyof CollectorEnv, CollectorObjectBindingKey>;
 /**
  * Verifies that every string key in `declaredKeys` is categorized in either
@@ -202,4 +266,4 @@ declare function createIngestAuth(config?: {
     };
 }>;
 
-export { COLLECTOR_HOST_MANAGED_ENV_KEYS as C, type Logger as L, COLLECTOR_OPTIONAL_STRING_ENV_KEYS as a, COLLECTOR_STRING_ENV_MANIFEST as b, type ChildSpanRunner as c, type CollectorApp as d, type CollectorEnv as e, type CollectorHostManagedEnvKey as f, type CollectorManifestStringEnvKey as g, type CollectorObjectBindingKey as h, type CollectorOptionalStringEnvKey as i, type CollectorRouteContext as j, type CollectorStringEnvKey as k, assertCollectorEnvManifestCompleteness as l, consoleLogger as m, createIngestAuth as n, resetIngestAuthCache as r };
+export { type AlertEmailMessage as A, COLLECTOR_HOST_MANAGED_ENV_KEYS as C, type Logger as L, type AlertEmailTransport as a, type AlertNotificationPayload as b, COLLECTOR_OPTIONAL_STRING_ENV_KEYS as c, COLLECTOR_STRING_ENV_MANIFEST as d, type ChildSpanRunner as e, type CollectorApp as f, type CollectorEnv as g, type CollectorHostManagedEnvKey as h, type CollectorManifestStringEnvKey as i, type CollectorObjectBindingKey as j, type CollectorOptionalStringEnvKey as k, type CollectorRouteContext as l, type CollectorStringEnvKey as m, assertCollectorEnvManifestCompleteness as n, consoleLogger as o, createIngestAuth as p, formatAlertEmail as q, isValidEmailAddress as r, resetIngestAuthCache as s };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsunified/collector",
-  "version": "2.3.0",
+  "version": "2.4.3",
   "description": "Plugin-based observability collector runtime with pluggable SQL/blob storage.",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,7 @@
   "dependencies": {
     "@bufbuild/protobuf": "^2.11.0",
     "@obsunified/pprof-decoder": "2.0.2",
-    "@obsunified/types": "2.3.0"
+    "@obsunified/types": "2.4.1"
   },
   "peerDependencies": {
     "hono": "^4.7.0",

package/src/framework/env.ts

@@ -1,4 +1,5 @@
 import type { Context, Hono } from "hono";
+import type { AlertEmailTransport } from "../lib/alert-email";
 import type { Logger } from "./logger";
 
 /**
@@ -22,6 +23,12 @@ export interface CollectorEnv {
 	/** Durable Object namespace for live-tail SSE pub/sub. Optional — when
 	 *  unbound the /internal/telemetry/tail endpoint returns 503. */
 	TAIL_HUB?: DurableObjectNamespace;
+	/**
+	 * SMTP transport for email alert channels. Bound by hosts that can send
+	 * mail (the Node collector, from `ALERT_SMTP_*`); never set on Cloudflare
+	 * Workers. Without it, rules with an email channel are refused.
+	 */
+	ALERT_EMAIL?: AlertEmailTransport;
 	/** Write-only API key for SDK ingest endpoints (/v1/*) */
 	INGEST_KEY?: string;
 	/** Password for dashboard login */
@@ -146,7 +153,8 @@ export type CollectorObjectBindingKey =
 	| "DB"
 	| "REPLAYS_BUCKET"
 	| "PROFILES_BUCKET"
-	| "TAIL_HUB";
+	| "TAIL_HUB"
+	| "ALERT_EMAIL";
 
 export type CollectorStringEnvKey = Exclude<
 	keyof CollectorEnv,

package/src/index.ts

@@ -9,6 +9,7 @@ import { aiSpanPayloadsProcessorPlugin } from "./plugins/ai-span-payloads-proces
 import {
 	createAlertEvaluatorHandler,
 	evaluateAllRules,
+	evaluateRuleBatch,
 } from "./plugins/alerts-evaluator";
 import { alertsRoutesPlugin } from "./plugins/alerts-routes";
 import { analysesRoutesPlugin } from "./plugins/analyses-routes";
@@ -100,6 +101,13 @@ export {
 	type RetrievalEventRecord,
 	type ToolCallRecord,
 } from "./lib/actions-store";
+export {
+	type AlertEmailMessage,
+	type AlertEmailTransport,
+	type AlertNotificationPayload,
+	formatAlertEmail,
+	isValidEmailAddress,
+} from "./lib/alert-email";
 export { AlertsStore, compareValue } from "./lib/alerts-store";
 export {
 	computeChangeBlastRadius,
@@ -168,6 +176,11 @@ export {
 	isEvalCaseSourceType,
 	isEvalRunStatus,
 } from "./lib/eval-cases-store";
+export {
+	evaluateMetricQuery,
+	reduceSeries,
+	validateMetricQuery,
+} from "./lib/metric-alerts";
 export { MetricsStore } from "./lib/metrics-store";
 export { ProjectsStore } from "./lib/projects-store";
 export { D1Adapter, type SqlDb, type SqlStatement } from "./lib/sql-db";
@@ -192,6 +205,7 @@ export {
 	defaultSpanEnrichmentPlugin,
 	evalCasesRoutesPlugin,
 	evaluateAllRules,
+	evaluateRuleBatch,
 	evidenceRetrievalRoutesPlugin,
 	genAiNormalizerPlugin,
 	identityReceiverPlugin,

package/src/lib/alert-email.ts

@@ -0,0 +1,104 @@
+/**
+ * Email alert channel: the runtime-neutral half.
+ *
+ * The collector package runs on Cloudflare Workers as well as Node, and a
+ * Worker cannot open an SMTP connection. So the package only defines what an
+ * email transport must do (`AlertEmailTransport`) and how an alert reads as
+ * mail (`formatAlertEmail`); a host that can speak SMTP binds a transport as
+ * `env.ALERT_EMAIL` (the Node collector does, from `ALERT_SMTP_*`, see
+ * apps/collector-node/src/alert-email.ts). Without that binding, rules with
+ * an email channel are refused at create/update time and an email channel on
+ * an existing rule counts as a failed delivery at fire time.
+ */
+
+import type { AlertState } from "@obsunified/types";
+
+export interface AlertEmailMessage {
+	to: string[];
+	subject: string;
+	text: string;
+}
+
+export interface AlertEmailTransport {
+	/**
+	 * Sends one message. Resolves only when the SMTP server accepted it for
+	 * every recipient; rejects otherwise.
+	 */
+	send(message: AlertEmailMessage): Promise<void>;
+}
+
+/** What every channel is told about a transition (the webhook JSON body). */
+export interface AlertNotificationPayload {
+	rule: {
+		id: string;
+		name: string;
+		signal: string;
+	};
+	value: number;
+	threshold: number;
+	comparison: string;
+	state: AlertState;
+	evaluatedAt: string;
+	projectId: string;
+	/**
+	 * RFC 0002 Stage 6 — populated when the rule is bound to an Analysis
+	 * (`rule.analysisId` set). The narrative is the gated, LLM-generated
+	 * sentence the dashboard panel was last showing — what's actually
+	 * happening, in plain English. Webhooks consuming this can put the
+	 * narrative in the Slack/PagerDuty body directly.
+	 */
+	analysis?: {
+		id: string;
+		narrative: string | null;
+		status: string | null;
+	};
+}
+
+export const MAX_EMAIL_RECIPIENTS = 20;
+
+// Deliberately strict: one plain address, no display name, no whitespace,
+// commas, angle brackets or quotes (nothing that could add a header or a
+// second recipient).
+const EMAIL_RE =
+	/^[^\s@<>,;:"()[\]\\]+@[^\s@<>,;:"()[\]\\]+\.[^\s@<>,;:"()[\]\\]+$/;
+
+export const isValidEmailAddress = (addr: string): boolean =>
+	addr.length <= 254 && EMAIL_RE.test(addr);
+
+const oneLine = (s: string): string => s.replace(/[\r\n]+/g, " ").trim();
+
+export function formatAlertEmail(payload: AlertNotificationPayload): {
+	subject: string;
+	text: string;
+} {
+	const label = payload.state === "firing" ? "FIRING" : "RESOLVED";
+	const name = oneLine(payload.rule.name);
+	const lines = [
+		payload.state === "firing"
+			? `Alert rule "${name}" is firing.`
+			: `Alert rule "${name}" has resolved.`,
+		"",
+		`Rule:        ${name} (${payload.rule.id})`,
+		`Signal:      ${payload.rule.signal}`,
+		`State:       ${payload.state}`,
+		`Value:       ${payload.value}`,
+		`Condition:   value ${payload.comparison} ${payload.threshold}`,
+		`Threshold:   ${payload.threshold}`,
+		`Comparison:  ${payload.comparison}`,
+		`Evaluated:   ${payload.evaluatedAt}`,
+		`Project:     ${payload.projectId}`,
+	];
+	if (payload.analysis) {
+		lines.push(
+			`Analysis:    ${payload.analysis.id}${payload.analysis.status ? ` (${payload.analysis.status})` : ""}`,
+		);
+		if (payload.analysis.narrative) {
+			lines.push("", payload.analysis.narrative);
+		}
+	}
+	lines.push("", "Sent by obs-unified.");
+	return {
+		subject: `[obs-unified] ${label}: ${name}`,
+		text: `${lines.join("\n")}\n`,
+	};
+}

package/src/lib/alerts-store.test.ts

@@ -4,8 +4,8 @@
  */
 
 import type { AlertRuleInput } from "@obsunified/types";
-import { describe, expect, it } from "vitest";
-import { AlertsStore } from "./alerts-store";
+import { describe, expect, it, vi } from "vitest";
+import { AlertsStore, sanitizeEvaluationError } from "./alerts-store";
 import { ProjectsStore } from "./projects-store";
 import { createMigratedSqliteDb } from "./test-utils/node-sqlite-db";
 
@@ -151,3 +151,117 @@ describe("AlertsStore alert_state.notified (migration 049)", () => {
 		});
 	});
 });
+
+describe("AlertsStore.listRules evaluation status", () => {
+	it("reports the last evaluation, its error and whether the state was delivered", async () => {
+		vi.useFakeTimers({ toFake: ["Date"] });
+		try {
+			const db = createMigratedSqliteDb();
+			const project = await new ProjectsStore(db).createProject({
+				name: "S",
+				slug: "s",
+			});
+			const store = new AlertsStore(db);
+			const erroring = await store.createRule(
+				project.id,
+				input({ name: "erroring" }),
+			);
+			const undelivered = await store.createRule(
+				project.id,
+				input({ name: "undelivered" }),
+			);
+			const fresh = await store.createRule(
+				project.id,
+				input({ name: "fresh" }),
+			);
+
+			vi.setSystemTime(Date.parse("2026-10-31T10:00:00.000Z"));
+			await store.recordEvaluation(erroring.id, project.id, 3, "ok", false);
+			vi.setSystemTime(Date.parse("2026-10-31T10:05:00.000Z"));
+			await store.recordEvaluation(
+				erroring.id,
+				project.id,
+				0,
+				"ok",
+				false,
+				"error",
+				"connect ECONNREFUSED postgres://obs:hunter2@db:5432/obs\nat pool",
+			);
+			await store.transitionState(
+				undelivered.id,
+				project.id,
+				"firing",
+				"2026-10-31T10:05:00.000Z",
+			);
+			await store.recordEvaluation(
+				undelivered.id,
+				project.id,
+				7,
+				"firing",
+				false,
+			);
+
+			const byName = new Map(
+				(await store.listRules(project.id)).map((r) => [r.name, r]),
+			);
+			expect(byName.get("erroring")).toMatchObject({
+				currentState: undefined,
+				notificationDelivered: null,
+				lastEvaluation: {
+					evaluatedAt: "2026-10-31T10:05:00.000Z",
+					outcome: "error",
+					value: 0,
+					error: "connect ECONNREFUSED <url> at pool",
+				},
+			});
+			expect(JSON.stringify(byName.get("erroring"))).not.toContain("hunter2");
+			expect(byName.get("undelivered")).toMatchObject({
+				currentState: "firing",
+				notificationDelivered: false,
+				lastEvaluation: { outcome: "value", value: 7, error: null },
+			});
+			expect(byName.get("fresh")).toMatchObject({
+				notificationDelivered: null,
+				lastEvaluation: null,
+			});
+			// Existing fields are unchanged.
+			expect(byName.get("fresh")).toMatchObject({
+				id: fresh.id,
+				signal: "spans",
+				enabled: true,
+			});
+
+			await store.markNotified(
+				undelivered.id,
+				project.id,
+				"firing",
+				"2026-10-31T10:05:00.000Z",
+			);
+			expect(
+				(await store.listRules(project.id)).find(
+					(r) => r.name === "undelivered",
+				)?.notificationDelivered,
+			).toBe(true);
+
+			const evaluations = await store.listEvaluations({
+				ruleId: erroring.id,
+				projectId: project.id,
+				hours: 24 * 365,
+			});
+			expect(evaluations.evaluations[0]).toMatchObject({
+				outcome: "error",
+				error: "connect ECONNREFUSED <url> at pool",
+			});
+			db.close();
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("truncates long error messages", () => {
+		expect(sanitizeEvaluationError("x".repeat(800))).toHaveLength(500);
+		expect(sanitizeEvaluationError("see https://hooks.slack.com/T/B/s")).toBe(
+			"see <url>",
+		);
+	});
+});