@k2b/cloud 0.27.0 → 0.29.0

package/src/services/notifications/batches.ts

@@ -3,12 +3,15 @@ import { err, fail, ok, type Result } from "@k2b/stdlib";
 import type { Worker } from "@k2b/sync";
 import { sql } from "bun";
 import { lazySync } from "../../_internal/process-sync";
+import { type MailMessage, MailMessageSchema, type MailStatus, MailStatusSchema } from "../../contracts/outgoing-mail";
 import { markdown } from "../../shared/markdown";
 import { type AuditActor, audit } from "../audit";
 import { logger, trace } from "../logging";
+import { enqueueMail } from "../outgoing-mail/enqueue";
+import { outgoingMailStore } from "../outgoing-mail/store";
 import { parsePgJsonValue, toPgTextArray, toPgUuidArray } from "../postgres";
-
-import { sendEmail } from "./email";
+import { prepareNotificationEmail } from "./email-frame";
+import { normalizeNotificationMail, notificationMailError, notificationMailValidationError } from "./email-mail";
 
 const log = logger("notifications:batches");
 const CHUNK_SIZE = 100;
@@ -64,6 +67,8 @@ export type NotificationBatchRecipient = {
   profile: "user" | "guest";
   status: NotificationBatchRecipientStatus;
   notificationId: string | null;
+  outgoingMailId: string | null;
+  outgoingMailStatus: MailStatus | null;
   error: string | null;
   attemptCount: number;
   sentAt: string | null;
@@ -163,6 +168,8 @@ const mapRecipient = (row: BatchRow): NotificationBatchRecipient => ({
   profile: row.profile as "user" | "guest",
   status: row.status as NotificationBatchRecipientStatus,
   notificationId: row.notification_id as string | null,
+  outgoingMailId: typeof row.outgoing_mail_id === "string" ? row.outgoing_mail_id : null,
+  outgoingMailStatus: MailStatusSchema.nullable().parse(row.outgoing_mail_status ?? null),
   error: row.error as string | null,
   attemptCount: Number(row.attempt_count ?? 0),
   sentAt: row.sent_at ? (row.sent_at as Date).toISOString() : null,
@@ -210,29 +217,6 @@ const resolveCandidates = async (rawSelection: NotificationBatchSelection): Prom
   `;
 };
 
-const sendBatchEmail = async (params: {
-  recipient: string;
-  subject: string;
-  rawHtml: string;
-  sentBy?: string;
-}): Promise<{ id: string; status: "sent" | "error"; error?: string }> => {
-  const rows = await sql<BatchRow[]>`
-    INSERT INTO notifications.messages (type, recipient, subject, content, sent_by)
-    VALUES ('email', ${params.recipient}, ${params.subject}, ${params.rawHtml}, ${params.sentBy ?? null})
-    RETURNING id
-  `;
-  const id = rows[0]!.id as string;
-  try {
-    await sendEmail(params.recipient, params.subject, { rawHtml: params.rawHtml });
-    await sql`UPDATE notifications.messages SET sent_at = now(), error = NULL WHERE id = ${id}::uuid`;
-    return { id, status: "sent" };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    await sql`UPDATE notifications.messages SET error = ${message} WHERE id = ${id}::uuid`;
-    return { id, status: "error", error: message };
-  }
-};
-
 export const preview = async (selection: NotificationBatchSelection): Promise<NotificationBatchPreview> => {
   const candidates = await resolveCandidates(selection);
   return {
@@ -286,74 +270,147 @@ const refreshBatchCounters = async (batchId: string): Promise<NotificationBatch
 };
 
 const processBatchChunk = async (batchId: string): Promise<{ processed: number; remaining: number }> => {
-  await sql`
+  const [batchRow] = await sql<BatchRow[]>`
     UPDATE notifications.batches
     SET status = 'running', started_at = COALESCE(started_at, now())
     WHERE id = ${batchId}::uuid AND status IN ('ready', 'running')
+    RETURNING *
   `;
+  if (!batchRow) return { processed: 0, remaining: 0 };
+  const batch = mapBatch(batchRow);
 
-  const recipients = await sql<BatchRow[]>`
-    UPDATE notifications.batch_recipients r
-    SET status = 'sending', attempt_count = attempt_count + 1, updated_at = now()
-    WHERE (r.batch_id, r.user_id) IN (
-      SELECT batch_id, user_id
-      FROM notifications.batch_recipients
-      WHERE batch_id = ${batchId}::uuid
-        AND recipient IS NOT NULL
-        AND (
-          status = 'pending'
-          OR (status = 'sending' AND updated_at < now() - interval '5 minutes')
-        )
-      ORDER BY updated_at ASC
-      LIMIT ${CHUNK_SIZE}
-      FOR UPDATE SKIP LOCKED
+  // Settle a bounded page and its legacy message history in the same statement.
+  const settled = await sql<{ id: string }[]>`
+    WITH terminal AS (
+      SELECT r.user_id, r.outgoing_mail_id, m.status, m.sent_at, COALESCE(m.error_message, m.smtp_response, 'Outgoing mail ' || m.status, 'Outgoing mail record is no longer available.') AS error
+      FROM notifications.batch_recipients r
+      LEFT JOIN outgoing_mail.messages m ON m.id = r.outgoing_mail_id
+      WHERE r.batch_id = ${batchId}::uuid AND r.status = 'sending' AND r.outgoing_mail_id IS NOT NULL
+        AND (m.status IN ('sent', 'bounced', 'failed', 'cancelled') OR m.id IS NULL)
+      ORDER BY r.user_id LIMIT ${CHUNK_SIZE}
+    ), settled AS (
+      UPDATE notifications.batch_recipients r
+      SET status = CASE WHEN t.status IN ('sent', 'bounced') THEN 'sent' ELSE 'error' END,
+          sent_at = CASE WHEN t.status IN ('sent', 'bounced') THEN COALESCE(t.sent_at, now()) ELSE NULL END,
+          error = CASE WHEN t.status IN ('sent', 'bounced') THEN NULL ELSE t.error END, updated_at = now()
+      FROM terminal t
+      WHERE r.batch_id = ${batchId}::uuid AND r.user_id = t.user_id AND r.status = 'sending'
+        AND r.outgoing_mail_id = t.outgoing_mail_id
+      RETURNING r.notification_id, r.sent_at, r.error
     )
-    RETURNING r.*
+    UPDATE notifications.messages m SET sent_at = s.sent_at, error = s.error
+    FROM settled s WHERE m.id = s.notification_id AND m.mail_generation = 0 RETURNING m.id
   `;
 
-  const [batchRow] = await sql<BatchRow[]>`SELECT * FROM notifications.batches WHERE id = ${batchId}::uuid`;
-  if (!batchRow || batchRow.status === "cancelled") return { processed: 0, remaining: 0 };
-  const batch = mapBatch(batchRow);
+  const profile = (await outgoingMailStore.profilesForApp("core")).find((profile) => profile.default);
+  const claimSize =
+    profile?.quota.dailyRecipients == null
+      ? CHUNK_SIZE
+      : Math.max(0, Math.min(CHUNK_SIZE, profile.quota.dailyRecipients - profile.quota.usedLast24h));
+
+  type ClaimedRecipient = { user_id: string; recipient: string; notification_id: string | null };
+  // Persist a send generation before any external effect. Reclaim and worker
+  // retries reuse it; operator retries clear it and create a new generation.
+  const recipients = await sql.begin(async (tx) => {
+    const rows = await tx<ClaimedRecipient[]>`
+      UPDATE notifications.batch_recipients r
+      SET status = 'sending', attempt_count = attempt_count + 1, updated_at = now()
+      WHERE (r.batch_id, r.user_id) IN (
+        SELECT batch_id, user_id FROM notifications.batch_recipients
+        WHERE batch_id = ${batchId}::uuid AND recipient IS NOT NULL AND outgoing_mail_id IS NULL
+          AND (status = 'pending' OR (status = 'sending' AND updated_at < now() - interval '5 minutes'))
+        ORDER BY updated_at ASC LIMIT ${claimSize} FOR UPDATE SKIP LOCKED
+      )
+      RETURNING r.user_id, r.recipient, r.notification_id
+    `;
+    for (const row of rows) {
+      if (row.notification_id) continue;
+      const [message] = await tx<{ id: string }[]>`
+        INSERT INTO notifications.messages (type, recipient, subject, content, sent_by)
+        VALUES ('email', ${row.recipient}, ${batch.subject}, ${batch.bodyHtml}, ${batch.finalizedBy ?? batch.createdBy}::uuid)
+        RETURNING id
+      `;
+      if (!message) throw new Error("Notification batch message insert returned no row");
+      row.notification_id = message.id;
+      await tx`UPDATE notifications.batch_recipients SET notification_id = ${message.id}::uuid
+        WHERE batch_id = ${batchId}::uuid AND user_id = ${row.user_id}::uuid`;
+    }
+    return rows;
+  });
 
-  for (const recipient of recipients) {
+  const failRecipients = async (rows: ClaimedRecipient[], failure: ReturnType<typeof notificationMailError>) => {
+    const generations = toPgUuidArray(rows.flatMap((recipient) => (recipient.notification_id ? [recipient.notification_id] : [])));
+    await sql`
+      WITH changed AS (
+        UPDATE notifications.batch_recipients
+        SET status = ${failure.retryable ? "pending" : "error"}, error = ${failure.retryable ? null : failure.message}, updated_at = now()
+        WHERE batch_id = ${batchId}::uuid AND notification_id = ANY(${generations}::uuid[])
+          AND status = 'sending' AND outgoing_mail_id IS NULL
+        RETURNING notification_id, error
+      )
+      UPDATE notifications.messages m SET error = c.error FROM changed c WHERE m.id = c.notification_id
+    `;
+  };
+  let invalidCount = 0;
+  if (recipients.length) {
     try {
-      const result = await sendBatchEmail({
-        recipient: recipient.recipient as string,
-        subject: batch.subject,
-        rawHtml: batch.bodyHtml,
-        sentBy: batch.finalizedBy ?? batch.createdBy ?? undefined,
+      const frame = await prepareNotificationEmail({ rawHtml: batch.bodyHtml });
+      const shared = MailMessageSchema.pick({ subject: true, text: true, html: true }).safeParse({
+        subject: normalizeNotificationMail("", batch.subject).subject,
+        ...frame,
       });
-      await sql`
-        UPDATE notifications.batch_recipients
-        SET
-          status = ${result.status === "sent" ? "sent" : "error"},
-          notification_id = ${result.id}::uuid,
-          error = NULL,
-          sent_at = ${result.status === "sent" ? sql`now()` : null},
-          updated_at = now()
-        WHERE batch_id = ${batchId}::uuid AND user_id = ${recipient.user_id}::uuid
-      `;
+      if (!shared.success) throw notificationMailValidationError(shared.error);
+      const valid: { recipient: ClaimedRecipient; message: MailMessage }[] = [];
+      for (const recipient of recipients) {
+        const parsed = MailMessageSchema.safeParse({
+          ...normalizeNotificationMail(recipient.recipient, shared.data.subject),
+          ...shared.data,
+          key: `notification-message:${recipient.notification_id}`,
+        });
+        if (!parsed.success) {
+          await failRecipients([recipient], notificationMailError(notificationMailValidationError(parsed.error)));
+          invalidCount++;
+        } else valid.push({ recipient, message: parsed.data });
+      }
+      if (valid.length) {
+        const accepted = await enqueueMail(
+          "core",
+          valid.map(({ message }) => message),
+          { trustedHtml: true },
+        );
+        for (const [index, { recipient }] of valid.entries()) {
+          await sql`
+            WITH linked AS (
+              UPDATE notifications.batch_recipients SET outgoing_mail_id = ${accepted.ids[index]}::uuid, updated_at = now()
+              WHERE batch_id = ${batchId}::uuid AND user_id = ${recipient.user_id}::uuid
+                AND notification_id = ${recipient.notification_id}::uuid AND status = 'sending' AND outgoing_mail_id IS NULL
+              RETURNING notification_id, outgoing_mail_id
+            )
+            UPDATE notifications.messages m SET outgoing_mail_id = l.outgoing_mail_id
+            FROM linked l WHERE m.id = l.notification_id AND m.mail_generation = 0
+          `;
+        }
+      }
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      log.error("Batch recipient send failed", { batchId, userId: recipient.user_id, error: message });
-      await sql`
-        UPDATE notifications.batch_recipients
-        SET status = 'error', error = ${message}, updated_at = now()
-        WHERE batch_id = ${batchId}::uuid AND user_id = ${recipient.user_id}::uuid
-      `;
+      const failure = notificationMailError(error);
+      log.error("Notification batch enqueue failed", { batchId, code: failure.code, error: failure.message });
+      await failRecipients(recipients, failure);
+      // Backlog/quota/storage failures are not terminal recipient failures.
+      await refreshBatchCounters(batchId);
+      return { processed: invalidCount + settled.length, remaining: await remainingBatchRecipients(batchId) };
     }
   }
+  const remaining = await remainingBatchRecipients(batchId);
+  await refreshBatchCounters(batchId);
+  return { processed: recipients.length + settled.length, remaining };
+};
 
-  const [pendingRow] = await sql<BatchRow[]>`
-    SELECT COUNT(*)::int AS count
-    FROM notifications.batch_recipients
-    WHERE batch_id = ${batchId}::uuid
-      AND recipient IS NOT NULL
-      AND status IN ('pending', 'sending')
+const remainingBatchRecipients = async (batchId: string): Promise<number> => {
+  const [row] = await sql<{ count: number }[]>`
+    SELECT COUNT(*)::int AS count FROM notifications.batch_recipients
+    WHERE batch_id = ${batchId}::uuid AND recipient IS NOT NULL AND status IN ('pending', 'sending')
   `;
-  const remaining = Number(pendingRow?.count ?? 0);
-  await refreshBatchCounters(batchId);
-  return { processed: recipients.length, remaining };
+  return row?.count ?? 0;
 };
 
 const batchJob = lazySync((sync) => {
@@ -492,6 +549,8 @@ export const listRecipients = async (params: {
       r.profile,
       r.status,
       r.notification_id,
+      r.outgoing_mail_id,
+      mail.status AS outgoing_mail_status,
       COALESCE(m.error, r.error) AS error,
       r.attempt_count,
       r.sent_at,
@@ -499,6 +558,7 @@ export const listRecipients = async (params: {
       COUNT(*) OVER() AS total
     FROM notifications.batch_recipients r
     LEFT JOIN notifications.messages m ON m.id = r.notification_id
+    LEFT JOIN outgoing_mail.messages mail ON mail.id = r.outgoing_mail_id
     LEFT JOIN auth.users u ON u.id = r.user_id
     WHERE r.batch_id = ${params.batchId}::uuid
       AND (${params.status ?? null}::text IS NULL OR r.status = ${params.status ?? null})
@@ -620,7 +680,7 @@ export const retryFailed = async (params: {
   const result = await sql.begin(async (tx) => {
     const updated = await tx<BatchRow[]>`
       UPDATE notifications.batch_recipients
-      SET status = 'pending', error = NULL, notification_id = NULL, sent_at = NULL, updated_at = now()
+      SET status = 'pending', error = NULL, notification_id = NULL, outgoing_mail_id = NULL, sent_at = NULL, updated_at = now()
       WHERE batch_id = ${params.id}::uuid AND status = 'error' AND recipient IS NOT NULL
       RETURNING user_id
     `;
@@ -667,7 +727,7 @@ export const retryRecipient = async (params: {
   const result = await sql.begin(async (tx) => {
     const updated = await tx<BatchRow[]>`
       UPDATE notifications.batch_recipients
-      SET status = 'pending', error = NULL, notification_id = NULL, sent_at = NULL, updated_at = now()
+      SET status = 'pending', error = NULL, notification_id = NULL, outgoing_mail_id = NULL, sent_at = NULL, updated_at = now()
       WHERE batch_id = ${params.id}::uuid
         AND user_id = ${params.userId}::uuid
         AND status = 'error'

package/src/services/notifications/browser.ts

@@ -2,11 +2,13 @@ import { createHash } from "node:crypto";
 import { sql } from "bun";
 import webpush from "web-push";
 import { z } from "zod";
+import { notificationGroupTag } from "../../contracts/notification-group";
 import { isSafeNotificationTargetHref } from "../../contracts/notification-types";
 import { type BrowserPushSubscription, BrowserPushSubscriptionSchema } from "../../contracts/user-notifications";
 import { decryptSecret, encryptSecret } from "../secrets";
 import { coreSettings } from "../settings/api";
 import { type NotificationDestination, registerNotificationChannel } from "./channels";
+import { NOTIFICATION_PREVIEW_LIMIT } from "./preview";
 import { sendPinnedWebPush } from "./web-push-transport";
 
 type EndpointRow = {
@@ -21,15 +23,41 @@ type BrowserDeliveryPayload = {
   subscription: BrowserPushSubscription;
   eventId: string;
   title: string;
+  preview?: string;
   targetHref?: string;
+  group?: string;
+  badge?: number;
+  createdAt?: number;
 };
 
+// RFC 8030 section 7.2 guarantees 4,096 bytes; aes128gcm adds a header, tag, and padding delimiter.
+const WEB_PUSH_PLAINTEXT_BUDGET = 4_096 - 86 - 16 - 1;
+
+const browserPushMessage = (payload: BrowserDeliveryPayload): string =>
+  JSON.stringify({
+    type: "cloud-notification",
+    eventId: payload.eventId,
+    title: payload.title,
+    ...(payload.preview !== undefined ? { preview: payload.preview } : {}),
+    targetHref: payload.targetHref,
+    ...(payload.group !== undefined ? { group: payload.group } : {}),
+    ...(payload.badge !== undefined ? { badge: payload.badge } : {}),
+    ...(payload.createdAt !== undefined ? { createdAt: payload.createdAt } : {}),
+  });
+
 const BrowserDeliveryPayloadSchema = z.object({
   endpointId: z.uuid(),
   subscription: BrowserPushSubscriptionSchema,
   eventId: z.uuid(),
   title: z.string().min(1).max(200),
+  preview: z.string().min(1).max(NOTIFICATION_PREVIEW_LIMIT).optional(),
   targetHref: z.string().max(4_000).refine(isSafeNotificationTargetHref).optional(),
+  group: z
+    .string()
+    .regex(/^[A-Za-z0-9._:-]+$/)
+    .optional(),
+  badge: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).optional(),
+  createdAt: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).optional(),
 });
 
 const BrowserDestinationContextSchema = z.object({
@@ -142,13 +170,27 @@ const browserDriver = {
   },
   createPayload: ({ presentation, destination, event }) => {
     const context = BrowserDestinationContextSchema.parse(destination.context);
-    return BrowserDeliveryPayloadSchema.parse({
+    const group =
+      presentation.group === undefined
+        ? undefined
+        : notificationGroupTag(event.definitionId.slice(0, event.definitionId.lastIndexOf(".")), presentation.group);
+    if (group === null) throw new Error("Invalid notification group tag");
+    const payload = BrowserDeliveryPayloadSchema.parse({
       endpointId: context.endpointId,
       subscription: context.subscription,
       eventId: event.id,
       title: presentation.title,
+      ...(presentation.preview !== undefined ? { preview: presentation.preview } : {}),
       targetHref: presentation.targetHref,
+      ...(group !== undefined ? { group } : {}),
+      ...(presentation.badge !== undefined ? { badge: presentation.badge } : {}),
+      ...(presentation.group !== undefined || presentation.badge !== undefined ? { createdAt: Date.now() } : {}),
     });
+    if (payload.preview !== undefined && Buffer.byteLength(browserPushMessage(payload), "utf8") > WEB_PUSH_PLAINTEXT_BUDGET) {
+      const { preview: _preview, ...titleOnlyPayload } = payload;
+      return titleOnlyPayload;
+    }
+    return payload;
   },
   deliver: async (value: unknown) => {
     const payload: BrowserDeliveryPayload = BrowserDeliveryPayloadSchema.parse(value);
@@ -166,20 +208,11 @@ const browserDriver = {
     }
     await ensureWebPushConfigured();
     try {
-      await sendPinnedWebPush(
-        payload.subscription,
-        JSON.stringify({
-          type: "cloud-notification",
-          eventId: payload.eventId,
-          title: payload.title,
-          targetHref: payload.targetHref,
-        }),
-        {
-          TTL: 24 * 60 * 60,
-          urgency: "normal",
-          topic: createHash("sha256").update(payload.eventId).digest("base64url").slice(0, 32),
-        },
-      );
+      await sendPinnedWebPush(payload.subscription, browserPushMessage(payload), {
+        TTL: 24 * 60 * 60,
+        urgency: "normal",
+        topic: createHash("sha256").update(payload.eventId).digest("base64url").slice(0, 32),
+      });
     } catch (error) {
       const statusCode = error && typeof error === "object" && "statusCode" in error ? Number(error.statusCode) : null;
       if (statusCode === 404 || statusCode === 410) {

package/src/services/notifications/channels.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import type { EmailNotificationPresentation, NotificationChannelId, NotificationPresentation } from "../../contracts/notification-types";
-import { sendEmail } from "./email";
+import { notificationMailOutcome, notificationMailOutcomeById, sendNotificationMail } from "./email-mail";
 
 export type ResolvedNotificationRecipient = {
   userId: string | null;
@@ -23,7 +23,22 @@ export type NotificationChannelDriver = {
     destination: NotificationDestination;
     event: { id: string; definitionId: string };
   }) => unknown;
-  deliver: (payload: unknown) => Promise<void>;
+  deliver: (
+    payload: unknown,
+    context?: { deliveryId: string; signal?: AbortSignal; outgoingMailId?: string },
+  ) => Promise<
+    | void
+    | {
+        status: "delivered";
+        outgoingMailId?: string;
+      }
+    | {
+        status: "pending";
+        retryAfterMs: number;
+        outgoingMailId?: string;
+        errorMessage?: string | null;
+      }
+  >;
 };
 
 const drivers = new Map<string, NotificationChannelDriver>();
@@ -58,7 +73,6 @@ type EmailPayload = {
   subject: string;
   content?: string;
   rawHtml?: string;
-  messageId?: string;
 };
 
 const parseEmailPayload = (value: unknown): EmailPayload => {
@@ -69,8 +83,7 @@ const parseEmailPayload = (value: unknown): EmailPayload => {
   }
   if (payload.content !== undefined && typeof payload.content !== "string") throw new Error("Invalid email notification payload");
   if (payload.rawHtml !== undefined && typeof payload.rawHtml !== "string") throw new Error("Invalid email notification payload");
-  if (payload.messageId !== undefined && typeof payload.messageId !== "string") throw new Error("Invalid email notification payload");
-  return { to: payload.to, subject: payload.subject, content: payload.content, rawHtml: payload.rawHtml, messageId: payload.messageId };
+  return { to: payload.to, subject: payload.subject, content: payload.content, rawHtml: payload.rawHtml };
 };
 
 const emailDriver: NotificationChannelDriver = {
@@ -80,7 +93,7 @@ const emailDriver: NotificationChannelDriver = {
     const email = normalizeEmail(recipient.email);
     return [{ key: emailKey(email), label: emailLabel(email), context: { email } }];
   },
-  createPayload: ({ presentation, email, destination, event }) => {
+  createPayload: ({ presentation, email, destination }) => {
     const context = destination.context as { email?: unknown };
     if (typeof context.email !== "string") throw new Error("Email destination is missing an address");
     return {
@@ -88,16 +101,23 @@ const emailDriver: NotificationChannelDriver = {
       subject: email?.subject ?? presentation.title,
       content: email?.content ?? presentation.body,
       rawHtml: email?.rawHtml,
-      messageId: `<cloud-notification-${event.id}@cloud.invalid>`,
     } satisfies EmailPayload;
   },
-  deliver: async (value) => {
+  deliver: async (value, context) => {
+    if (context?.outgoingMailId) return notificationMailOutcomeById(context.outgoingMailId);
     const payload = parseEmailPayload(value);
-    await sendEmail(payload.to, payload.subject, {
-      content: payload.content,
-      rawHtml: payload.rawHtml,
-      messageId: payload.messageId,
-    });
+    return notificationMailOutcome(
+      await sendNotificationMail(
+        payload.to,
+        payload.subject,
+        {
+          content: payload.content,
+          rawHtml: payload.rawHtml,
+        },
+        context ? `notification-delivery:${context.deliveryId}` : undefined,
+        context?.signal,
+      ),
+    );
   },
 };
 

package/src/services/notifications/dispatcher.ts

@@ -1,6 +1,8 @@
 import { sql } from "bun";
+import { z } from "zod";
 import { decryptSecret } from "../secrets";
 import { getNotificationChannel } from "./channels";
+import { quietStateForEvent } from "./quiet";
 
 const MAX_DELIVERY_ATTEMPTS = 5;
 const BASE_RETRY_MS = 2_000;
@@ -14,14 +16,44 @@ type DeliveryRow = {
   required: boolean;
   route_priority: number | null;
   attempt_count: number;
+  outgoing_mail_id: string | null;
 };
 
 export type DeliveryAttemptResult =
-  | { status: "skipped" | "delivered" | "failed" }
+  | { status: "skipped" | "delivered" | "suppressed" | "failed" }
+  | { status: "pending"; retryAfterMs: number }
   | { status: "retry"; retryAfterMs: number; error: string };
 
 const retryDelay = (attempt: number): number => Math.min(BASE_RETRY_MS * 2 ** Math.max(0, attempt - 1), MAX_RETRY_MS);
 
+/**
+ * Do not disturb and quiet hours hold back recommended browser notifications when they would go out. The
+ * notification is dropped, not postponed, so nothing arrives in a burst when the quiet time ends, and it is not
+ * rerouted: the event's waiting fallbacks end with it. Required deliveries are part of a protocol and still go.
+ */
+const holdBackForQuietTime = async (delivery: DeliveryRow): Promise<boolean> => {
+  if (delivery.channel !== "browser" || delivery.required) return false;
+  const quiet = await quietStateForEvent(delivery.event_id);
+  if (!quiet?.active) return false;
+  const code = quiet.reason === "doNotDisturb" ? "do_not_disturb" : "quiet_hours";
+  const message = quiet.reason === "doNotDisturb" ? "Held back by do not disturb." : "Held back during quiet hours.";
+  // One transaction: a crash in between must not leave fallbacks waiting, with their payload, behind a dropped push.
+  await sql.begin(async (tx) => {
+    await tx`
+      UPDATE notifications.deliveries
+      SET status = 'suppressed', attempt_count = attempt_count - 1, next_attempt_at = NULL,
+          error_code = ${code}, error_message = ${message}, payload_encrypted = NULL, updated_at = now()
+      WHERE id = ${delivery.id}::uuid AND status = 'sending'
+    `;
+    await tx`
+      UPDATE notifications.deliveries
+      SET status = 'suppressed', error_code = ${code}, error_message = ${message}, payload_encrypted = NULL, updated_at = now()
+      WHERE event_id = ${delivery.event_id}::uuid AND required = false AND status = 'deferred'
+    `;
+  });
+  return true;
+};
+
 const activateNextFallback = async (eventId: string): Promise<string[]> => {
   const delivered = await sql<{ exists: boolean }[]>`
     SELECT EXISTS (
@@ -65,7 +97,10 @@ const activateNextFallback = async (eventId: string): Promise<string[]> => {
   return rows.map((row) => row.id);
 };
 
-export const processNotificationDelivery = async (deliveryId: string): Promise<DeliveryAttemptResult & { activatedIds?: string[] }> => {
+export const processNotificationDelivery = async (
+  deliveryId: string,
+  signal?: AbortSignal,
+): Promise<DeliveryAttemptResult & { activatedIds?: string[] }> => {
   const rows = await sql<DeliveryRow[]>`
     UPDATE notifications.deliveries
     SET status = 'sending', attempt_count = attempt_count + 1,
@@ -73,12 +108,13 @@ export const processNotificationDelivery = async (deliveryId: string): Promise<D
     WHERE id = ${deliveryId}::uuid
       AND status = 'pending'
       AND (next_attempt_at IS NULL OR next_attempt_at <= now())
-    RETURNING id, event_id, channel, payload_encrypted, required, route_priority, attempt_count
+    RETURNING id, event_id, channel, payload_encrypted, required, route_priority, attempt_count, outgoing_mail_id
   `;
   const delivery = rows[0];
   if (!delivery) return { status: "skipped" };
 
   try {
+    if (await holdBackForQuietTime(delivery)) return { status: "suppressed" };
     const driver = getNotificationChannel(delivery.channel);
     if (!driver)
       throw Object.assign(new Error(`Notification channel "${delivery.channel}" is unavailable`), { code: "channel_unavailable" });
@@ -86,10 +122,34 @@ export const processNotificationDelivery = async (deliveryId: string): Promise<D
       throw Object.assign(new Error("Notification delivery payload is unavailable"), { code: "payload_missing", retryable: false });
     }
     const payload = await decryptSecret(delivery.payload_encrypted);
-    await driver.deliver(payload);
+    const outcome = await driver.deliver(payload, {
+      deliveryId: delivery.id,
+      ...(signal ? { signal } : {}),
+      ...(delivery.outgoing_mail_id ? { outgoingMailId: delivery.outgoing_mail_id } : {}),
+    });
+    // Third-party drivers may return provider bodies; only a UUID can name an outgoing mail.
+    const mailId = z.uuid().safeParse(outcome?.outgoingMailId).data ?? null;
+    if (
+      outcome?.status === "pending" &&
+      typeof outcome.retryAfterMs === "number" &&
+      Number.isFinite(outcome.retryAfterMs) &&
+      outcome.retryAfterMs > 0
+    ) {
+      const retryAfterMs = Math.round(Math.min(MAX_RETRY_MS, Math.max(BASE_RETRY_MS, outcome.retryAfterMs)));
+      await sql`
+        UPDATE notifications.deliveries
+        SET status = 'pending', attempt_count = attempt_count - 1,
+            next_attempt_at = now() + (${retryAfterMs}::int * INTERVAL '1 millisecond'),
+            outgoing_mail_id = COALESCE(${mailId}::uuid, outgoing_mail_id),
+            error_code = NULL, error_message = ${typeof outcome.errorMessage === "string" ? outcome.errorMessage : null}, updated_at = now()
+        WHERE id = ${delivery.id}::uuid
+      `;
+      return { status: "pending", retryAfterMs };
+    }
     await sql`
       UPDATE notifications.deliveries
-      SET status = 'delivered', delivered_at = now(), next_attempt_at = NULL,
+      SET outgoing_mail_id = COALESCE(${mailId}::uuid, outgoing_mail_id),
+          status = 'delivered', delivered_at = now(), next_attempt_at = NULL,
           error_code = NULL, error_message = NULL, payload_encrypted = NULL, updated_at = now()
       WHERE id = ${delivery.id}::uuid
     `;
@@ -98,6 +158,8 @@ export const processNotificationDelivery = async (deliveryId: string): Promise<D
   } catch (error) {
     const message = error instanceof Error ? error.message : "Notification delivery failed";
     const code = error && typeof error === "object" && "code" in error ? String(error.code) : "provider_error";
+    const outgoingMailId =
+      error && typeof error === "object" && "outgoingMailId" in error ? (z.uuid().safeParse(error.outgoingMailId).data ?? null) : null;
     const retryable = !(error && typeof error === "object" && "retryable" in error && error.retryable === false);
     if (retryable && delivery.attempt_count < MAX_DELIVERY_ATTEMPTS) {
       const retryAfterMs = retryDelay(delivery.attempt_count);
@@ -112,7 +174,8 @@ export const processNotificationDelivery = async (deliveryId: string): Promise<D
 
     await sql`
       UPDATE notifications.deliveries
-      SET status = 'failed', next_attempt_at = NULL, error_code = ${code},
+      SET outgoing_mail_id = COALESCE(${outgoingMailId}::uuid, outgoing_mail_id),
+          status = 'failed', next_attempt_at = NULL, error_code = ${code},
           error_message = ${message}, payload_encrypted = NULL, updated_at = now()
       WHERE id = ${delivery.id}::uuid
     `;
@@ -137,3 +200,22 @@ export const recoverNotificationDeliveries = async (): Promise<string[]> => {
   `;
   return rows.map((row) => row.id);
 };
+
+export const reconcileNotificationMessages = async (): Promise<void> => {
+  await sql`
+    WITH terminal AS (
+      SELECT m.id, m.outgoing_mail_id, mail.status, mail.sent_at,
+        COALESCE(mail.error_message, mail.smtp_response, 'Outgoing mail record is no longer available.') AS error
+      FROM notifications.messages m
+      LEFT JOIN outgoing_mail.messages mail ON mail.id = m.outgoing_mail_id
+      WHERE m.outgoing_mail_id IS NOT NULL AND m.sent_at IS NULL AND m.error IS NULL
+        AND (mail.status IN ('sent', 'bounced', 'failed', 'cancelled') OR mail.id IS NULL)
+      ORDER BY m.outgoing_mail_id, m.id LIMIT 500
+    )
+    UPDATE notifications.messages m
+    SET sent_at = CASE WHEN t.status IN ('sent', 'bounced') THEN t.sent_at ELSE NULL END,
+        error = CASE WHEN t.status IN ('sent', 'bounced') THEN NULL ELSE t.error END
+    FROM terminal t
+    WHERE m.id = t.id AND m.outgoing_mail_id = t.outgoing_mail_id AND m.sent_at IS NULL AND m.error IS NULL
+  `;
+};