@mohasinac/appkit 4.35.1 → 4.35.3

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

package/dist/_internal/shared/features/messaging/config.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared vocabulary for "may this message go out, and does the budget allow
+ * it" — the types both the server guard and the settings schema speak.
+ *
+ * Lives in `_internal/shared/` because the channel/audience unions are read on
+ * both sides: the guard enforces them server-side, the admin settings view
+ * renders them.
+ */
+/**
+ * A metered outbound channel.
+ *
+ * `sms` is declared and has no sender. That is deliberate rather than
+ * aspirational: `notificationChannels.sms` has existed in the settings schema
+ * (and been seeded `enabled: true`) for a long time while no code has ever
+ * read it, so anyone adding an SMS provider will reach for this union first
+ * and find the budget already covers them. A channel that is born capped
+ * cannot repeat what email did.
+ */
+export type MessageChannel = "email" | "whatsapp" | "sms";
+/**
+ * Who the message is FOR — which is what the kill switch keys on.
+ *
+ * `user` is a buyer or seller receiving something about their own activity.
+ * `staff` is the operators of the site receiving something about the site.
+ *
+ * The kill switch suppresses `user` only. Turning off customer email must not
+ * also blind the people running the shop: the daily digest is how a support
+ * message or a stuck payment proof gets noticed at all, and silencing it is
+ * how an outage becomes a week-long outage.
+ */
+export type MessageAudience = "user" | "staff";
+/**
+ * What a caller must state before a message can leave the building.
+ *
+ * Every field is required except `transactional`, and that asymmetry is the
+ * point — a sender that cannot say who this is for and why has not thought
+ * about it, and an optional field defaults to whatever is least safe.
+ */
+export interface SendGuardContext {
+    channel: MessageChannel;
+    /**
+     * Stable identifier for WHAT is being sent — a notification type
+     * (`order_shipped`), or a named non-notification flow (`daily_digest`,
+     * `checkout_otp`, `payout_summary`).
+     *
+     * Recorded on every allow and deny, so "what ate the quota today" is a
+     * question with an answer.
+     */
+    feature: string;
+    audience: MessageAudience;
+    /**
+     * The message is part of a flow the user is actively in, and suppressing it
+     * breaks that flow rather than merely quietening it.
+     *
+     * Exempt from the KILL SWITCH ONLY — the daily ceiling still applies, since
+     * the ceiling exists to stop the provider rejecting everything, and a
+     * transactional mail that would be rejected anyway is not worth pretending
+     * about.
+     *
+     * Only two things qualify today and the bar should stay this high:
+     *   · the high-value checkout OTP — the buyer cannot complete an order above
+     *     the threshold without the code;
+     *   · the order confirmation — the buyer's receipt for money already taken.
+     */
+    transactional?: boolean;
+}
+export type SendDecision = {
+    allow: true;
+} | {
+    allow: false;
+    /** Machine-readable, for logs and the suppression record. */
+    reason: "type_ineligible" | "env_disabled" | "admin_disabled" | "daily_ceiling";
+    /** One line, for the log. Never shown to an end user. */
+    detail: string;
+};
+/**
+ * Defaults, mirrored into `DEFAULT_SITE_SETTINGS_DATA.messaging`.
+ *
+ * 🛑 `emailEnabled` and `whatsappEnabled` default to FALSE. An install that
+ * has not made a decision should be quiet, not loud — the opposite default is
+ * how a fresh deploy mails real people from a half-configured site.
+ */
+export declare const MESSAGE_BUDGET_DEFAULTS: {
+    readonly emailEnabled: false;
+    readonly whatsappEnabled: false;
+    readonly dailyCeiling: {
+        /**
+         * Resend's free tier is 100/day. 80 is not timidity — the counter is
+         * reserve-then-send and a burst can race slightly past the check, and
+         * Firebase-side auth mail (password resets, verification) draws on a
+         * different quota but the same inbox reputation. Twenty messages of
+         * headroom is what stops "at the limit" from becoming "over it".
+         */
+        readonly email: 80;
+        /** Meta's pricing is per-conversation, not per-message; this is a sanity bound, not a tier limit. */
+        readonly whatsapp: 200;
+        /** No sender exists yet. Present so one cannot ship uncapped. */
+        readonly sms: 50;
+    };
+};
+/**
+ * Hard kill, checked before any Firestore read so it works even when Firestore
+ * is the thing that is unhappy.
+ *
+ * Any of `1` / `true` / `yes` counts, case-insensitively — an operator setting
+ * this at 3am should not have to remember which spelling the parser wanted.
+ */
+export declare function isEnvKillSwitchOn(): boolean;

package/dist/_internal/shared/features/messaging/config.js

@@ -0,0 +1,44 @@
+/**
+ * Shared vocabulary for "may this message go out, and does the budget allow
+ * it" — the types both the server guard and the settings schema speak.
+ *
+ * Lives in `_internal/shared/` because the channel/audience unions are read on
+ * both sides: the guard enforces them server-side, the admin settings view
+ * renders them.
+ */
+/**
+ * Defaults, mirrored into `DEFAULT_SITE_SETTINGS_DATA.messaging`.
+ *
+ * 🛑 `emailEnabled` and `whatsappEnabled` default to FALSE. An install that
+ * has not made a decision should be quiet, not loud — the opposite default is
+ * how a fresh deploy mails real people from a half-configured site.
+ */
+export const MESSAGE_BUDGET_DEFAULTS = {
+    emailEnabled: false,
+    whatsappEnabled: false,
+    dailyCeiling: {
+        /**
+         * Resend's free tier is 100/day. 80 is not timidity — the counter is
+         * reserve-then-send and a burst can race slightly past the check, and
+         * Firebase-side auth mail (password resets, verification) draws on a
+         * different quota but the same inbox reputation. Twenty messages of
+         * headroom is what stops "at the limit" from becoming "over it".
+         */
+        email: 80,
+        /** Meta's pricing is per-conversation, not per-message; this is a sanity bound, not a tier limit. */
+        whatsapp: 200,
+        /** No sender exists yet. Present so one cannot ship uncapped. */
+        sms: 50,
+    },
+};
+/**
+ * Hard kill, checked before any Firestore read so it works even when Firestore
+ * is the thing that is unhappy.
+ *
+ * Any of `1` / `true` / `yes` counts, case-insensitively — an operator setting
+ * this at 3am should not have to remember which spelling the parser wanted.
+ */
+export function isEnvKillSwitchOn() {
+    const raw = process.env.EMAIL_DISABLED?.trim().toLowerCase() ?? "";
+    return raw === "1" || raw === "true" || raw === "yes";
+}

package/dist/_internal/shared/features/notifications/action-url.js

@@ -155,4 +155,13 @@ export const TYPE_AUDIENCE = {
     account_action: "buyer",
     system: "buyer",
     promotion: "buyer",
+    /*
+     * Both are "buyer" because that is where the RECIPIENT reads them — the
+     * ticket's owner at `/user/support`, the reporter at the scam registry.
+     * Staff do not receive either of these as notifications any more: the
+     * per-employee fan-out was replaced by a single `adminNotifications` row
+     * plus a daily digest section, so there is no staff audience to express.
+     */
+    support_ticket_update: "buyer",
+    scam_report_update: "buyer",
 };

package/dist/_internal/shared/features/notifications/email-eligibility.d.ts

@@ -0,0 +1,66 @@
+/**
+ * May this notification type be EMAILED at all?
+ *
+ * ## Why this is code and not the admin allow-list
+ *
+ * `siteSettings.notificationChannels.email.types?: NotificationType[]` already
+ * exists and is checked inside `sendNotification`. Setting it in the seed would
+ * have been one line — and the wrong one, three times over:
+ *
+ *   · it is a plain array, so a NEW notification type is silently
+ *     email-enabled. A `Record<Union, boolean>` makes it a compile error
+ *     instead (Root Cause #61 — a Record is compile-safe, an array is not);
+ *   · its empty case means "all types allowed", so an admin clearing the field
+ *     reopens every one of them;
+ *   · it is data, so a reseed quietly restores the old behaviour.
+ *
+ * So the two layers compose in one direction only: **this map decides what is
+ * eligible, the admin list may narrow it further, and neither can widen past
+ * here.**
+ *
+ * ## What this is actually protecting
+ *
+ * Resend's free tier is 100 emails/day, and three call sites could exhaust it
+ * on their own:
+ *
+ *   · `auctionSettlement` sends `bid_lost` to every losing bidder, up to 50 in
+ *     PARALLEL per auction, and settles all expired auctions concurrently —
+ *     two auctions is the whole day;
+ *   · `onScamReportCreate` fanned out one send per employee, up to 100;
+ *   · `bid_outbid` is one email per bid per bidder on a live auction.
+ *
+ * The gate runs FIRST in `sendNotification`'s channel conjunctions — before the
+ * settings read, before the budget counter — so those 50 sends now exit with
+ * zero Firestore operations. That ordering is load-bearing: it is what lets the
+ * daily counter stay a single unsharded document.
+ *
+ * ## Nothing is lost by dropping a type from here
+ *
+ * `sendNotification` writes the in-app notification BEFORE any channel
+ * decision, so an ineligible type still fills the bell. Only the emailed copy
+ * goes away.
+ */
+import type { NotificationType } from "../../../../features/admin/schemas/firestore";
+/**
+ * `true` = may email (subject to the admin allow-list, the kill switch, the
+ * user's own preference and the daily ceiling). `false` = in-app bell only.
+ *
+ * Typed on the union so a new notification type cannot compile without an
+ * answer to "is this worth an email?". Do not reach for a default — the whole
+ * value of this map is that the question gets asked once, deliberately, per
+ * type.
+ */
+export declare const EMAIL_ELIGIBLE_TYPES: Record<NotificationType, boolean>;
+/**
+ * Prefer this over indexing the map directly — the lookup is `boolean`, and a
+ * bare `EMAIL_ELIGIBLE_TYPES[type]` inside a long `&&` chain reads as a flag
+ * rather than as a decision.
+ */
+export declare function isEmailEligible(type: NotificationType): boolean;
+/**
+ * For the admin UI, which renders an ineligible type as a DISABLED row rather
+ * than hiding it. Hiding would leave an admin wondering why `bid_outbid` is
+ * absent from a list that claims to cover every type; a disabled row with a
+ * reason answers the question in place.
+ */
+export declare const EMAIL_INELIGIBLE_TYPE_LIST: readonly NotificationType[];

package/dist/_internal/shared/features/notifications/email-eligibility.js

@@ -0,0 +1,129 @@
+/**
+ * May this notification type be EMAILED at all?
+ *
+ * ## Why this is code and not the admin allow-list
+ *
+ * `siteSettings.notificationChannels.email.types?: NotificationType[]` already
+ * exists and is checked inside `sendNotification`. Setting it in the seed would
+ * have been one line — and the wrong one, three times over:
+ *
+ *   · it is a plain array, so a NEW notification type is silently
+ *     email-enabled. A `Record<Union, boolean>` makes it a compile error
+ *     instead (Root Cause #61 — a Record is compile-safe, an array is not);
+ *   · its empty case means "all types allowed", so an admin clearing the field
+ *     reopens every one of them;
+ *   · it is data, so a reseed quietly restores the old behaviour.
+ *
+ * So the two layers compose in one direction only: **this map decides what is
+ * eligible, the admin list may narrow it further, and neither can widen past
+ * here.**
+ *
+ * ## What this is actually protecting
+ *
+ * Resend's free tier is 100 emails/day, and three call sites could exhaust it
+ * on their own:
+ *
+ *   · `auctionSettlement` sends `bid_lost` to every losing bidder, up to 50 in
+ *     PARALLEL per auction, and settles all expired auctions concurrently —
+ *     two auctions is the whole day;
+ *   · `onScamReportCreate` fanned out one send per employee, up to 100;
+ *   · `bid_outbid` is one email per bid per bidder on a live auction.
+ *
+ * The gate runs FIRST in `sendNotification`'s channel conjunctions — before the
+ * settings read, before the budget counter — so those 50 sends now exit with
+ * zero Firestore operations. That ordering is load-bearing: it is what lets the
+ * daily counter stay a single unsharded document.
+ *
+ * ## Nothing is lost by dropping a type from here
+ *
+ * `sendNotification` writes the in-app notification BEFORE any channel
+ * decision, so an ineligible type still fills the bell. Only the emailed copy
+ * goes away.
+ */
+/**
+ * `true` = may email (subject to the admin allow-list, the kill switch, the
+ * user's own preference and the daily ceiling). `false` = in-app bell only.
+ *
+ * Typed on the union so a new notification type cannot compile without an
+ * answer to "is this worth an email?". Do not reach for a default — the whole
+ * value of this map is that the question gets asked once, deliberately, per
+ * type.
+ */
+export const EMAIL_ELIGIBLE_TYPES = {
+    // ── Money. The buyer is owed something, owes something, or just paid. ──────
+    order_placed: true,
+    order_confirmed: true,
+    order_shipped: true,
+    order_delivered: true,
+    order_cancelled: true,
+    refund_initiated: true,
+    payment_review: true,
+    emi_installment_due_soon: true,
+    emi_installment_overdue: true,
+    // ── Negotiation. Each one is a move the other party must respond to, and ──
+    // ── every one of them expires if they do not.                            ──
+    offer_received: true,
+    offer_responded: true,
+    offer_expired: true,
+    offer_counter_accepted: true,
+    // Won, and on a clock: the winner forfeits the lot if they miss the payment
+    // deadline. This is the one auction type that survives, and it survives
+    // BECAUSE of the deadline — not because winning is nice to hear about.
+    bid_won: true,
+    // Someone must claim this, and the claim window closes.
+    prize_won: true,
+    // Access to the account itself — a ban or an unban. After the 2026-09 split
+    // this means ONLY that; support tickets and scam reports moved to their own
+    // types precisely so this one could keep emailing. A banned user has to be
+    // told outside the app, because the app is what they just lost.
+    account_action: true,
+    // Signup and genuine one-off announcements. Low volume by nature.
+    welcome: true,
+    system: true,
+    // ── Bell only. ────────────────────────────────────────────────────────────
+    // The three auction fan-outs. `bid_lost` is up to 50 parallel sends per
+    // settled auction; `bid_outbid` is one per bid per bidder; `bid_placed`
+    // pings the seller on every single bid. All three are visible on the auction
+    // page and in the bell, and none of them is a deadline.
+    bid_lost: false,
+    bid_outbid: false,
+    bid_placed: false,
+    auction_ended: false,
+    // Marketing. The likeliest way to get the sending domain flagged, and the
+    // first thing a recipient marks as spam — which damages deliverability for
+    // the transactional mail above.
+    promotion: false,
+    product_available: false,
+    // Nothing for the user to do; the record is on the site when they next look.
+    review_approved: false,
+    review_replied: false,
+    // Housekeeping nags. `catalogue_images_stale` loops one send per stale item,
+    // so it is a quiet fan-out of its own.
+    catalogue_images_stale: false,
+    prize_reveal_expired: false,
+    // The conversation lives in the UI. Routine ticket back-and-forth costs
+    // nothing; a staff replier who genuinely needs one to land in an inbox ticks
+    // "also email the user", which sends `eligibilityOverride: "staff_requested"`
+    // for that one reply. The user side has no such tick — a user replying to
+    // their own ticket never triggers mail.
+    support_ticket_update: false,
+    // The reporter reads the outcome on the site; the admin side rides the daily
+    // digest. This was the second 100-way fan-out — `onScamReportCreate` sent one
+    // notification per employee, up to 100, for every report filed.
+    scam_report_update: false,
+};
+/**
+ * Prefer this over indexing the map directly — the lookup is `boolean`, and a
+ * bare `EMAIL_ELIGIBLE_TYPES[type]` inside a long `&&` chain reads as a flag
+ * rather than as a decision.
+ */
+export function isEmailEligible(type) {
+    return EMAIL_ELIGIBLE_TYPES[type] === true;
+}
+/**
+ * For the admin UI, which renders an ineligible type as a DISABLED row rather
+ * than hiding it. Hiding would leave an admin wondering why `bid_outbid` is
+ * absent from a list that claims to cover every type; a disabled row with a
+ * reason answers the question in place.
+ */
+export const EMAIL_INELIGIBLE_TYPE_LIST = Object.freeze(Object.keys(EMAIL_ELIGIBLE_TYPES).filter((t) => EMAIL_ELIGIBLE_TYPES[t] === false));