improve alert emails: human-readable bucket times, drop count for single anomaly

Author: uriva

deno.lock

@@ -45,6 +45,20 @@ const sendEmail = async (email: Email) => {
   return response;
 };
 
+const days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const months = [
+  "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+  "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+];
+
+const hourLabel = (h: number) =>
+  h === 0 ? "12am" : h < 12 ? `${h}am` : h === 12 ? "12pm" : `${h - 12}pm`;
+
+export const formatBucket = (bucket: string) => {
+  const d = new Date(`${bucket}:00:00Z`);
+  return `${days[d.getUTCDay()]} ${months[d.getUTCMonth()]} ${d.getUTCDate()}, ${hourLabel(d.getUTCHours())}`;
+};
+
 const metricLabel = (metric: Anomaly["metric"]) =>
   metric === "userSpike"
     ? "User Spike"
@@ -73,7 +87,7 @@ const formatAnomaly = (showUser: boolean) =>
   `<tr>
     <td>${eventName}</td>
     ${showUser ? `<td>${userId ?? "-"}</td>` : ""}
-    <td>${bucket}</td>
+    <td>${formatBucket(bucket)}</td>
     <td>${expected}</td>
     <td>${actual}</td>
     <td>${zScore}</td>
@@ -99,10 +113,12 @@ const groupByMetric = (anomalies: Anomaly[]) =>
     anomalies.filter((a) => a.metric === metric),
   ] as const);
 
-const anomaliesHtml = (projectName: string, anomalies: Anomaly[]) =>
-  `<h2>${projectName}: ${anomalies.length} Anomal${
-    anomalies.length === 1 ? "y" : "ies"
-  } Detected</h2>
+export const anomaliesHtml = (projectName: string, anomalies: Anomaly[]) =>
+  `<h2>${projectName}: ${
+    anomalies.length === 1
+      ? "Anomaly Detected"
+      : `${anomalies.length} Anomalies Detected`
+  }</h2>
   ${
     groupByMetric(anomalies).map(([metric, group]) =>
       sectionHtml(metric, group)
@@ -115,9 +131,9 @@ const anomalyText = (
 ) =>
   `  ${eventName}${
     userId ? ` (user: ${userId})` : ""
-  } in ${bucket} — expected ${expected}, got ${actual} (score=${zScore})`;
+  } in ${formatBucket(bucket)} — expected ${expected}, got ${actual} (score=${zScore})`;
 
-const anomaliesText = (anomalies: Anomaly[]) =>
+export const anomaliesText = (anomalies: Anomaly[]) =>
   groupByMetric(anomalies).map(([metric, group]) =>
     `${metricLabel(metric)}:\n${group.map(anomalyText).join("\n")}`
   ).join("\n\n");
@@ -130,7 +146,7 @@ const subjectLine = (
     userId ? ` (${userId})` : ""
   }`;
 
-const batchSubject = (projectName: string, anomalies: Anomaly[]) =>
+export const batchSubject = (projectName: string, anomalies: Anomaly[]) =>
   anomalies.length === 1
     ? subjectLine(projectName, anomalies[0])
     : `[${projectName}] ${anomalies.length} anomalies detected`;

src/email.ts

@@ -0,0 +1,87 @@
+import { assertEquals } from "jsr:@std/assert";
+import type { Anomaly } from "./anomaly.ts";
+import {
+  anomaliesHtml,
+  anomaliesText,
+  batchSubject,
+  formatBucket,
+} from "./email.ts";
+
+const singleAnomaly: Anomaly = {
+  projectId: "proj1",
+  eventName: "login",
+  bucket: "2026-04-06T23",
+  expected: 10,
+  actual: 30,
+  zScore: 3.5,
+  metric: "totalCount",
+  detectedAt: "2026-04-06T23:30:00Z",
+};
+
+const twoAnomalies: Anomaly[] = [
+  singleAnomaly,
+  {
+    projectId: "proj1",
+    eventName: "signup",
+    bucket: "2026-04-07T09",
+    expected: 5,
+    actual: 20,
+    zScore: 4.1,
+    metric: "percentageSpike",
+    detectedAt: "2026-04-07T09:15:00Z",
+    userId: "user123",
+  },
+];
+
+Deno.test("batchSubject uses specific subject for single anomaly", () => {
+  assertEquals(
+    batchSubject("myapp", [singleAnomaly]),
+    "[myapp] Total Count: login",
+  );
+});
+
+Deno.test("batchSubject shows count for multiple anomalies", () => {
+  assertEquals(
+    batchSubject("myapp", twoAnomalies),
+    "[myapp] 2 anomalies detected",
+  );
+});
+
+Deno.test("anomaliesHtml says 'Anomaly Detected' without count for single anomaly", () => {
+  const html = anomaliesHtml("myapp", [singleAnomaly]);
+  assertEquals(html.includes("1 Anomaly"), false);
+  assertEquals(html.includes("Anomaly Detected"), true);
+});
+
+Deno.test("anomaliesHtml shows count for multiple anomalies", () => {
+  const html = anomaliesHtml("myapp", twoAnomalies);
+  assertEquals(html.includes("2 Anomalies Detected"), true);
+});
+
+Deno.test("formatBucket renders human-readable date", () => {
+  assertEquals(formatBucket("2026-04-06T23"), "Mon Apr 6, 11pm");
+});
+
+Deno.test("formatBucket renders midnight as 12am", () => {
+  assertEquals(formatBucket("2026-04-07T00"), "Tue Apr 7, 12am");
+});
+
+Deno.test("formatBucket renders noon as 12pm", () => {
+  assertEquals(formatBucket("2026-04-07T12"), "Tue Apr 7, 12pm");
+});
+
+Deno.test("formatBucket renders morning hour", () => {
+  assertEquals(formatBucket("2026-04-07T09"), "Tue Apr 7, 9am");
+});
+
+Deno.test("anomaliesHtml uses formatted bucket not raw ISO", () => {
+  const html = anomaliesHtml("myapp", [singleAnomaly]);
+  assertEquals(html.includes("2026-04-06T23"), false);
+  assertEquals(html.includes("Mon Apr 6, 11pm"), true);
+});
+
+Deno.test("anomaliesText uses formatted bucket not raw ISO", () => {
+  const text = anomaliesText([singleAnomaly]);
+  assertEquals(text.includes("2026-04-06T23"), false);
+  assertEquals(text.includes("Mon Apr 6, 11pm"), true);
+});