@obsunified/collector 2.2.3 → 2.4.3

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>",
+		);
+	});
+});