@mohasinac/appkit 4.63.3 → 4.63.5

package/dist/features/checkout/actions/checkout-value-otp-actions.js

@@ -9,12 +9,17 @@
 import { timingSafeEqual } from "crypto";
 import { ValidationError } from "../../../errors/index.js";
 import { normalizeError } from "../../../errors/normalize.js";
+import { safeRead } from "../../../errors/safe-read.js";
 import { serverLogger } from "../../../monitoring/index.js";
 import { sendEmail } from "../../contact/email.js";
 import { getAdminDb } from "../../../providers/db-firebase/index.js";
 import { resolveDate } from "../../../utils/index.js";
+import { addressesRepository } from "../../addresses/repository/addresses.repository.js";
+import { siteSettingsRepository } from "../../admin/repository/site-settings.repository.js";
+import { sendWhatsAppBusinessMessage } from "../../whatsapp-bot/helpers/whatsapp.js";
 import { isChannelHealthy, withChannelRetry } from "../../../_internal/server/notifications/channel-health.js";
-import { CHECKOUT_VALUE_OTP_EXPIRY_MS, CHECKOUT_VALUE_OTP_MAX_ATTEMPTS, hashOtp, generateOtpCode, checkoutValueOtpRef, enforceCheckoutValueOtpRateLimit, } from "../../auth/checkout-value-otp.js";
+import { guardSend, logSuppressedSend } from "../../../_internal/server/notifications/send-guard.js";
+import { CHECKOUT_VALUE_OTP_EXPIRY_MS, CHECKOUT_VALUE_OTP_MAX_ATTEMPTS, hashOtp, generateOtpCode, checkoutValueOtpRef, enforceCheckoutValueOtpRateLimit, buildCheckoutValueOtpMessage, } from "../../auth/checkout-value-otp.js";
 function maskEmail(userEmail) {
     const [local, domain] = userEmail.split("@");
     return domain
@@ -22,7 +27,10 @@ function maskEmail(userEmail) {
         : "***";
 }
 /**
- * Sends a checkout-value OTP by email.
+ * Sends a checkout-value OTP either by email (default) or WhatsApp
+ * (opt-in — the buyer must explicitly choose it in the UI). WhatsApp phone
+ * is always resolved server-side from the selected shipping address —
+ * never trust a client-supplied phone number.
  *
  * If the chosen channel (and, for email, its skip-worthy fallback) is
  * currently circuit-broken or unconfigured, the OTP gate is treated as
@@ -37,6 +45,84 @@ export async function sendCheckoutValueOtp(userId, userEmail, channel = "email",
     const codeHash = hashOtp(code);
     const expiresAt = new Date(Date.now() + CHECKOUT_VALUE_OTP_EXPIRY_MS);
     const siteName = process.env.NEXT_PUBLIC_SITE_NAME || "LetItRip";
+    if (channel === "whatsapp") {
+        if (!addressId) {
+            throw new ValidationError("Select a delivery address before sending the code via WhatsApp.");
+        }
+        // A failed settings read makes the WhatsApp channel look deliberately
+        // switched off ("send the code by email instead") — a defensible fallback,
+        // but one an operator has to be able to see, since it is indistinguishable
+        // from an admin having disabled it.
+        const settings = await safeRead(() => siteSettingsRepository.getSingleton(), {
+            route: "checkout/value-otp",
+            key: "checkoutValueOtp.siteSettings",
+            fallback: null,
+        });
+        const creds = settings?.credentials ?? {};
+        const whatsappOtpEnabled = settings?.notificationChannels?.whatsapp?.otpEnabled === true;
+        const phoneNumberId = creds.whatsappPhoneNumberId?.trim() ?? "";
+        const accessToken = creds.whatsappCloudApiToken?.trim() ?? "";
+        const credsReady = phoneNumberId && accessToken && !phoneNumberId.includes("PLACEHOLDER") && !accessToken.includes("PLACEHOLDER");
+        if (!whatsappOtpEnabled || !credsReady) {
+            throw new ValidationError("WhatsApp verification isn't available right now — send the code by email instead.");
+        }
+        const address = await addressesRepository.findById(addressId);
+        /*
+       * REVEALED: this phone receives the high-value checkout OTP, so it has to
+       * be the real number. `addressesRepository` is ciphertext-by-default, and
+       * `.trim()` on the stored value is what the nominal brand caught — the
+       * old intersection form let `Encrypted<string>` call string methods.
+       */
+        const addressPlain = address ? addressesRepository.revealAddress(address) : null;
+        const phone = addressPlain?.phone?.trim();
+        if (!phone) {
+            throw new ValidationError("The selected address has no phone number on file — send the code by email instead.");
+        }
+        if (!(await isChannelHealthy("whatsapp"))) {
+            serverLogger.warn("sendCheckoutValueOtp: WhatsApp channel unhealthy — skipping OTP gate", { uid: userId, channel });
+            return { skipped: true };
+        }
+        await checkoutValueOtpRef(db, userId).set({
+            codeHash,
+            expiresAt,
+            attempts: 0,
+            verified: false,
+            createdAt: new Date(),
+        });
+        const message = buildCheckoutValueOtpMessage(code, siteName);
+        // Same guard as the email branch below, same reasoning: transactional, so
+        // the kill switch does not apply (the buyer cannot check out without the
+        // code), but the daily ceiling does.
+        const waGuard = {
+            channel: "whatsapp",
+            feature: "checkout_value_otp",
+            audience: "user",
+            transactional: true,
+        };
+        const waDecision = await guardSend(waGuard);
+        if (!waDecision.allow) {
+            logSuppressedSend(waGuard, waDecision);
+            throw new ValidationError("We couldn't send the verification code via WhatsApp — please try again, or send it by email instead.");
+        }
+        try {
+            const sent = await withChannelRetry("whatsapp", async () => {
+                const ok = await sendWhatsAppBusinessMessage({ toPhone: phone, message, phoneNumberId, accessToken });
+                if (!ok)
+                    throw new Error("WhatsApp Cloud API returned a non-OK response");
+                return ok;
+            });
+            if (!sent)
+                throw new Error("WhatsApp send failed");
+        }
+        catch (err) {
+            void normalizeError(err);
+            serverLogger.error("Failed to send checkout value OTP via WhatsApp", { uid: userId, err });
+            throw new ValidationError("We couldn't send the verification code via WhatsApp — please try again, or send it by email instead.");
+        }
+        const maskedPhone = phone.length > 4 ? `${"*".repeat(phone.length - 4)}${phone.slice(-4)}` : "***";
+        serverLogger.info(`Checkout value OTP sent via WhatsApp: uid=${userId}`);
+        return { maskedPhone };
+    }
     if (!(await isChannelHealthy("email"))) {
         serverLogger.warn("sendCheckoutValueOtp: email channel unhealthy — skipping OTP gate", { uid: userId, channel });
         return { skipped: true };

package/dist/features/events/components/AdminEventEditorView.js

@@ -5,13 +5,15 @@ import { useApiMutation } from "@mohasinac/appkit/client";
 import React, { useEffect } from "react";
 import { useTranslations } from "next-intl";
 import { useQuery } from "@tanstack/react-query";
-import { Alert, Button, Div, Grid, Heading, Input, Label, RichTextEditor, Row, Select, Stack, StackedViewShell, TagInput, Text, Textarea, Toggle, } from "../../../ui/index.js";
+import { Alert, Button, Div, Grid, Heading, Input, Label, RichTextEditor, Row, Select, Span, Stack, StackedViewShell, TagInput, Text, Textarea, Toggle, } from "../../../ui/index.js";
 import { FormShellContext, useFormShellState, applyZodIssues, FormErrorSummary } from "../../../ui/forms/index.js";
 import { apiClient } from "../../../http/index.js";
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
 import { ACTIONS } from "../../../_internal/shared/actions/action-registry.js";
 import { toUserMessage } from "../../../errors/error-display-map.js";
 import { ALL_EVENT_TYPES, EVENT_TYPE_LABELS } from "../types/index.js";
+import { rafflePrizeCouponIdsOf } from "../schemas/firestore.js";
+import { ATTACHED_COUPON_MAX } from "../../promotions/constants/attached-coupons.js";
 import { SectionForm, useSectionFormNav } from "../../shell/index.js";
 import { eventDraftSchema } from "../schemas/event-form.js";
 import { ProductInlineSelect } from "../../seller/components/ProductInlineSelect.js";
@@ -136,6 +138,7 @@ const DEFAULT_DRAFT = {
     createdBy: "",
     allowGuestParticipation: false,
     isPinned: false,
+    couponIds: [],
     discountPercent: "10",
     saleBannerText: "",
     couponId: "",
@@ -158,7 +161,7 @@ const DEFAULT_DRAFT = {
     raffleType: "open_raffle",
     raffleTopN: "10",
     rafflePrize: "",
-    rafflePrizeCouponId: "",
+    rafflePrizeCouponIds: [],
     rafflePrizeProductIds: [],
     spinPrizes: [],
     spinMaxPerUser: "1",
@@ -190,8 +193,27 @@ function buildEventRaffleFields(draft) {
         fields.raffleTopN = Number(draft.raffleTopN);
     if (draft.rafflePrize)
         fields.rafflePrize = draft.rafflePrize;
-    if (draft.rafflePrizeCouponId)
-        fields.rafflePrizeCouponId = draft.rafflePrizeCouponId;
+    /*
+     * 🛑 Writes the ARRAY and never the deprecated `rafflePrizeCouponId`. The
+     * editor LOADS the legacy scalar (see the hydration below, which folds it in
+     * through `rafflePrizeCouponIdsOf`) so an old event's prize is visible and
+     * editable — but the moment an admin saves, the value lives in the array
+     * alone. Writing both would leave two fields to keep in step, which is the
+     * mirror-drift trap in Root Cause #42.
+     *
+     * The legacy scalar is deliberately NOT cleared here: a merge-write cannot
+     * remove a field anyway (§ Seed API Reference), and `rafflePrizeCouponIdsOf`
+     * dedupes, so a stale scalar duplicating an array entry awards nothing twice.
+     */
+    /*
+     * Unconditional — `[]` included. Every neighbouring field here is written
+     * only when non-empty, which means none of them can be CLEARED through this
+     * form: the route merges, the stored value survives, and the admin's
+     * deletion silently reverts on reload. Not fixing the others in this change
+     * (each needs its own think about what "cleared" means for an event
+     * mid-flight), but a brand-new field must not be born with the bug.
+     */
+    fields.rafflePrizeCouponIds = draft.rafflePrizeCouponIds;
     if (draft.rafflePrizeProductIds.length > 0)
         fields.rafflePrizeProductIds = draft.rafflePrizeProductIds;
     if (draft.raffleType === "spin_wheel" || draft.type === "spin_wheel") {
@@ -205,6 +227,22 @@ function buildEventRaffleFields(draft) {
     }
     return fields;
 }
+/**
+ * Promotional coupons — shown to everyone who opens the public event page.
+ *
+ * 🛑 NOT gated on event type, unlike the sale/offer/poll blocks beside it in
+ * the Settings step. Any event can advertise a code: a tournament can hand out
+ * a shipping coupon, a sale event can list three more. Gating it would make
+ * the field invisible on most of the catalogue for no reason.
+ *
+ * Module-level for the same reason `SpinPrizesEditor` below is — the Settings
+ * step's render closure is counted by `audit-code-quality`'s LARGE_COMPONENT
+ * rule and this block put it 3 lines over. Purely a line-count split; no
+ * behaviour differs from when it was inline.
+ */
+function PromotionalCouponsField({ values, onChange, }) {
+    return (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Promotional coupons" }), _jsx(CouponInlineSelect, { scope: "admin", multiple: true, value: values.couponIds, onChange: (ids) => onChange({ couponIds: ids }), placeholder: "Search coupons to feature on this event\u2026", allowCreate: false }), _jsxs(Text, { size: "xs", color: "muted", children: ["Shown on the public event page for readers to copy and use at checkout. Up to ", ATTACHED_COUPON_MAX, ". Expired and deactivated coupons are hidden automatically, so an old event never advertises a dead code. These are ", _jsx(Span, { className: "italic", children: "not" }), " prizes \u2014 raffle prizes are set in the Raffle step."] })] }));
+}
 // Extracted out of the raffle/spin step's render() so that closure stays
 // under the LARGE_COMPONENT line-count threshold — purely a line-count
 // split, no behavior change from when this was inline.
@@ -246,6 +284,7 @@ function eventToDraft(event) {
         // the toggle as off rather than leaving it `undefined`, which React
         // would read as an uncontrolled input.
         isPinned: Boolean(event.isPinned),
+        couponIds: Array.isArray(event.couponIds) ? event.couponIds : [],
         discountPercent: String(event.saleConfig?.discountPercent ?? 10),
         saleBannerText: event.saleConfig?.bannerText || "",
         couponId: event.offerConfig?.couponId || "",
@@ -270,7 +309,14 @@ function eventToDraft(event) {
         raffleType: event.raffleType || "open_raffle",
         raffleTopN: String(event.raffleTopN ?? 10),
         rafflePrize: event.rafflePrize || "",
-        rafflePrizeCouponId: event.rafflePrizeCouponId || "",
+        /*
+         * 🛑 Through `rafflePrizeCouponIdsOf`, never `event.rafflePrizeCouponIds`
+         * directly. An event created before the widening carries ONLY the
+         * deprecated scalar, and reading just the array would show an empty
+         * picker — so the first save of an unrelated field would silently drop
+         * a prize the admin never knew was set.
+         */
+        rafflePrizeCouponIds: rafflePrizeCouponIdsOf(event),
         rafflePrizeProductIds: Array.isArray(event.rafflePrizeProductIds) ? event.rafflePrizeProductIds : [],
         spinPrizes: Array.isArray(event.spinPrizes) ? event.spinPrizes : [],
         spinMaxPerUser: String(event.spinMaxPerUser ?? 1),
@@ -331,6 +377,15 @@ export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes,
                 coverImageUrl: draft.coverImageUrl || undefined,
                 allowGuestParticipation: draft.allowGuestParticipation,
                 isPinned: draft.isPinned,
+                /*
+                 * Sent UNCONDITIONALLY, including as `[]`. An editor that omits the
+                 * key when the list is empty can never REMOVE the last coupon: the
+                 * route merges, so the stored array survives and the admin watches
+                 * their deletion silently undo itself on reload. Root Cause #76's
+                 * shape, from the other side — there the form could express state it
+                 * did not own; here it must be able to express an empty one it does.
+                 */
+                couponIds: draft.couponIds,
                 ...buildEventTypeConfig(draft),
                 ...buildEventRaffleFields(draft),
             };
@@ -424,23 +479,23 @@ export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes,
         {
             id: "settings",
             label: "Settings",
-            fields: ["status", "allowGuestParticipation", "isPinned", "discountPercent", "saleBannerText", "couponId", "displayCode", "offerBannerText", "pollOptions", "resultsVisibility", "allowMultiSelect", "allowComment", "maxEntriesPerUser", "hasLeaderboard", "hasPointSystem", "pointsLabel", "entryReviewRequired", "surveyFields", "anonymous", "feedbackFields"],
+            fields: ["status", "allowGuestParticipation", "isPinned", "couponIds", "discountPercent", "saleBannerText", "couponId", "displayCode", "offerBannerText", "pollOptions", "resultsVisibility", "allowMultiSelect", "allowComment", "maxEntriesPerUser", "hasLeaderboard", "hasPointSystem", "pointsLabel", "entryReviewRequired", "surveyFields", "anonymous", "feedbackFields"],
             // Same: the offer-coupon, offer-display-code and poll-minimum-options
             // rules are all stated in eventDraftSchema's superRefine, which now
             // surfaces them inline on the field instead of as a step-blocking banner.
-            render: ({ values, onChange, errors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Event Settings" }), isEdit && (_jsx(Select, { label: "Status", error: errors.status, value: values.status, options: EVENT_STATUS_OPTIONS, onChange: (e) => onChange({ status: e.target.value }) })), values.createdBy && (_jsxs(Stack, { gap: "none", children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Created by" }), _jsx(Text, { size: "sm", color: "muted", children: values.createdBy })] })), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.allowGuestParticipation, onChange: (v) => onChange({ allowGuestParticipation: v }), label: "Allow guest participation (no login required)" }), _jsx(Text, { size: "xs", color: "muted", children: "When enabled, unauthenticated visitors can participate in this event (poll vote, survey/feedback response, raffle entry, or wheel spin), identified by a hashed IP address instead of an account. Applies uniformly to whatever entry mechanism this event type uses." })] }), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.isPinned, onChange: (v) => onChange({ isPinned: v }), label: "Pin to the top of Events" }), _jsx(Text, { size: "xs", color: "muted", children: "Pinned events are listed first on the Events page and in the homepage strip, ahead of the usual soonest-first order. A pinned event still has to be Active to appear at all \u2014 pinning does not publish it." })] }), values.type === "sale" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Sale configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Discount %", error: errors.discountPercent, type: "number", value: values.discountPercent, onChange: (e) => onChange({ discountPercent: e.target.value }), placeholder: "10" }), _jsx(Input, { label: "Banner text (optional)", value: values.saleBannerText, error: errors.saleBannerText, onChange: (e) => onChange({ saleBannerText: e.target.value }), placeholder: "Limited time \u2014 ends Sunday!" })] })] })), values.type === "offer" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Offer configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupon" }), _jsx(CouponInlineSelect, { scope: "admin", value: values.couponId, onChange: (id) => onChange({ couponId: id ?? "" }), placeholder: "Search coupons\u2026", allowCreate: false })] }), _jsx(Input, { label: "Display code", error: errors.displayCode, value: values.displayCode, onChange: (e) => onChange({ displayCode: e.target.value }), placeholder: "CHARIZARD25", required: true })] }), _jsx(Input, { label: "Banner text (optional)", value: values.offerBannerText, error: errors.offerBannerText, onChange: (e) => onChange({ offerBannerText: e.target.value }), placeholder: "Use CHARIZARD25 at checkout" })] })), values.type === "poll" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Poll configuration" }), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", children: "Options (minimum 2)" }), values.pollOptions.map((opt, idx) => (_jsxs(Row, { gap: "xs", children: [_jsx(Div, { className: "flex-1", children: _jsx(Input, { value: opt.label, 
+            render: ({ values, onChange, errors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Event Settings" }), isEdit && (_jsx(Select, { label: "Status", error: errors.status, value: values.status, options: EVENT_STATUS_OPTIONS, onChange: (e) => onChange({ status: e.target.value }) })), values.createdBy && (_jsxs(Stack, { gap: "none", children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Created by" }), _jsx(Text, { size: "sm", color: "muted", children: values.createdBy })] })), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.allowGuestParticipation, onChange: (v) => onChange({ allowGuestParticipation: v }), label: "Allow guest participation (no login required)" }), _jsx(Text, { size: "xs", color: "muted", children: "When enabled, unauthenticated visitors can participate in this event (poll vote, survey/feedback response, raffle entry, or wheel spin), identified by a hashed IP address instead of an account. Applies uniformly to whatever entry mechanism this event type uses." })] }), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.isPinned, onChange: (v) => onChange({ isPinned: v }), label: "Pin to the top of Events" }), _jsx(Text, { size: "xs", color: "muted", children: "Pinned events are listed first on the Events page and in the homepage strip, ahead of the usual soonest-first order. A pinned event still has to be Active to appear at all \u2014 pinning does not publish it." })] }), _jsx(PromotionalCouponsField, { values: values, onChange: onChange }), values.type === "sale" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Sale configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Discount %", error: errors.discountPercent, type: "number", value: values.discountPercent, onChange: (e) => onChange({ discountPercent: e.target.value }), placeholder: "10" }), _jsx(Input, { label: "Banner text (optional)", value: values.saleBannerText, error: errors.saleBannerText, onChange: (e) => onChange({ saleBannerText: e.target.value }), placeholder: "Limited time \u2014 ends Sunday!" })] })] })), values.type === "offer" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Offer configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupon" }), _jsx(CouponInlineSelect, { scope: "admin", value: values.couponId, onChange: (id) => onChange({ couponId: id ?? "" }), placeholder: "Search coupons\u2026", allowCreate: false })] }), _jsx(Input, { label: "Display code", error: errors.displayCode, value: values.displayCode, onChange: (e) => onChange({ displayCode: e.target.value }), placeholder: "CHARIZARD25", required: true })] }), _jsx(Input, { label: "Banner text (optional)", value: values.offerBannerText, error: errors.offerBannerText, onChange: (e) => onChange({ offerBannerText: e.target.value }), placeholder: "Use CHARIZARD25 at checkout" })] })), values.type === "poll" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Poll configuration" }), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", children: "Options (minimum 2)" }), values.pollOptions.map((opt, idx) => (_jsxs(Row, { gap: "xs", children: [_jsx(Div, { className: "flex-1", children: _jsx(Input, { value: opt.label, 
                                                     /* Indexed: a failure on option 2 arrives as `pollOptions.1.label`. */
                                                     error: errors[`pollOptions.${idx}.label`], onChange: (e) => onChange({ pollOptions: values.pollOptions.map((o) => o.id === opt.id ? { ...o, label: e.target.value } : o) }), placeholder: `Option ${idx + 1}` }) }), values.pollOptions.length > 2 && (_jsx(Button, { variant: "ghost", type: "button", onClick: () => onChange({ pollOptions: values.pollOptions.filter((o) => o.id !== opt.id) }), className: CLS_REMOVE_BTN_PX2, "aria-label": "Remove option", children: "\u00D7" }))] }, opt.id))), _jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: () => onChange({ pollOptions: [...values.pollOptions, { id: `opt${Date.now()}`, label: "" }] }), children: "+ Add option" })] }), _jsx(Select, { label: "Results visibility", error: errors.resultsVisibility, value: values.resultsVisibility, options: POLL_VISIBILITY_OPTIONS, onChange: (e) => onChange({ resultsVisibility: e.target.value }) }), _jsxs(Stack, { gap: "sm", children: [_jsx(Toggle, { checked: values.allowMultiSelect, onChange: (v) => onChange({ allowMultiSelect: v }), label: "Allow multi-select" }), _jsx(Toggle, { checked: values.allowComment, onChange: (v) => onChange({ allowComment: v }), label: "Allow comment with vote" })] })] })), values.type === "survey" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Survey configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Max entries per user", error: errors.maxEntriesPerUser, type: "number", value: values.maxEntriesPerUser, onChange: (e) => onChange({ maxEntriesPerUser: e.target.value }), placeholder: "1" }), values.hasPointSystem && (_jsx(Input, { label: "Points label", error: errors.pointsLabel, value: values.pointsLabel, onChange: (e) => onChange({ pointsLabel: e.target.value }), placeholder: "Points" }))] }), _jsxs(Stack, { gap: "xs", children: [_jsx(Toggle, { checked: values.requireLogin, onChange: (v) => onChange({ requireLogin: v }), label: "Require login to participate" }), _jsx(Toggle, { checked: values.hasLeaderboard, onChange: (v) => onChange({ hasLeaderboard: v }), label: "Show leaderboard" }), _jsx(Toggle, { checked: values.hasPointSystem, onChange: (v) => onChange({ hasPointSystem: v }), label: "Enable point system" }), _jsx(Toggle, { checked: values.entryReviewRequired, onChange: (v) => onChange({ entryReviewRequired: v }), label: "Require employee review before entry is approved" })] }), _jsx(FormFieldBuilder, { fields: values.surveyFields, setFields: (f) => onChange({ surveyFields: f }) })] })), values.type === "feedback" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Feedback configuration" }), _jsx(Toggle, { checked: values.anonymous, onChange: (v) => onChange({ anonymous: v }), label: "Allow anonymous submissions" }), _jsx(FormFieldBuilder, { fields: values.feedbackFields, setFields: (f) => onChange({ feedbackFields: f }) })] }))] })),
         },
         {
             id: "raffle",
             label: "Raffle / Spin",
-            fields: ["hasRaffle", "raffleType", "raffleTopN", "rafflePrize", "rafflePrizeCouponId", "rafflePrizeProductIds", "spinPrizes", "spinMaxPerUser", "spinWindowStart", "spinWindowEnd"],
+            fields: ["hasRaffle", "raffleType", "raffleTopN", "rafflePrize", "rafflePrizeCouponIds", "rafflePrizeProductIds", "spinPrizes", "spinMaxPerUser", "spinWindowStart", "spinWindowEnd"],
             render: ({ values, onChange, errors }) => {
                 const isRaffleType = values.type === "raffle" || values.type === "spin_wheel";
                 const showRaffleConfig = isRaffleType || values.hasRaffle;
                 const isSpinMode = values.type === "spin_wheel" || values.raffleType === "spin_wheel";
-                return (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Raffle & Spin Wheel" }), !isRaffleType && (_jsx(Toggle, { checked: values.hasRaffle, onChange: (v) => onChange({ hasRaffle: v }), label: "Attach a raffle to this event" })), !isRaffleType && !values.hasRaffle && (_jsx(Text, { size: "sm", color: "muted", children: "Enable the toggle above to attach a raffle draw to this event. Not applicable for this event type by default." })), showRaffleConfig && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Select, { label: "Raffle type", error: errors.raffleType, value: values.type === "spin_wheel" ? "spin_wheel" : values.raffleType, options: RAFFLE_TYPE_OPTIONS, onChange: (e) => onChange({ raffleType: e.target.value }), disabled: values.type === "spin_wheel" }), _jsx(Input, { label: "Top N (for top-N raffle types)", error: errors.raffleTopN, type: "number", value: values.raffleTopN, onChange: (e) => onChange({ raffleTopN: e.target.value }), placeholder: "10" })] }), _jsx(Input, { label: "Prize description", error: errors.rafflePrize, value: values.rafflePrize, onChange: (e) => onChange({ rafflePrize: e.target.value }), placeholder: "\u20B92,000 store credit + exclusive Pikachu sticker" }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupon for winner (optional)" }), _jsx(CouponInlineSelect, { scope: "admin", value: values.rafflePrizeCouponId, onChange: (id) => onChange({ rafflePrizeCouponId: id ?? "" }), placeholder: "Search coupons\u2026", allowCreate: false })] }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Prize products (optional)" }), _jsx(ProductInlineSelect, { scope: "admin", multiple: true, value: values.rafflePrizeProductIds, onChange: (ids) => onChange({ rafflePrizeProductIds: ids }), placeholder: "Search products to feature as prizes\u2026" }), _jsx(Text, { size: "xs", color: "muted", className: "mt-1", children: "Products shown to winners or displayed as the prize showcase." })] }), isSpinMode && _jsx(SpinPrizesEditor, { values: values, onChange: onChange }), isEdit && (_jsxs(Stack, { gap: "xs", rounded: "lg", padding: "sm", className: CLS_RAFFLE_PANEL, children: [_jsxs(Row, { justify: "between", gap: "sm", children: [_jsx(Text, { size: "sm", weight: "medium", className: CLS_RAFFLE_HEADING, children: raffleWinnerName ? `Winner: ${raffleWinnerName}` : "Raffle not yet triggered" }), _jsx(Button, { type: "button", action: ACTIONS.EVENT["draw-raffle-winner"], size: "sm", onClick: () => triggerRaffleMutation.mutate(), disabled: triggerRaffleMutation.isPending || Boolean(raffleWinnerName), children: triggerRaffleMutation.isPending ? "Triggering…" : raffleWinnerName ? "Already triggered" : "Trigger Raffle Now" })] }), raffleEntryCount !== null && _jsxs(Text, { size: "xs", className: CLS_RAFFLE_BODY, children: ["Pool size: ", raffleEntryCount] }), raffleGithubUrl && _jsxs(Text, { size: "xs", className: `break-all ${CLS_RAFFLE_BODY}`, children: ["Fairness proof: ", raffleGithubUrl] }), triggerMessage && _jsx(Text, { size: "xs", className: CLS_RAFFLE_HEADING, children: triggerMessage })] }))] }))] }));
+                return (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Raffle & Spin Wheel" }), !isRaffleType && (_jsx(Toggle, { checked: values.hasRaffle, onChange: (v) => onChange({ hasRaffle: v }), label: "Attach a raffle to this event" })), !isRaffleType && !values.hasRaffle && (_jsx(Text, { size: "sm", color: "muted", children: "Enable the toggle above to attach a raffle draw to this event. Not applicable for this event type by default." })), showRaffleConfig && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Select, { label: "Raffle type", error: errors.raffleType, value: values.type === "spin_wheel" ? "spin_wheel" : values.raffleType, options: RAFFLE_TYPE_OPTIONS, onChange: (e) => onChange({ raffleType: e.target.value }), disabled: values.type === "spin_wheel" }), _jsx(Input, { label: "Top N (for top-N raffle types)", error: errors.raffleTopN, type: "number", value: values.raffleTopN, onChange: (e) => onChange({ raffleTopN: e.target.value }), placeholder: "10" })] }), _jsx(Input, { label: "Prize description", error: errors.rafflePrize, value: values.rafflePrize, onChange: (e) => onChange({ rafflePrize: e.target.value }), placeholder: "\u20B92,000 store credit + exclusive Pikachu sticker" }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupons for winner (optional)" }), _jsx(CouponInlineSelect, { scope: "admin", multiple: true, value: values.rafflePrizeCouponIds, onChange: (ids) => onChange({ rafflePrizeCouponIds: ids }), placeholder: "Search coupons\u2026", allowCreate: false }), _jsxs(Text, { size: "xs", color: "muted", className: "mt-1", children: ["Every coupon listed here is awarded to the winner when the draw runs. Up to ", ATTACHED_COUPON_MAX, "."] })] }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Prize products (optional)" }), _jsx(ProductInlineSelect, { scope: "admin", multiple: true, value: values.rafflePrizeProductIds, onChange: (ids) => onChange({ rafflePrizeProductIds: ids }), placeholder: "Search products to feature as prizes\u2026" }), _jsx(Text, { size: "xs", color: "muted", className: "mt-1", children: "Products shown to winners or displayed as the prize showcase." })] }), isSpinMode && _jsx(SpinPrizesEditor, { values: values, onChange: onChange }), isEdit && (_jsxs(Stack, { gap: "xs", rounded: "lg", padding: "sm", className: CLS_RAFFLE_PANEL, children: [_jsxs(Row, { justify: "between", gap: "sm", children: [_jsx(Text, { size: "sm", weight: "medium", className: CLS_RAFFLE_HEADING, children: raffleWinnerName ? `Winner: ${raffleWinnerName}` : "Raffle not yet triggered" }), _jsx(Button, { type: "button", action: ACTIONS.EVENT["draw-raffle-winner"], size: "sm", onClick: () => triggerRaffleMutation.mutate(), disabled: triggerRaffleMutation.isPending || Boolean(raffleWinnerName), children: triggerRaffleMutation.isPending ? "Triggering…" : raffleWinnerName ? "Already triggered" : "Trigger Raffle Now" })] }), raffleEntryCount !== null && _jsxs(Text, { size: "xs", className: CLS_RAFFLE_BODY, children: ["Pool size: ", raffleEntryCount] }), raffleGithubUrl && _jsxs(Text, { size: "xs", className: `break-all ${CLS_RAFFLE_BODY}`, children: ["Fairness proof: ", raffleGithubUrl] }), triggerMessage && _jsx(Text, { size: "xs", className: CLS_RAFFLE_HEADING, children: triggerMessage })] }))] }))] }));
             },
         },
     ];

package/dist/features/events/components/EventOfferCard.js

@@ -1,11 +1,10 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { normalizeError } from "../../../errors/normalize.js";
-import { useState } from "react";
 import Link from "next/link.js";
-import { Code, Div, Heading, Row, Stack, Text } from "../../../ui/index.js";
+import { Div, Heading, Stack, Text } from "../../../ui/index.js";
 import { Button } from "../../../ui/components/Button.js";
 import { ROUTES } from "../../../next/routing/route-map.js";
+import { CouponCodeCopyRow } from "../../promotions/components/CouponCodeCopyRow.js";
 const __P = {
     p6: "p-[var(--appkit-space-6)]",
 };
@@ -15,22 +14,8 @@ const __P = {
  * products page.
  */
 export function EventOfferCard({ couponCode, offerDescription, title = "Exclusive offer", filterParam, }) {
-    const [copied, setCopied] = useState(false);
     const href = filterParam
         ? `${ROUTES.PUBLIC.PRODUCTS}?${encodeURIComponent(filterParam.key)}=${encodeURIComponent(filterParam.value)}`
         : String(ROUTES.PUBLIC.PRODUCTS);
-    const copyCode = async () => {
-        try {
-            await navigator.clipboard.writeText(couponCode);
-            setCopied(true);
-            setTimeout(() => setCopied(false), 2000);
-            // Clipboard access is denied outright on insecure origins and by user
-            // permission. The button simply never flips to "Copied", and the code is
-            // still visible on screen to select by hand.
-        }
-        catch (_err) {
-            void normalizeError(_err);
-        }
-    };
-    return (_jsx(Div, { className: `${__P.p6}`, rounded: "2xl", border: "default", children: _jsxs(Stack, { gap: "md", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 2, weight: "semibold", size: "2xl", children: title }), offerDescription ? (_jsx(Text, { size: "sm", color: "muted", children: offerDescription })) : null] }), _jsxs(Row, { surface: "muted", padding: "inline", align: "center", gap: "3", rounded: "lg", children: [_jsx(Code, { className: "flex-1", weight: "bold", size: "base", color: "primary", children: couponCode }), _jsx(Button, { type: "button", variant: "outline", onClick: copyCode, children: copied ? "Copied!" : "Copy code" })] }), _jsx(Div, { children: _jsx(Link, { href: href, children: _jsx(Button, { variant: "primary", children: "Apply at checkout" }) }) })] }) }));
+    return (_jsx(Div, { className: `${__P.p6}`, rounded: "2xl", border: "default", children: _jsxs(Stack, { gap: "md", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 2, weight: "semibold", size: "2xl", children: title }), offerDescription ? (_jsx(Text, { size: "sm", color: "muted", children: offerDescription })) : null] }), _jsx(CouponCodeCopyRow, { code: couponCode, ariaContext: title }), _jsx(Div, { children: _jsx(Link, { href: href, children: _jsx(Button, { variant: "primary", children: "Apply at checkout" }) }) })] }) }));
 }

package/dist/features/events/components/EventRaffleWinnerView.d.ts

@@ -11,6 +11,12 @@ export interface RaffleWinnerEvent {
      * `currentUserIsWinner` so the CTA only renders for the actual winner.
      */
     rafflePrizeCouponCode?: string;
+    /**
+     * Every prize coupon's code, for a raffle awarding more than one. Supersedes
+     * the singular field above, which stays declared because raffles drawn
+     * before this existed recorded only that.
+     */
+    rafflePrizeCouponCodes?: string[];
 }
 export interface EventRaffleWinnerViewProps {
     event: RaffleWinnerEvent;

package/dist/features/events/components/EventRaffleWinnerView.js

@@ -17,8 +17,18 @@ const DEFAULT_LABELS = {
 };
 export function EventRaffleWinnerView({ event, currentUserIsWinner, labels }) {
     const l = { ...DEFAULT_LABELS, ...(labels ?? {}) };
+    /*
+     * Array first, singular as the fallback — and deduped, because the page
+     * feeds `rafflePrizeCouponCode` from the first entry of the same list, so a
+     * naive concat would render the first prize twice.
+     */
+    const winnerCouponCodes = Array.from(new Set(event.rafflePrizeCouponCodes?.length
+        ? event.rafflePrizeCouponCodes
+        : event.rafflePrizeCouponCode
+            ? [event.rafflePrizeCouponCode]
+            : []));
     if (!event.raffleWinnerUserId) {
         return (_jsx(Div, { className: "border-dashed text-left", border: "strong", paddingY: "y-2xl", paddingX: "x-lg", rounded: "xl", children: _jsx(Text, { color: "muted", children: l.notDrawnYet }) }));
     }
-    return (_jsx(Article, { children: _jsxs(Stack, { gap: "lg", children: [_jsxs(Heading, { level: 2, size: "xl", weight: "semibold", color: "primary", children: ["\uD83C\uDF9F\uFE0F ", l.heading] }), _jsxs(Div, { className: CLS_PANEL, children: [_jsxs(Div, { children: [_jsx(Text, { className: CLS_LABEL, children: l.winnerLabel }), _jsx(Text, { className: CLS_WINNER_NAME, children: event.raffleWinnerDisplayName?.trim() || l.anonymous })] }), event.rafflePrize ? (_jsxs(Div, { children: [_jsx(Text, { className: CLS_LABEL, children: l.prizeLabel }), _jsx(Text, { className: "mt-1", color: "primary", size: "base", children: event.rafflePrize })] })) : null, currentUserIsWinner && event.rafflePrizeCouponCode ? (_jsx(Div, { padding: "t-xs", children: _jsx(ClaimCouponButton, { couponCode: event.rafflePrizeCouponCode, source: "raffle", size: "sm" }) })) : null, _jsxs(Row, { wrap: true, textSize: "sm", className: "gap-x-6 gap-y-2", color: "muted", padding: "t-xs", children: [typeof event.raffleEntryCount === "number" ? (_jsxs(Span, { children: [l.poolLabel, ":", " ", _jsx(Span, { weight: "medium", color: "primary", children: event.raffleEntryCount })] })) : null, event.raffleTriggeredAt ? (_jsx(Span, { children: new Date(event.raffleTriggeredAt).toLocaleString() })) : null] })] }), event.raffleGithubFunctionUrl ? (_jsxs(Div, { textSize: "sm", className: `${__P.p4}`, rounded: "lg", border: "default", children: [_jsx(Text, { weight: "medium", color: "primary", children: l.fairnessLabel }), _jsx(TextLink, { href: event.raffleGithubFunctionUrl, className: "mt-1 block break-all text-primary-600 dark:text-primary-400 hover:underline", children: event.raffleGithubFunctionUrl })] })) : null] }) }));
+    return (_jsx(Article, { children: _jsxs(Stack, { gap: "lg", children: [_jsxs(Heading, { level: 2, size: "xl", weight: "semibold", color: "primary", children: ["\uD83C\uDF9F\uFE0F ", l.heading] }), _jsxs(Div, { className: CLS_PANEL, children: [_jsxs(Div, { children: [_jsx(Text, { className: CLS_LABEL, children: l.winnerLabel }), _jsx(Text, { className: CLS_WINNER_NAME, children: event.raffleWinnerDisplayName?.trim() || l.anonymous })] }), event.rafflePrize ? (_jsxs(Div, { children: [_jsx(Text, { className: CLS_LABEL, children: l.prizeLabel }), _jsx(Text, { className: "mt-1", color: "primary", size: "base", children: event.rafflePrize })] })) : null, currentUserIsWinner && winnerCouponCodes.length > 0 ? (_jsx(Div, { padding: "t-xs", children: _jsx(Row, { wrap: true, className: "gap-x-3 gap-y-2", children: winnerCouponCodes.map((code) => (_jsx(ClaimCouponButton, { couponCode: code, source: "raffle", size: "sm" }, code))) }) })) : null, _jsxs(Row, { wrap: true, textSize: "sm", className: "gap-x-6 gap-y-2", color: "muted", padding: "t-xs", children: [typeof event.raffleEntryCount === "number" ? (_jsxs(Span, { children: [l.poolLabel, ":", " ", _jsx(Span, { weight: "medium", color: "primary", children: event.raffleEntryCount })] })) : null, event.raffleTriggeredAt ? (_jsx(Span, { children: new Date(event.raffleTriggeredAt).toLocaleString() })) : null] })] }), event.raffleGithubFunctionUrl ? (_jsxs(Div, { textSize: "sm", className: `${__P.p4}`, rounded: "lg", border: "default", children: [_jsx(Text, { weight: "medium", color: "primary", children: l.fairnessLabel }), _jsx(TextLink, { href: event.raffleGithubFunctionUrl, className: "mt-1 block break-all text-primary-600 dark:text-primary-400 hover:underline", children: event.raffleGithubFunctionUrl })] })) : null] }) }));
 }

package/dist/features/events/schemas/event-form.d.ts

@@ -42,6 +42,8 @@ export declare const eventDraftSchema: z.ZodEffects<z.ZodObject<{
         id: string;
         label: string;
     }>, "many">;
+    couponIds: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
+    rafflePrizeCouponIds: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     type: z.ZodString;
     title: z.ZodString;
@@ -59,6 +61,8 @@ export declare const eventDraftSchema: z.ZodEffects<z.ZodObject<{
         id: string;
         label: string;
     }>, "many">;
+    couponIds: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
+    rafflePrizeCouponIds: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     type: z.ZodString;
     title: z.ZodString;
@@ -76,6 +80,8 @@ export declare const eventDraftSchema: z.ZodEffects<z.ZodObject<{
         id: string;
         label: string;
     }>, "many">;
+    couponIds: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
+    rafflePrizeCouponIds: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
 }, z.ZodTypeAny, "passthrough">>, z.objectOutputType<{
     type: z.ZodString;
     title: z.ZodString;
@@ -93,6 +99,8 @@ export declare const eventDraftSchema: z.ZodEffects<z.ZodObject<{
         id: string;
         label: string;
     }>, "many">;
+    couponIds: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
+    rafflePrizeCouponIds: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     type: z.ZodString;
     title: z.ZodString;
@@ -110,4 +118,6 @@ export declare const eventDraftSchema: z.ZodEffects<z.ZodObject<{
         id: string;
         label: string;
     }>, "many">;
+    couponIds: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
+    rafflePrizeCouponIds: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
 }, z.ZodTypeAny, "passthrough">>;

package/dist/features/events/schemas/event-form.js

@@ -16,6 +16,7 @@
  */
 import { z } from "zod";
 import { annotate } from "../../shell/field-ui-meta.js";
+import { attachedCouponIdsSchema } from "../../promotions/schemas/attached-coupons.js";
 /**
  * ## `.passthrough()` STAYS here, deliberately
  *
@@ -67,6 +68,24 @@ export const eventDraftSchema = z.object({
     pollOptions: annotate(z.array(z.object({ id: z.string(), label: z.string() })), {
         section: "settings", order: 3, row: "full", kind: "list",
     }),
+    /*
+     * Named explicitly even though this object is `.passthrough()` and would
+     * carry them regardless — passthrough preserves a value, it does not
+     * VALIDATE one. Without these two entries the cap would be enforced only by
+     * the API route, so an admin who picked eleven coupons would fill the form,
+     * hit Save, and be told by a 400 what the field could have told them while
+     * they were still looking at it.
+     *
+     * 🛑 `couponIds` (promotional, shown to every reader) and
+     * `rafflePrizeCouponIds` (awarded to one winner) are DIFFERENT fields on
+     * purpose — see `EventDocument`. They share a schema, never a value.
+     */
+    couponIds: annotate(attachedCouponIdsSchema, {
+        section: "settings", order: 4, row: "full", kind: "list",
+    }),
+    rafflePrizeCouponIds: annotate(attachedCouponIdsSchema, {
+        section: "raffle", sectionLabel: "Raffle & Spin Wheel", order: 5, row: "full", kind: "list",
+    }),
 }).passthrough().superRefine((v, ctx) => {
     if (v.type === "offer") {
         if (!v.couponId.trim()) {

package/dist/features/events/schemas/firestore.d.ts

@@ -45,6 +45,24 @@ export interface EventDocument extends BaseDocument {
     winnerImages?: MediaField[];
     additionalImages?: MediaField[];
     tags?: string[];
+    /**
+     * PROMOTIONAL coupons shown on the event page for a reader to copy.
+     *
+     * 🛑 Not a prize, and not the same field as `rafflePrizeCouponIds` below.
+     * These are advertised to everyone who opens the page; those are awarded to
+     * one winner. The two were deliberately kept apart rather than overloaded,
+     * because every reader of a prize field asks "who won it" and every reader
+     * of a promo field asks "can I use it", and one array cannot answer both.
+     *
+     * Capped at `ATTACHED_COUPON_MAX` by the write schemas AND re-clamped by
+     * `couponsRepository.findByIds`. Resolved for display by
+     * `getAttachedCoupons`, which drops expired and inactive entries so a page
+     * never advertises a code the till will refuse.
+     *
+     * Mirrors `BlogPostDocument.couponIds` — same name, same shape, same
+     * renderer, on purpose.
+     */
+    couponIds?: string[];
     saleConfig?: SaleConfig;
     offerConfig?: OfferConfig;
     pollConfig?: PollConfig;
@@ -54,12 +72,43 @@ export interface EventDocument extends BaseDocument {
     raffleType?: RaffleType;
     raffleTopN?: number;
     rafflePrize?: string;
+    /**
+     * @deprecated Legacy single raffle-prize coupon. READ-ONLY — kept because
+     * `appkit-seed load` writes with `set({merge:true})` and therefore CANNOT
+     * remove a field from a live document (§ Seed API Reference), so events
+     * written before this widening still carry it and a reader that stops
+     * looking silently stops awarding their prize.
+     *
+     * 🛑 Never write this from new code. Resolve both through
+     * `rafflePrizeCouponIdsOf(event)`, which folds the legacy scalar into the
+     * array — the reader-side fallback Root Cause #42 prescribes, so no data
+     * migration is required and a forgotten write path cannot strand a prize.
+     */
     rafflePrizeCouponId?: string;
+    /**
+     * Coupons awarded to the raffle winner. Replaces the single
+     * `rafflePrizeCouponId` above; a raffle may now hand over several.
+     */
+    rafflePrizeCouponIds?: string[];
     rafflePrizeProductIds?: string[];
     raffleGithubFunctionUrl?: string;
     raffleWinnerUserId?: string;
     raffleWinnerDisplayName?: string;
     raffleWinnerEntryId?: string;
+    /**
+     * The prize coupon CODES, resolved and frozen at draw time by
+     * `triggerEventRaffle` so the prize survives a later edit of the event's
+     * coupon list — the same reason an entry stores `spinPrizeCouponCode`
+     * instead of re-deriving it.
+     *
+     * 🛑 Both were WRITTEN by the raffle job and declared on no interface until
+     * this change. An undeclared field is invisible to every type-driven review
+     * and to `audit-public-projection-parity`, which is how five settings fields
+     * ended up publicly readable in Root Cause #70. Declared now, even though
+     * both are already public by design (a winner announcement is a public page).
+     */
+    rafflePrizeCouponCode?: string;
+    rafflePrizeCouponCodes?: string[];
     raffleTriggeredAt?: Date;
     raffleEntryCount?: number;
     spinPrizes?: SpinPrize[];
@@ -150,6 +199,8 @@ export declare const EVENT_FIELDS: {
     readonly WINNER_IMAGES: "winnerImages";
     readonly ADDITIONAL_IMAGES: "additionalImages";
     readonly TAGS: "tags";
+    readonly COUPON_IDS: "couponIds";
+    readonly RAFFLE_PRIZE_COUPON_IDS: "rafflePrizeCouponIds";
     readonly IS_PINNED: "isPinned";
     readonly ALLOW_GUEST_PARTICIPATION: "allowGuestParticipation";
     readonly CREATED_BY: "createdBy";
@@ -213,6 +264,23 @@ export declare const EVENT_ENTRY_FIELDS: {
 export type EventCreateInput = Omit<EventDocument, "id" | "createdAt" | "updatedAt" | "stats">;
 export type EventUpdateInput = Partial<Omit<EventDocument, "id" | "createdAt" | "createdBy">>;
 export type EventEntryCreateInput = Omit<EventEntryPlain, "id" | "submittedAt">;
+/**
+ * Every coupon this event awards its raffle winner, folding the deprecated
+ * single `rafflePrizeCouponId` into the array.
+ *
+ * 🛑 EVERY reader goes through this — never touch either field directly.
+ * `appkit-seed load` merge-writes, so it cannot remove a field from a live
+ * document: events created before the widening still carry only the scalar,
+ * and a reader that looks solely at `rafflePrizeCouponIds` hands those
+ * winners nothing while erroring nowhere. Making the READER resilient is the
+ * fix Root Cause #42 prescribes, and it means this change needs no migration
+ * and no backfill script.
+ *
+ * Deduped because an admin who edits an old event through the new picker ends
+ * up with the same id in both fields, and awarding it twice would double the
+ * prize.
+ */
+export declare function rafflePrizeCouponIdsOf(event: Pick<EventDocument, "rafflePrizeCouponId" | "rafflePrizeCouponIds">): string[];
 export declare const eventQueryHelpers: {
     readonly active: () => readonly ["status", "==", EventStatus];
     readonly byType: (type: EventType) => readonly ["type", "==", EventType];

package/dist/features/events/schemas/firestore.js

@@ -38,6 +38,8 @@ export const EVENT_FIELDS = {
     WINNER_IMAGES: "winnerImages",
     ADDITIONAL_IMAGES: "additionalImages",
     TAGS: "tags",
+    COUPON_IDS: "couponIds",
+    RAFFLE_PRIZE_COUPON_IDS: "rafflePrizeCouponIds",
     IS_PINNED: "isPinned",
     ALLOW_GUEST_PARTICIPATION: "allowGuestParticipation",
     CREATED_BY: "createdBy",
@@ -98,6 +100,29 @@ export const EVENT_ENTRY_FIELDS = {
         FLAGGED: "flagged",
     },
 };
+/**
+ * Every coupon this event awards its raffle winner, folding the deprecated
+ * single `rafflePrizeCouponId` into the array.
+ *
+ * 🛑 EVERY reader goes through this — never touch either field directly.
+ * `appkit-seed load` merge-writes, so it cannot remove a field from a live
+ * document: events created before the widening still carry only the scalar,
+ * and a reader that looks solely at `rafflePrizeCouponIds` hands those
+ * winners nothing while erroring nowhere. Making the READER resilient is the
+ * fix Root Cause #42 prescribes, and it means this change needs no migration
+ * and no backfill script.
+ *
+ * Deduped because an admin who edits an old event through the new picker ends
+ * up with the same id in both fields, and awarding it twice would double the
+ * prize.
+ */
+export function rafflePrizeCouponIdsOf(event) {
+    const ids = [
+        ...(event.rafflePrizeCouponIds ?? []),
+        ...(event.rafflePrizeCouponId ? [event.rafflePrizeCouponId] : []),
+    ].filter(Boolean);
+    return Array.from(new Set(ids));
+}
 export const eventQueryHelpers = {
     active: () => ["status", "==", "active"],
     byType: (type) => ["type", "==", type],