@mohasinac/appkit 4.35.0 → 4.35.2

package/dist/_internal/server/jobs/core/onOrderCreate.js

@@ -1,8 +1,9 @@
 import { normalizeError } from "../../../../errors/normalize";
-import { storeRepository, userRepository } from "../../../../repositories";
+import { adminNotificationsRepository, storeRepository, userRepository } from "../../../../repositories";
 import { decryptPii } from "../../../../security/index";
 import { sendWhatsAppBusinessMessage, buildPurchaseAnnouncementMessage, } from "../../../../features/whatsapp-bot/server";
 import { resolveKeys } from "../../../../core/integration-keys";
+import { guardSend, logSuppressedSend } from "../../notifications/send-guard";
 async function sendAnnouncement(ctx, toPhone, message, phoneNumberId, accessToken, label, orderId) {
     try {
         const sent = await sendWhatsAppBusinessMessage({
@@ -68,21 +69,10 @@ async function resolveWhatsAppCredentials(ctx, orderId) {
     return {
         phoneNumberId: usable(db.whatsappPhoneNumberId) || usable(ctx.env("WHATSAPP_PHONE_NUMBER_ID")),
         accessToken: usable(db.whatsappCloudApiToken) || usable(ctx.env("WHATSAPP_CLOUD_API_TOKEN")),
-        adminNumbersRaw: usable(db.whatsappAdminNotifyNumbers) || usable(ctx.env("WHATSAPP_ADMIN_NOTIFY_NUMBERS")),
     };
 }
 export async function handleOrderCreate(input, ctx) {
     const { orderId, order } = input;
-    // Credentials resolve DB-first (Admin → Site Settings → WhatsApp) with an env
-    // fallback, matching resolveKeys() and every other WhatsApp send path. This
-    // read ctx.env() ONLY until 2026-08-22, so credentials saved in Site Settings
-    // never reached the order-placed announcement — it silently no-op'd unless the
-    // Functions runtime also carried the env vars.
-    const { phoneNumberId, accessToken, adminNumbersRaw } = await resolveWhatsAppCredentials(ctx, orderId);
-    if (!phoneNumberId || !accessToken) {
-        ctx.logger.info("WhatsApp Cloud API not configured — skipping announcement", { orderId });
-        return;
-    }
     const items = order.items ?? [];
     const firstItem = items[0];
     const firstItemName = firstItem?.productTitle ?? "an item";
@@ -95,20 +85,67 @@ export async function handleOrderCreate(input, ctx) {
         totalAmount: order.totalPrice ?? 0,
         orderId,
     });
-    const adminNumbers = adminNumbersRaw
-        .split(",")
-        .map((n) => n.trim().replace(/\D/g, ""))
-        .filter(Boolean);
-    for (const num of adminNumbers) {
-        await sendAnnouncement(ctx, num, message, phoneNumberId, accessToken, "admin", orderId);
+    /*
+     * Staff side: one durable row, not a WhatsApp message per admin number.
+     *
+     * 🛑 This used to loop `whatsappAdminNotifyNumbers` and send the purchase
+     * announcement to every one of them, ON EVERY ORDER — the highest-volume
+     * staff blast in the codebase. It is now an `adminNotifications` row that
+     * the admin inbox reads and the daily digest counts.
+     *
+     * Written BEFORE the credential check on purpose. The old code returned
+     * early when WhatsApp was unconfigured, which meant that with no Meta
+     * credentials — the state this project is actually in — an order produced
+     * no staff signal at all, and no record that it hadn't.
+     */
+    try {
+        await adminNotificationsRepository.create({
+            category: "growth",
+            title: "New order placed",
+            body: message,
+            severity: "info",
+            isRead: false,
+            entityType: "order",
+            entityId: orderId,
+            audienceUserIds: [],
+        });
     }
+    catch (err) {
+        void normalizeError(err);
+        ctx.logger.error("Failed to write admin order notification (non-fatal)", err, { orderId });
+    }
+    /*
+     * Seller side keeps WhatsApp: it is ONE message to ONE person about their
+     * own sale, which is the case the channel is good at. Credentials resolve
+     * DB-first (Admin → Site Settings → WhatsApp) with an env fallback — this
+     * read `ctx.env()` only until 2026-08-22, so credentials saved in Site
+     * Settings never reached the announcement and it silently no-op'd.
+     */
     const storeId = order.storeId;
-    if (storeId) {
-        await notifyStoreOwner(ctx, storeId, message, phoneNumberId, accessToken, orderId);
+    if (!storeId) {
+        ctx.logger.info("Order has no storeId — nothing to announce to a seller", { orderId });
+        return;
     }
-    ctx.logger.info(`Order announcement complete`, {
-        orderId,
-        adminCount: adminNumbers.length,
-        storeId: storeId ?? "unknown",
-    });
+    const { phoneNumberId, accessToken } = await resolveWhatsAppCredentials(ctx, orderId);
+    if (!phoneNumberId || !accessToken) {
+        ctx.logger.info("WhatsApp Cloud API not configured — skipping seller announcement", { orderId });
+        return;
+    }
+    // Audience is "user": a seller receiving news of their own sale is a
+    // marketplace participant, not an operator of the site. Staff exemption is
+    // for the digest and the payout summary, and widening it to "anyone we think
+    // ought to see this" would make the kill switch mean nothing.
+    const guard = {
+        channel: "whatsapp",
+        feature: "order_placed_seller",
+        audience: "user",
+    };
+    const decision = await guardSend(guard);
+    if (!decision.allow) {
+        logSuppressedSend(guard, decision);
+        ctx.logger.info("Seller order announcement suppressed by messaging guard", { orderId, storeId });
+        return;
+    }
+    await notifyStoreOwner(ctx, storeId, message, phoneNumberId, accessToken, orderId);
+    ctx.logger.info(`Order announcement complete`, { orderId, storeId });
 }

package/dist/_internal/server/jobs/core/onScamReportCreate.js

@@ -1,5 +1,5 @@
 import { normalizeError } from "../../../../errors/normalize";
-import { userRepository } from "../../../../repositories";
+import { adminNotificationsRepository, userRepository } from "../../../../repositories";
 import { sendNotification } from "../../../../features/admin/actions/notification-actions";
 import { SCAM_TYPE_LABELS } from "../../../../features/scams/constants/scam-types";
 export async function handleScamReportCreate(input, ctx) {
@@ -12,7 +12,7 @@ export async function handleScamReportCreate(input, ctx) {
             const reporter = await userRepository.findById(reportedBy);
             await sendNotification({
                 userId: reportedBy,
-                type: "account_action",
+                type: "scam_report_update",
                 priority: "normal",
                 title: "Scam report submitted",
                 message: `Your report for "${name}" has been received. Our team will review it within 48 hours.`,
@@ -27,31 +27,42 @@ export async function handleScamReportCreate(input, ctx) {
             ctx.logger.error("Failed to notify reporter (non-fatal)", err, { scammerId, reportedBy });
         }
     }
-    // 2. Notify all employees with admin:scammers:read permission
+    /*
+     * 2. Tell STAFF — once, into the admin inbox.
+     *
+     * 🛑 This used to be `Promise.all` over `userRepository.list({ pageSize: 100 })`,
+     * i.e. **one `sendNotification` per employee, up to 100, per report filed**.
+     * Each of those was a potential email against a 100/day Resend allowance, so
+     * a single scam report could consume the entire day — and it was a hundred
+     * concurrent Firestore writes besides.
+     *
+     * It was also the wrong shape regardless of cost: a scam report is one
+     * event needing one person to action it, not N personal messages. The
+     * `adminNotifications` collection exists for exactly this and is already
+     * read by `GET /api/admin/admin-notifications` and surfaced in the admin
+     * inbox — `audienceUserIds: []` means "all admins" rather than a fan-out.
+     *
+     * The daily digest carries the count as well, so nothing depends on someone
+     * happening to look at the inbox.
+     */
     try {
-        const result = await userRepository.list({
-            filters: "role==employee",
-            page: 1,
-            pageSize: 100,
-        });
         const scamTypeLabel = scamType ? (SCAM_TYPE_LABELS[scamType] ?? scamType) : "Unknown";
         const amountStr = amountLost ? ` ₹${amountLost.toLocaleString("en-IN")}` : "";
         const platformStr = scamPlatform ? ` via ${scamPlatform}` : "";
-        await Promise.all(result.items.filter((e) => !!e.id).map((employee) => sendNotification({
-            userId: employee.id,
-            type: "account_action",
-            priority: "normal",
+        await adminNotificationsRepository.create({
+            category: "fraud",
             title: "New scam report submitted",
-            message: `A report was submitted for "${name}" — ${scamTypeLabel}${platformStr}.${amountStr}`,
-            relatedId: scammerId,
-            relatedType: "scammer",
-            userEmail: employee.email ?? undefined,
-            userPhone: employee.phoneNumber ?? undefined,
-        }).catch((err) => ctx.logger.error("Failed to notify employee (non-fatal)", err, { scammerId, employeeId: employee.id ?? null }))));
+            body: `A report was submitted for "${name}" — ${scamTypeLabel}${platformStr}.${amountStr}`,
+            severity: "warning",
+            isRead: false,
+            entityType: "scammer",
+            entityId: scammerId,
+            audienceUserIds: [],
+        });
     }
     catch (err) {
         void normalizeError(err);
-        ctx.logger.error("Failed to query employees for scam notification (non-fatal)", err, { scammerId });
+        ctx.logger.error("Failed to write admin scam-report notification (non-fatal)", err, { scammerId });
     }
     ctx.logger.info("onScamReportCreate complete", { scammerId, reportedBy: reportedBy ?? null });
 }

package/dist/_internal/server/jobs/core/onScamReportRejected.js

@@ -15,7 +15,7 @@ export async function handleScamReportRejected(input, ctx) {
         const reporter = await userRepository.findById(reportedBy);
         await sendNotification({
             userId: reportedBy,
-            type: "account_action",
+            type: "scam_report_update",
             priority: "normal",
             title: "Scam report not verified",
             message: `Your report for "${name}" could not be verified with the evidence provided. You may submit a new report with additional evidence.`,

package/dist/_internal/server/jobs/core/onScamReportVerified.js

@@ -15,7 +15,7 @@ export async function handleScamReportVerified(input, ctx) {
         const reporter = await userRepository.findById(reportedBy);
         await sendNotification({
             userId: reportedBy,
-            type: "account_action",
+            type: "scam_report_update",
             priority: "normal",
             title: "Your scam report was verified",
             message: `The report for "${name}" has been verified and published to the Scam Registry. Thank you for helping protect the community.`,

package/dist/_internal/server/jobs/core/onSupportTicketCreate.js

@@ -10,7 +10,7 @@ export async function handleSupportTicketCreate(input, ctx) {
     try {
         await sendNotification({
             userId,
-            type: "account_action",
+            type: "support_ticket_update",
             priority: "normal",
             title: "Support ticket received",
             message: `We received your support request: "${ticket.subject ?? "your ticket"}". We'll get back to you soon.`,

package/dist/_internal/server/jobs/core/onSupportTicketUpdate.js

@@ -35,7 +35,7 @@ export async function handleSupportTicketUpdate(input, ctx) {
     try {
         await sendNotification({
             userId,
-            type: "account_action",
+            type: "support_ticket_update",
             priority: "normal",
             title: msg.title,
             message: msg.body(subject),

package/dist/_internal/server/jobs/core/paymentReviewAutoApprove.js

@@ -76,15 +76,27 @@ export async function runPaymentReviewAutoApprove(ctx) {
             ctx.logger.error("Failed to auto-approve payment proof", err, { orderId: entry.id });
         }
     }
-    await Promise.allSettled(unreviewed.map((entry) => sendNotification({
-        userId: entry.data.userId,
-        type: "payment_review",
-        priority: "normal",
-        title: ORDER_MESSAGES.AUTO_APPROVED_TITLE,
-        message: ORDER_MESSAGES.AUTO_APPROVED_MESSAGE(entry.data.productTitle),
-        relatedId: entry.id,
-        relatedType: "order",
-    })));
+    // Sequential: `payment_review` is email-eligible, so each send reserves a
+    // unit from the single-document daily budget counter. See pendingOrderTimeout.
+    for (const entry of unreviewed) {
+        try {
+            await sendNotification({
+                userId: entry.data.userId,
+                type: "payment_review",
+                priority: "normal",
+                title: ORDER_MESSAGES.AUTO_APPROVED_TITLE,
+                message: ORDER_MESSAGES.AUTO_APPROVED_MESSAGE(entry.data.productTitle),
+                relatedId: entry.id,
+                relatedType: "order",
+            });
+        }
+        catch (err) {
+            void normalizeError(err);
+            ctx.logger.error("Failed to notify buyer of auto-approved payment (non-fatal)", err, {
+                orderId: entry.id,
+            });
+        }
+    }
     ctx.logger.info("Payment review auto-approve sweep complete", {
         scanned: unreviewed.length,
         approved,

package/dist/_internal/server/jobs/core/paymentWindowTimeout.js

@@ -43,16 +43,29 @@ export async function runPaymentWindowTimeout(ctx) {
             });
         }
     }
-    await Promise.allSettled(expired.map((entry) => sendNotification({
-        userId: entry.data.userId,
-        type: "order_cancelled",
-        priority: "normal",
-        title: ORDER_MESSAGES.CANCELLED_PAYMENT_WINDOW_TITLE,
-        message: ORDER_MESSAGES.CANCELLED_PAYMENT_WINDOW_MESSAGE(entry.data.productTitle),
-        relatedId: entry.id,
-        relatedType: "order",
-        orderWhatsappAddonPaid: entry.data.whatsappNotifyAddon === true,
-    })));
+    // Sequential: `order_cancelled` is email-eligible, so each send reserves a
+    // unit from the single-document daily budget counter and a concurrent sweep
+    // would contend on it. See pendingOrderTimeout for the full reasoning.
+    for (const entry of expired) {
+        try {
+            await sendNotification({
+                userId: entry.data.userId,
+                type: "order_cancelled",
+                priority: "normal",
+                title: ORDER_MESSAGES.CANCELLED_PAYMENT_WINDOW_TITLE,
+                message: ORDER_MESSAGES.CANCELLED_PAYMENT_WINDOW_MESSAGE(entry.data.productTitle),
+                relatedId: entry.id,
+                relatedType: "order",
+                orderWhatsappAddonPaid: entry.data.whatsappNotifyAddon === true,
+            });
+        }
+        catch (err) {
+            void normalizeError(err);
+            ctx.logger.error("Failed to notify buyer of expired payment window (non-fatal)", err, {
+                orderId: entry.id,
+            });
+        }
+    }
     ctx.logger.info("Payment window timeout sweep complete", {
         scanned: expired.length,
         restored,

package/dist/_internal/server/jobs/core/pendingOrderTimeout.js

@@ -41,15 +41,41 @@ export async function runPendingOrderTimeout(ctx) {
             });
         }
     }
-    await Promise.allSettled(timedOut.map((entry) => sendNotification({
-        userId: entry.data.userId,
-        type: "order_cancelled",
-        priority: "normal",
-        title: ORDER_MESSAGES.CANCELLED_TITLE,
-        message: ORDER_MESSAGES.CANCELLED_TIMEOUT_MESSAGE(entry.data.productTitle, timeoutHours),
-        relatedId: entry.id,
-        relatedType: "order",
-        orderWhatsappAddonPaid: entry.data.whatsappNotifyAddon === true,
-    })));
+    /*
+     * Sequential, not `Promise.allSettled`.
+     *
+     * 🛑 `order_cancelled` is email-ELIGIBLE, so each of these reserves a unit
+     * from the daily budget — a single Firestore document. Firestore sustains
+     * roughly one write per second on one document, so a concurrent sweep would
+     * contend on it, retry, and slow the job down more than the serial version
+     * it replaced. Awaiting in a loop is the cheap fix; the alternative is
+     * sharding the counter to defend a fan-out nobody needs.
+     *
+     * Safe on latency: this runs in a Firebase Function with a 300s budget, and
+     * the set is bounded by however many orders timed out in one window.
+     *
+     * Failures stay non-fatal per order — a notification that will not send must
+     * not stop the remaining cancellations being announced.
+     */
+    for (const entry of timedOut) {
+        try {
+            await sendNotification({
+                userId: entry.data.userId,
+                type: "order_cancelled",
+                priority: "normal",
+                title: ORDER_MESSAGES.CANCELLED_TITLE,
+                message: ORDER_MESSAGES.CANCELLED_TIMEOUT_MESSAGE(entry.data.productTitle, timeoutHours),
+                relatedId: entry.id,
+                relatedType: "order",
+                orderWhatsappAddonPaid: entry.data.whatsappNotifyAddon === true,
+            });
+        }
+        catch (err) {
+            void normalizeError(err);
+            ctx.logger.error("Failed to notify buyer of timed-out order (non-fatal)", err, {
+                orderId: entry.id,
+            });
+        }
+    }
     ctx.logger.info("Pending order timeout complete", { cancelled: timedOut.length, restored });
 }

package/dist/_internal/server/jobs/core/whatsappNotify.js

@@ -21,13 +21,55 @@ import { normalizeError } from "../../../../errors/normalize";
 import { notificationRepository } from "../../../../features/admin/repository/notification.repository";
 import { sendWhatsAppTemplateMessage, sendWhatsAppBusinessMessage, } from "../../../../features/whatsapp-bot/helpers/whatsapp";
 import { isChannelHealthy, recordChannelOutcome } from "../../notifications/channel-health";
+import { guardSend, logSuppressedSend } from "../../notifications/send-guard";
 const MAX_ATTEMPTS = 3;
 const RETRY_DELAY_MS = 1500;
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
 export async function runWhatsAppNotify(payload, ctx) {
-    const { toPhone, title, message, templateName, templateLanguage, notificationId, phoneNumberId, accessToken } = payload;
+    const { toPhone, title, message, type, templateName, templateLanguage, notificationId, phoneNumberId, accessToken } = payload;
+    /*
+     * The messaging guard, applied HERE rather than inside
+     * `sendWhatsAppBusinessMessage` itself.
+     *
+     * 🛑 That placement is deliberate and must not be "improved" by pushing a
+     * required guard parameter down into the sender. `features/whatsapp-bot/helpers/whatsapp.ts`
+     * is re-exported from `appkit/src/index.ts` (via `isAdminNumber`), and
+     * `guardSend` reaches `firebase-admin` through the settings and budget
+     * repositories. A static import of it from that file would put
+     * `firebase-admin` in the main entry's import graph, which is precisely the
+     * Turbopack client-bundle trap in Root Cause #6/#24 — it builds fine locally
+     * on webpack and fails every page in production.
+     *
+     * So the senders stay pure and each of the three real call sites guards
+     * itself; `scripts/audit-unguarded-send.mjs` enforces that a file calling a
+     * WhatsApp sender also calls `guardSend`.
+     *
+     * Note this job is only ever reached for an email/WhatsApp-ELIGIBLE type —
+     * `sendNotification` returns before enqueuing otherwise — so this is the
+     * ceiling and kill-switch check, not the type check.
+     */
+    const guard = {
+        channel: "whatsapp",
+        feature: type,
+        audience: "user",
+    };
+    const decision = await guardSend(guard);
+    if (!decision.allow) {
+        logSuppressedSend(guard, decision);
+        await notificationRepository
+            .update(notificationId, { whatsappStatus: "skipped" })
+            .catch((err) => {
+            void normalizeError(err);
+        });
+        return {
+            summary: { total: 1, succeeded: 0, skipped: 1, failed: 0 },
+            succeeded: [],
+            skipped: [notificationId],
+            failed: [],
+        };
+    }
     if (!(await isChannelHealthy("whatsapp"))) {
         ctx.logger.warn("whatsappNotify: WhatsApp channel circuit is open — skipping send", { notificationId });
         await notificationRepository

package/dist/_internal/server/jobs/handlers/onCatalogueSubmittedForApproval.js

@@ -6,6 +6,20 @@ export const onCatalogueSubmittedForApprovalHandler = async (event, ctx) => {
         return;
     const itemId = event.params.itemId ?? event.after?.id;
     const title = event.after?.title ?? "Untitled item";
+    /*
+     * No `as never` here any more, and the cast is worth a note because it was
+     * load-bearing in the wrong direction.
+     *
+     * `BaseRepository.create` takes `Omit<T, "id" | "createdAt" | "updatedAt">`
+     * and stamps its own timestamps. This call passed `createdAt: ctx.now`,
+     * which is an excess property — so TS rejected it, someone reached for
+     * `as never`, and that silenced the type check on EVERY OTHER FIELD of the
+     * payload rather than just the offending one. The `createdAt` was being
+     * discarded at runtime regardless.
+     *
+     * Dropping the field is the whole fix. Five more call sites now follow this
+     * shape; none of them needs a cast either.
+     */
     await adminNotificationsRepository.create({
         category: "moderation",
         title: "Catalogue listing pending approval",
@@ -15,6 +29,5 @@ export const onCatalogueSubmittedForApprovalHandler = async (event, ctx) => {
         entityType: "catalogueItem",
         entityId: itemId,
         audienceUserIds: [],
-        createdAt: ctx.now,
     });
 };

package/dist/_internal/server/notifications/send-guard.d.ts

@@ -0,0 +1,42 @@
+/**
+ * May this message go out?
+ *
+ * One decision function, called from the only two places that know both WHO a
+ * message is for and WHY: `sendEmail()` and `sendNotification()`'s channel
+ * branches.
+ *
+ * ## Why not inside the Resend provider
+ *
+ * That would catch 100% of sends, which sounds like the stronger design and is
+ * not. The transport sees `to`, `subject` and `html` — it has no notion of
+ * feature or audience, so it could not tell a customer marketing blast from the
+ * daily digest, and every kill-switch decision would degrade to all-or-nothing.
+ * Worse, a counter there plus a counter here would double-charge the same
+ * message.
+ *
+ * The guarantee that nothing bypasses this is STRUCTURAL instead: the guard
+ * argument is REQUIRED on `sendEmail` and on both WhatsApp senders, so an
+ * unguarded send does not typecheck, and `scripts/audit-unguarded-send.mjs`
+ * fails the build on a raw `createResendProvider().send()`. Make the wrong
+ * thing unrepresentable rather than adding a second layer of defence that has
+ * to be kept in sync with the first (CLAUDE.md Rule #22).
+ */
+import { type SendDecision, type SendGuardContext } from "../../shared/features/messaging/config";
+/**
+ * Evaluate the guard. Never throws — a guard that can throw turns a config
+ * problem into a failed checkout.
+ *
+ * Order is deliberate and is cost-ordered: the two free checks run before the
+ * Firestore read, and the Firestore WRITE runs last, so a message that was
+ * never going out costs nothing to refuse.
+ */
+export declare function guardSend(ctx: SendGuardContext): Promise<SendDecision>;
+/**
+ * Record a suppression so "why did nobody get that" has an answer.
+ *
+ * Separate from `guardSend` so the decision function stays pure-ish and
+ * callable from a dry run. Deliberately `info`: a suppression is the system
+ * working, not failing — the ceiling case above already logs at `error` on its
+ * own.
+ */
+export declare function logSuppressedSend(ctx: SendGuardContext, decision: SendDecision): void;

package/dist/_internal/server/notifications/send-guard.js

@@ -0,0 +1,142 @@
+/**
+ * May this message go out?
+ *
+ * One decision function, called from the only two places that know both WHO a
+ * message is for and WHY: `sendEmail()` and `sendNotification()`'s channel
+ * branches.
+ *
+ * ## Why not inside the Resend provider
+ *
+ * That would catch 100% of sends, which sounds like the stronger design and is
+ * not. The transport sees `to`, `subject` and `html` — it has no notion of
+ * feature or audience, so it could not tell a customer marketing blast from the
+ * daily digest, and every kill-switch decision would degrade to all-or-nothing.
+ * Worse, a counter there plus a counter here would double-charge the same
+ * message.
+ *
+ * The guarantee that nothing bypasses this is STRUCTURAL instead: the guard
+ * argument is REQUIRED on `sendEmail` and on both WhatsApp senders, so an
+ * unguarded send does not typecheck, and `scripts/audit-unguarded-send.mjs`
+ * fails the build on a raw `createResendProvider().send()`. Make the wrong
+ * thing unrepresentable rather than adding a second layer of defence that has
+ * to be kept in sync with the first (CLAUDE.md Rule #22).
+ */
+import { normalizeError } from "../../../errors/normalize";
+import { serverLogger } from "../../../monitoring";
+import { siteSettingsRepository } from "../../../features/admin/repository/site-settings.repository";
+import { messageBudgetRepository } from "../../../features/messaging/repository/message-budget.repository";
+import { MESSAGE_BUDGET_DEFAULTS, isEnvKillSwitchOn, } from "../../shared/features/messaging/config";
+/**
+ * Evaluate the guard. Never throws — a guard that can throw turns a config
+ * problem into a failed checkout.
+ *
+ * Order is deliberate and is cost-ordered: the two free checks run before the
+ * Firestore read, and the Firestore WRITE runs last, so a message that was
+ * never going out costs nothing to refuse.
+ */
+export async function guardSend(ctx) {
+    // 1. Hard kill. No I/O, so it still works when Firestore is the problem.
+    if (isEnvKillSwitchOn() && !ctx.transactional) {
+        return {
+            allow: false,
+            reason: "env_disabled",
+            detail: `EMAIL_DISABLED is set; suppressed ${ctx.channel}/${ctx.feature}`,
+        };
+    }
+    let settings = null;
+    try {
+        settings = await siteSettingsRepository.getSingleton();
+    }
+    catch (err) {
+        void normalizeError(err);
+        /*
+         * Fail OPEN on an unreadable settings document, and only here.
+         *
+         * The alternative — refuse everything — means one Firestore blip silences
+         * order confirmations and checkout OTPs site-wide. The ceiling below still
+         * applies with its default, so failing open cannot become unbounded; it
+         * just means the admin toggle is briefly ignored, which is the smaller of
+         * the two harms.
+         */
+        serverLogger.warn("guardSend: siteSettings unreadable — falling back to defaults", {
+            channel: ctx.channel,
+            feature: ctx.feature,
+        });
+    }
+    const messaging = settings?.messaging;
+    // 2. Admin kill switch. USER-facing only — staff mail is how an operator
+    //    finds out anything is wrong, so it is never suppressed by this.
+    if (ctx.audience === "user" && !ctx.transactional) {
+        const channelEnabled = ctx.channel === "email"
+            ? (messaging?.emailEnabled ?? MESSAGE_BUDGET_DEFAULTS.emailEnabled)
+            : ctx.channel === "whatsapp"
+                ? (messaging?.whatsappEnabled ?? MESSAGE_BUDGET_DEFAULTS.whatsappEnabled)
+                : false; // sms has no sender; if one appears it starts disabled.
+        if (!channelEnabled) {
+            return {
+                allow: false,
+                reason: "admin_disabled",
+                detail: `${ctx.channel} is disabled for user-facing mail in Site Settings`,
+            };
+        }
+    }
+    // 3. The daily ceiling. Applies to EVERYTHING, including staff and
+    //    transactional mail — the ceiling exists to keep the provider from
+    //    rejecting, and a provider that is rejecting rejects those too.
+    const ceiling = messaging?.dailyCeiling?.[ctx.channel] ??
+        MESSAGE_BUDGET_DEFAULTS.dailyCeiling[ctx.channel];
+    try {
+        const { allowed, count } = await messageBudgetRepository.reserveSend(ctx.channel, ceiling);
+        if (!allowed) {
+            // `error`, not `warn`: hitting the ceiling means real messages are being
+            // dropped, and it should be visible in the admin error list rather than
+            // buried among ordinary warnings.
+            serverLogger.error("guardSend: daily ceiling reached — message suppressed", {
+                channel: ctx.channel,
+                feature: ctx.feature,
+                audience: ctx.audience,
+                transactional: ctx.transactional === true,
+                count,
+                ceiling,
+            });
+            return {
+                allow: false,
+                reason: "daily_ceiling",
+                detail: `${ctx.channel} daily ceiling of ${ceiling} reached`,
+            };
+        }
+    }
+    catch (err) {
+        void normalizeError(err);
+        /*
+         * Fail OPEN on a counter that will not write, for the same reason as the
+         * settings read above — but note the asymmetry: this branch cannot be
+         * reached without Firestore being broadly unavailable, in which case very
+         * little is being sent anyway.
+         */
+        serverLogger.warn("guardSend: budget reservation failed — allowing send", {
+            channel: ctx.channel,
+            feature: ctx.feature,
+        });
+    }
+    return { allow: true };
+}
+/**
+ * Record a suppression so "why did nobody get that" has an answer.
+ *
+ * Separate from `guardSend` so the decision function stays pure-ish and
+ * callable from a dry run. Deliberately `info`: a suppression is the system
+ * working, not failing — the ceiling case above already logs at `error` on its
+ * own.
+ */
+export function logSuppressedSend(ctx, decision) {
+    if (decision.allow)
+        return;
+    serverLogger.info("send suppressed", {
+        channel: ctx.channel,
+        feature: ctx.feature,
+        audience: ctx.audience,
+        reason: decision.reason,
+        detail: decision.detail,
+    });
+}