@mohasinac/appkit 4.63.3 → 4.63.5

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

@@ -835,11 +835,14 @@ export declare const eventItemSchema: z.ZodObject<{
             placeholder?: string | undefined;
         }[];
     }>>;
+    couponIds: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
     hasRaffle: z.ZodOptional<z.ZodBoolean>;
     raffleType: z.ZodOptional<z.ZodEnum<["top_n_scorers", "top_n_participants", "open_raffle", "spin_wheel"]>>;
     raffleTopN: z.ZodOptional<z.ZodNumber>;
     rafflePrize: z.ZodOptional<z.ZodString>;
+    /** @deprecated read-only legacy scalar — see `rafflePrizeCouponIdsOf`. */
     rafflePrizeCouponId: z.ZodOptional<z.ZodString>;
+    rafflePrizeCouponIds: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
     rafflePrizeProductIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     raffleGithubFunctionUrl: z.ZodOptional<z.ZodString>;
     raffleWinnerUserId: z.ZodOptional<z.ZodString>;
@@ -992,11 +995,13 @@ export declare const eventItemSchema: z.ZodObject<{
         duration?: number | undefined;
     }[];
     slug?: string | undefined;
+    couponIds?: string[] | undefined;
     hasRaffle?: boolean | undefined;
     raffleType?: "spin_wheel" | "open_raffle" | "top_n_scorers" | "top_n_participants" | undefined;
     raffleTopN?: number | undefined;
     rafflePrize?: string | undefined;
     rafflePrizeCouponId?: string | undefined;
+    rafflePrizeCouponIds?: string[] | undefined;
     raffleGithubFunctionUrl?: string | undefined;
     raffleWinnerUserId?: string | undefined;
     raffleWinnerDisplayName?: string | undefined;
@@ -1108,11 +1113,13 @@ export declare const eventItemSchema: z.ZodObject<{
         flaggedEntries: number;
     };
     slug?: string | undefined;
+    couponIds?: string[] | undefined;
     hasRaffle?: boolean | undefined;
     raffleType?: "spin_wheel" | "open_raffle" | "top_n_scorers" | "top_n_participants" | undefined;
     raffleTopN?: number | undefined;
     rafflePrize?: string | undefined;
     rafflePrizeCouponId?: string | undefined;
+    rafflePrizeCouponIds?: string[] | undefined;
     raffleGithubFunctionUrl?: string | undefined;
     raffleWinnerUserId?: string | undefined;
     raffleWinnerDisplayName?: string | undefined;

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

@@ -2,6 +2,7 @@ export * from "./firestore.js";
 import { z } from "zod";
 import { mediaUrlSchema } from "../../../validation/schemas.js";
 import { mediaFieldSchema } from "../../media/types/index.js";
+import { attachedCouponIdsSchema } from "../../promotions/schemas/attached-coupons.js";
 const eventCoverImageSchema = z
     .union([
     mediaFieldSchema,
@@ -125,12 +126,16 @@ export const eventItemSchema = z.object({
     pollConfig: pollConfigSchema.optional(),
     surveyConfig: surveyConfigSchema.optional(),
     feedbackConfig: feedbackConfigSchema.optional(),
+    // Promotional coupons shown on the event page — NOT prizes (see below).
+    couponIds: attachedCouponIdsSchema,
     // Raffle fields
     hasRaffle: z.boolean().optional(),
     raffleType: z.enum(["top_n_scorers", "top_n_participants", "open_raffle", "spin_wheel"]).optional(),
     raffleTopN: z.number().optional(),
     rafflePrize: z.string().optional(),
+    /** @deprecated read-only legacy scalar — see `rafflePrizeCouponIdsOf`. */
     rafflePrizeCouponId: z.string().optional(),
+    rafflePrizeCouponIds: attachedCouponIdsSchema,
     rafflePrizeProductIds: z.array(z.string()).optional(),
     raffleGithubFunctionUrl: z.string().optional(),
     raffleWinnerUserId: z.string().optional(),

package/dist/features/events/types/index.d.ts

@@ -121,11 +121,15 @@ export interface EventItem {
     pollConfig?: PollConfig;
     surveyConfig?: SurveyConfig;
     feedbackConfig?: FeedbackConfig;
+    /** Promotional coupons shown on the page — see `EventDocument.couponIds`. */
+    couponIds?: string[];
     hasRaffle?: boolean;
     raffleType?: RaffleType;
     raffleTopN?: number;
     rafflePrize?: string;
+    /** @deprecated legacy scalar — resolve via `rafflePrizeCouponIdsOf`. */
     rafflePrizeCouponId?: string;
+    rafflePrizeCouponIds?: string[];
     rafflePrizeProductIds?: string[];
     raffleGithubFunctionUrl?: string;
     raffleWinnerUserId?: string;

package/dist/features/homepage/lib/section-renderer.js

@@ -259,7 +259,7 @@ const SECTION_REGISTRY = {
             return (_jsx(WhatsAppCommunitySection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.whatsappCommunity, descriptionHtml: cfg?.description || SECTION_COPY.whatsappDescription, 
                 // No `|| 5000` fallback: inventing a member count the site cannot
                 // verify is a fabricated social-proof number.
-                memberCount: cfg?.memberCount, groupLink: cfg?.groupLink || undefined, benefits: cfg?.benefits ?? [], testimonial: cfg?.testimonial, buttonText: cfg?.buttonText }));
+                memberCount: cfg?.memberCount, groupLink: cfg?.groupLink || "https://chat.whatsapp.com/", benefits: cfg?.benefits ?? [], testimonial: cfg?.testimonial, buttonText: cfg?.buttonText }));
         },
     },
     faq: {

package/dist/features/orders/actions/refund-actions.js

@@ -79,6 +79,7 @@ export async function issuePartialRefund(adminUid, orderId, deductFees, refundNo
             : `Your full refund of ₹${grossRefund} is being processed.`,
         relatedId: orderId,
         relatedType: "order",
+        storeId: order.storeId,
     });
     serverLogger.info("Admin partial refund initiated", {
         adminUid,

package/dist/features/orders/components/OrderAddonBadges.d.ts

@@ -2,7 +2,7 @@ import React from "react";
 /**
  * Icon badges for an order's paid add-ons and applied coupon.
  *
- * These are fulfilment instructions, not decoration: gift wrap tells the
+ * These are fulfilment instructions, not decoration: WhatsApp tells the
  * status-change notifier to message this buyer, gift wrap tells the packer to
  * wrap the parcel and enclose the message, and either protection changes how a
  * claim is handled. They are recorded on the order (and filterable in the
@@ -14,6 +14,8 @@ import React from "react";
  * at once instead of being wired per screen.
  */
 export interface OrderAddonBadgesOrder {
+    whatsappNotifyAddon?: boolean;
+    whatsappNotifyFee?: number;
     giftWrapAddon?: boolean;
     giftWrapFee?: number;
     giftWrapMessage?: string;

package/dist/features/orders/components/OrderAddonBadges.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Gift, ShieldAlert, ShieldCheck, Tag } from "lucide-react";
+import { Gift, MessageCircle, ShieldAlert, ShieldCheck, Tag } from "lucide-react";
 import { Row, Span, Stack, Text } from "../../../ui/index.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
 const CHIP_BASE = "inline-flex items-center gap-[var(--appkit-space-1)] rounded-full px-[var(--appkit-space-2)] py-[var(--appkit-space-0-5)] text-[length:var(--appkit-text-xs)] font-medium";
@@ -15,14 +15,15 @@ function Chip({ icon, label, tone, title, }) {
 export function OrderAddonBadges({ order, variant = "compact", showCoupon = true, currency = "INR", className = "", }) {
     const money = (v) => (typeof v === "number" && v > 0 ? formatCurrency(v, currency) : undefined);
     const hasCoupon = showCoupon && !!order.couponCode;
-    const hasAny = order.giftWrapAddon ||
+    const hasAny = order.whatsappNotifyAddon ||
+        order.giftWrapAddon ||
         order.shipmentProtectionAddon ||
         order.saleProtectionAddon ||
         hasCoupon;
     if (!hasAny)
         return null;
     const isDetail = variant === "detail";
-    return (_jsxs(Stack, { gap: "xs", className: `min-w-0 ${className}`, children: [_jsxs(Row, { gap: "xs", align: "center", wrap: true, className: "min-w-0", children: [order.giftWrapAddon && (_jsx(Chip, { icon: _jsx(Gift, { size: 12 }), label: isDetail && money(order.giftWrapFee) ? `Gift wrap · ${money(order.giftWrapFee)}` : "Gift wrap", tone: "brand", title: "This parcel must be gift-wrapped before dispatch." })), order.shipmentProtectionAddon && (_jsx(Chip, { icon: _jsx(ShieldCheck, { size: 12 }), label: isDetail && money(order.shipmentProtectionFee) ? `Protected · ${money(order.shipmentProtectionFee)}` : "Protected", tone: "info", title: "Shipment protection purchased \u2014 loss or damage in transit is covered, claimed against the held funds." })), order.saleProtectionAddon && (_jsx(Chip, { icon: _jsx(ShieldAlert, { size: 12 }), label: isDetail && money(order.saleProtectionFee) ? `Sale protected · ${money(order.saleProtectionFee)}` : "Sale protected", tone: "info", title: "Sale protection purchased \u2014 if the item is not as described the buyer is refunded, no questions asked." })), hasCoupon && (_jsx(Chip, { icon: _jsx(Tag, { size: 12 }), label: isDetail && money(order.couponDiscount)
+    return (_jsxs(Stack, { gap: "xs", className: `min-w-0 ${className}`, children: [_jsxs(Row, { gap: "xs", align: "center", wrap: true, className: "min-w-0", children: [order.whatsappNotifyAddon && (_jsx(Chip, { icon: _jsx(MessageCircle, { size: 12 }), label: isDetail && money(order.whatsappNotifyFee) ? `WhatsApp updates · ${money(order.whatsappNotifyFee)}` : "WhatsApp updates", tone: "success", title: "Buyer opted into WhatsApp order-status updates \u2014 status changes on this order should notify them on WhatsApp." })), order.giftWrapAddon && (_jsx(Chip, { icon: _jsx(Gift, { size: 12 }), label: isDetail && money(order.giftWrapFee) ? `Gift wrap · ${money(order.giftWrapFee)}` : "Gift wrap", tone: "brand", title: "This parcel must be gift-wrapped before dispatch." })), order.shipmentProtectionAddon && (_jsx(Chip, { icon: _jsx(ShieldCheck, { size: 12 }), label: isDetail && money(order.shipmentProtectionFee) ? `Protected · ${money(order.shipmentProtectionFee)}` : "Protected", tone: "info", title: "Shipment protection purchased \u2014 loss or damage in transit is covered, claimed against the held funds." })), order.saleProtectionAddon && (_jsx(Chip, { icon: _jsx(ShieldAlert, { size: 12 }), label: isDetail && money(order.saleProtectionFee) ? `Sale protected · ${money(order.saleProtectionFee)}` : "Sale protected", tone: "info", title: "Sale protection purchased \u2014 if the item is not as described the buyer is refunded, no questions asked." })), hasCoupon && (_jsx(Chip, { icon: _jsx(Tag, { size: 12 }), label: isDetail && money(order.couponDiscount)
                             ? `${order.couponCode} · −${money(order.couponDiscount)}`
                             : order.couponCode, tone: "success", title: `Coupon ${order.couponCode} applied to this order.` }))] }), isDetail && order.giftWrapAddon && order.giftWrapMessage && (_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsx(Text, { size: "xs", color: "muted", weight: "semibold", transform: "uppercase", className: "tracking-wide", children: "Gift message" }), _jsx(Text, { size: "sm", color: "primary", className: "min-w-0 whitespace-pre-wrap break-words", children: order.giftWrapMessage })] }))] }));
 }

package/dist/features/orders/repository/orders.repository.d.ts

@@ -215,6 +215,10 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        whatsappNotifyAddon: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         giftWrapAddon: {
             canFilter: boolean;
             canSort: boolean;
@@ -335,6 +339,10 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        whatsappNotifyAddon: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         giftWrapAddon: {
             canFilter: boolean;
             canSort: boolean;

package/dist/features/orders/repository/orders.repository.js

@@ -1364,6 +1364,7 @@ OrderRepository.SELLER_SIEVE_FIELDS = {
     // Fulfilment flags. Filterable so "which of my orders need gift wrap?" is a
     // query against the orders themselves — the whole point of recording the
     // add-on on the order rather than keeping a side list of who asked for what.
+    whatsappNotifyAddon: { canFilter: true, canSort: false },
     giftWrapAddon: { canFilter: true, canSort: false },
     shipmentProtectionAddon: { canFilter: true, canSort: false },
     saleProtectionAddon: { canFilter: true, canSort: false },
@@ -1396,6 +1397,7 @@ OrderRepository.ADMIN_SIEVE_FIELDS = {
     // Same fulfilment flags as SELLER_SIEVE_FIELDS — admin needs to answer
     // "who opted into WhatsApp updates?" when a status change goes out, without
     // maintaining a parallel tracker.
+    whatsappNotifyAddon: { canFilter: true, canSort: false },
     giftWrapAddon: { canFilter: true, canSort: false },
     shipmentProtectionAddon: { canFilter: true, canSort: false },
     saleProtectionAddon: { canFilter: true, canSort: false },

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

@@ -822,6 +822,10 @@ export interface OrderDocument extends BaseDocument {
     codRemainingAmount?: number;
     /** COD handling fee charged to the buyer: min(subtotal × codHandlingFeePercent / 100, codHandlingFeeCap). Only set when paymentMethod === "cod". */
     codHandlingFee?: number;
+    /** Buyer opted into WhatsApp order-update messages at checkout (unchecked by default). */
+    whatsappNotifyAddon?: boolean;
+    /** Fee charged for the WhatsApp addon, decimal rupees — snapshot of siteSettings.commissions.whatsappNotifyFee at order time. */
+    whatsappNotifyFee?: number;
     /** Buyer opted into gift wrapping at checkout (unchecked by default). */
     giftWrapAddon?: boolean;
     /** Fee charged for gift wrap, decimal rupees — snapshot of siteSettings.commissions.giftWrapFee at order time. */

package/dist/features/orders/types/index.d.ts

@@ -231,12 +231,15 @@ export interface Order {
     /**
      * Paid add-ons the buyer opted into for THIS order (= this store).
      *
-     * These are operational flags, not just billing records:
-     * `giftWrapAddon`/`shipmentProtectionAddon` are what
+     * These are operational flags, not just billing records: `whatsappNotifyAddon`
+     * is what the status-change notifier checks to decide whether to send a
+     * WhatsApp message, and `giftWrapAddon`/`shipmentProtectionAddon` are what
      * the packer needs to see before dispatch. They live on the order itself and
      * are filterable (`orders` SIEVE_FIELDS) precisely so nobody has to keep a
      * separate list of who asked for what.
      */
+    whatsappNotifyAddon?: boolean;
+    whatsappNotifyFee?: number;
     giftWrapAddon?: boolean;
     giftWrapFee?: number;
     /** The buyer's gift message — the packer has to physically include this. */

package/dist/features/promotions/components/AttachedCouponsSection.d.ts

@@ -0,0 +1,30 @@
+import type { AttachedCoupon } from "../constants/attached-coupons";
+export interface AttachedCouponsSectionProps {
+    /** Already resolved, already filtered — see `getAttachedCoupons`. */
+    coupons: AttachedCoupon[];
+    /** Section heading. Events and blog posts word this differently. */
+    title?: string;
+    /** Optional one-line lead-in under the heading. */
+    description?: string;
+}
+/**
+ * The coupons a piece of content advertises — events and blog posts alike.
+ *
+ * Copy-code only, by design: the reader takes the code to checkout, where
+ * every existing validation, per-user limit and stacking rule already applies
+ * against a real cart. An "apply to cart" button here would have to reproduce
+ * `detectCouponConflict`'s one-seller-coupon-per-store-plus-one-admin rule and
+ * explain its refusals on a page that knows nothing about the cart.
+ *
+ * 🛑 Renders NOTHING when there are no coupons — not an empty state. This sits
+ * inside an article or an event description, and a "no coupons available" box
+ * on the 95% of posts that never had one is noise that makes the 5% harder to
+ * notice.
+ *
+ * 🛑 It deliberately does NOT label which seller a coupon belongs to, even
+ * though `CouponDocument` carries `scope`/`storeId`. A reader cannot act on
+ * that: the coupon either applies to their cart or it does not, and checkout
+ * is where that is decided and explained. Printing a store name here would
+ * imply a scope the card cannot actually enforce.
+ */
+export declare function AttachedCouponsSection({ coupons, title, description, }: AttachedCouponsSectionProps): import("react").JSX.Element | null;

package/dist/features/promotions/components/AttachedCouponsSection.js

@@ -0,0 +1,99 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+import { Badge, Div, Grid, Heading, Stack, Text } from "../../../ui/index.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+import { CouponCodeCopyRow } from "./CouponCodeCopyRow.js";
+/**
+ * Headline summary of what a coupon gives — "25% off", "₹200 off",
+ * "Free shipping".
+ *
+ * 🛑 `type` is a plain `string` here, not the `CouponType` union, because this
+ * renders a PROJECTION of a document rather than the document. That is a
+ * deliberate trade: a new coupon type added upstream falls through to the
+ * coupon's own `name` instead of failing to compile. The alternative —
+ * `Record<CouponType, …>` — is the right shape when the exhaustiveness is the
+ * point (Root Cause #61), and the wrong one across a serialisation boundary
+ * where the value has already been stringified.
+ */
+function summarise(coupon) {
+    switch (coupon.type) {
+        case "percentage":
+            return `${coupon.discountValue}% off`;
+        case "fixed":
+            return `${formatCurrency(coupon.discountValue, "INR")} off`;
+        case "free_shipping":
+            return "Free shipping";
+        case "points_earn":
+            return `${coupon.discountValue}% back in points`;
+        default:
+            // buy_x_get_y and anything added later: the name already says it.
+            return null;
+    }
+}
+/** "Min. spend ₹999 · Up to ₹500 off · Ends 10 Nov" — only the parts that exist. */
+function conditionsOf(coupon) {
+    const parts = [];
+    if (coupon.minPurchase)
+        parts.push(`Min. spend ${formatCurrency(coupon.minPurchase, "INR")}`);
+    if (coupon.maxDiscount)
+        parts.push(`Up to ${formatCurrency(coupon.maxDiscount, "INR")} off`);
+    /*
+     * 🛑 An absent `endsAt` means NO END DATE, not "expired" — it is `undefined`
+     * for every open-ended coupon. Rendering "Expired" here would libel every
+     * one of them, and rendering nothing is correct: there is no deadline to
+     * report. Expiry is not this component's job at all; `getAttachedCoupons`
+     * has already dropped anything past its window.
+     */
+    if (coupon.endsAt) {
+        parts.push(`Ends ${new Date(coupon.endsAt).toLocaleDateString("en-IN", { day: "numeric", month: "short" })}`);
+    }
+    return parts.length > 0 ? parts.join(" · ") : null;
+}
+/**
+ * The coupons a piece of content advertises — events and blog posts alike.
+ *
+ * Copy-code only, by design: the reader takes the code to checkout, where
+ * every existing validation, per-user limit and stacking rule already applies
+ * against a real cart. An "apply to cart" button here would have to reproduce
+ * `detectCouponConflict`'s one-seller-coupon-per-store-plus-one-admin rule and
+ * explain its refusals on a page that knows nothing about the cart.
+ *
+ * 🛑 Renders NOTHING when there are no coupons — not an empty state. This sits
+ * inside an article or an event description, and a "no coupons available" box
+ * on the 95% of posts that never had one is noise that makes the 5% harder to
+ * notice.
+ *
+ * 🛑 It deliberately does NOT label which seller a coupon belongs to, even
+ * though `CouponDocument` carries `scope`/`storeId`. A reader cannot act on
+ * that: the coupon either applies to their cart or it does not, and checkout
+ * is where that is decided and explained. Printing a store name here would
+ * imply a scope the card cannot actually enforce.
+ */
+export function AttachedCouponsSection({ coupons, title = "Coupons", description, }) {
+    /*
+     * 🛑 `useId`, not a literal. This component is reusable and nothing stops a
+     * page mounting it twice — a hardcoded id would then appear on two elements
+     * and `aria-labelledby` would resolve to whichever came first, silently
+     * mislabelling the second section. React generates one id per instance.
+     *
+     * Called before the empty-return below because it is a HOOK: an early
+     * return above it would change the hook order between a post with coupons
+     * and one without.
+     */
+    const headingId = useId();
+    if (coupons.length === 0)
+        return null;
+    return (_jsxs(Stack, { gap: "md", "aria-labelledby": headingId, children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { id: headingId, level: 2, weight: "semibold", size: "xl", children: title }), description ? (_jsx(Text, { size: "sm", color: "muted", children: description })) : null] }), _jsx(Grid, { cols: "cardsWide", gap: "md", children: coupons.map((coupon) => {
+                    const summary = summarise(coupon);
+                    const conditions = conditionsOf(coupon);
+                    /*
+                     * `surface="card"` already carries the border, radius and shadow —
+                     * adding `border=` / `rounded=` beside it emits a second, competing
+                     * set of utilities, and with `important: true` in both Tailwind
+                     * configs the winner is decided by emission order rather than by
+                     * anything readable here (Root Cause #79).
+                     */
+                    return (_jsx(Div, { surface: "card", padding: "card", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Stack, { gap: "xs", children: [summary ? (_jsx(Div, { children: _jsx(Badge, { variant: "primary", children: summary }) })) : null, _jsx(Text, { weight: "semibold", children: coupon.name }), coupon.description ? (_jsx(Text, { size: "sm", color: "muted", children: coupon.description })) : null] }), _jsx(CouponCodeCopyRow, { code: coupon.code, ariaContext: coupon.name }), conditions ? (_jsx(Text, { size: "xs", color: "muted", children: conditions })) : null] }) }, coupon.id));
+                }) })] }));
+}

package/dist/features/promotions/components/CouponCodeCopyRow.d.ts

@@ -0,0 +1,19 @@
+export interface CouponCodeCopyRowProps {
+    /** The code to copy. Rendered verbatim — it is what the buyer must type. */
+    code: string;
+    /** Accessible context, e.g. the coupon name. Appended to the button label for screen readers. */
+    ariaContext?: string;
+}
+/**
+ * The code + "Copy code" row. ONE implementation, shared by `EventOfferCard`
+ * (offer events, one coupon) and `AttachedCouponsSection` (events and blog
+ * posts, several).
+ *
+ * Extracted rather than copied: this is the second consumer, and the
+ * Duplication Framework's keep-it rule ("Rule of Three — two copies is
+ * observation") is outranked here by its consolidate rule #2, the bug-fix
+ * multiplier. The clipboard call has a real failure mode — it is denied
+ * outright on insecure origins and by permission — and a fix to that handling
+ * in one copy would silently not reach the other.
+ */
+export declare function CouponCodeCopyRow({ code, ariaContext }: CouponCodeCopyRowProps): import("react").JSX.Element;

package/dist/features/promotions/components/CouponCodeCopyRow.js

@@ -0,0 +1,39 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { normalizeError } from "../../../errors/normalize.js";
+import { Code, Row } from "../../../ui/index.js";
+import { Button } from "../../../ui/components/Button.js";
+/**
+ * The code + "Copy code" row. ONE implementation, shared by `EventOfferCard`
+ * (offer events, one coupon) and `AttachedCouponsSection` (events and blog
+ * posts, several).
+ *
+ * Extracted rather than copied: this is the second consumer, and the
+ * Duplication Framework's keep-it rule ("Rule of Three — two copies is
+ * observation") is outranked here by its consolidate rule #2, the bug-fix
+ * multiplier. The clipboard call has a real failure mode — it is denied
+ * outright on insecure origins and by permission — and a fix to that handling
+ * in one copy would silently not reach the other.
+ */
+export function CouponCodeCopyRow({ code, ariaContext }) {
+    const [copied, setCopied] = useState(false);
+    const copyCode = async () => {
+        try {
+            await navigator.clipboard.writeText(code);
+            setCopied(true);
+            setTimeout(() => setCopied(false), 2000);
+        }
+        catch (_err) {
+            /*
+             * Clipboard access is denied outright on insecure origins and by user
+             * permission. The button simply never flips to "Copied", and the code is
+             * still on screen to select by hand — so the failure costs convenience,
+             * never the ability to use the coupon. Nothing is shown to the user,
+             * because there is nothing they could do about it.
+             */
+            void normalizeError(_err);
+        }
+    };
+    return (_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: code }), _jsx(Button, { type: "button", variant: "outline", onClick: copyCode, "aria-label": ariaContext ? `Copy coupon code ${code} — ${ariaContext}` : `Copy coupon code ${code}`, children: copied ? "Copied!" : "Copy code" })] }));
+}

package/dist/features/promotions/components/index.d.ts

@@ -1,3 +1,7 @@
+export { AttachedCouponsSection } from "./AttachedCouponsSection";
+export type { AttachedCouponsSectionProps } from "./AttachedCouponsSection";
+export { CouponCodeCopyRow } from "./CouponCodeCopyRow";
+export type { CouponCodeCopyRowProps } from "./CouponCodeCopyRow";
 export { CouponCard } from "./CouponCard";
 export { CouponHelpDetails } from "./CouponHelpDetails";
 export type { CouponHelpDetailsProps } from "./CouponHelpDetails";

package/dist/features/promotions/components/index.js

@@ -1,3 +1,5 @@
+export { AttachedCouponsSection } from "./AttachedCouponsSection.js";
+export { CouponCodeCopyRow } from "./CouponCodeCopyRow.js";
 export { CouponCard } from "./CouponCard.js";
 export { CouponHelpDetails } from "./CouponHelpDetails.js";
 export { CouponsIndexListing } from "./CouponsIndexListing.js";

package/dist/features/promotions/constants/attached-coupons.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Attached coupons — the contract shared by every layer that carries a set of
+ * coupon ids on a piece of CONTENT (`EventDocument.couponIds`,
+ * `BlogPostDocument.couponIds`).
+ *
+ * This file is deliberately dependency-free: the Zod write schemas, the admin
+ * editors, the repository's batch read and the public renderer all import the
+ * cap from here, so the number cannot drift between what an editor may save
+ * and what a page is willing to read. A cap enforced in one of those four
+ * places is not a cap.
+ */
+/**
+ * Most coupons one event or blog post may carry.
+ *
+ * 🛑 This is a Rule #6 bound, not a style preference. The public event and
+ * blog pages resolve these ids in a Server Component, so the number is a
+ * direct multiplier on a guest-reachable read. Ten is already generous for a
+ * promotion readers are expected to scan; the write schemas reject more, and
+ * `couponsRepository.findByIds` re-clamps so a document hand-edited in the
+ * Firestore console still cannot widen the read.
+ *
+ * Raising it means re-checking both: the schemas AND the repository.
+ */
+export declare const ATTACHED_COUPON_MAX = 10;
+/**
+ * The public projection of a coupon when it is attached to content.
+ *
+ * 🛑 This is an ALLOW-LIST, and the reason it exists is Root Cause #70: a
+ * public payload built by spreading a document and deleting keys publishes
+ * every field nobody thought to delete — including fields the TypeScript
+ * interface never declared. `CouponDocument` carries `usage.currentUsage`,
+ * `analytics.totalRevenue`, `analytics.totalDiscount`, the whole
+ * `restrictions` block and `createdBy`; none of that is a reader's business,
+ * and `analytics.*` is seller revenue.
+ *
+ * Note the existing `GET /api/coupons` returns whole documents. That is
+ * pre-existing and out of scope here — but it is precisely why this path
+ * starts with a projection instead of inheriting the habit.
+ */
+export interface AttachedCoupon {
+    id: string;
+    code: string;
+    name: string;
+    description: string;
+    /** `percentage` | `fixed` | `free_shipping` | `buy_x_get_y` | `points_earn` */
+    type: string;
+    /** The headline number: percent for `percentage`, rupees for `fixed`. */
+    discountValue: number;
+    /** Cap on a percentage discount, in rupees. */
+    maxDiscount?: number;
+    /** Minimum cart value before the coupon applies, in rupees. */
+    minPurchase?: number;
+    /** ISO string — `undefined` means no end date, NOT "expired". */
+    endsAt?: string;
+}

package/dist/features/promotions/constants/attached-coupons.js

@@ -0,0 +1,24 @@
+/**
+ * Attached coupons — the contract shared by every layer that carries a set of
+ * coupon ids on a piece of CONTENT (`EventDocument.couponIds`,
+ * `BlogPostDocument.couponIds`).
+ *
+ * This file is deliberately dependency-free: the Zod write schemas, the admin
+ * editors, the repository's batch read and the public renderer all import the
+ * cap from here, so the number cannot drift between what an editor may save
+ * and what a page is willing to read. A cap enforced in one of those four
+ * places is not a cap.
+ */
+/**
+ * Most coupons one event or blog post may carry.
+ *
+ * 🛑 This is a Rule #6 bound, not a style preference. The public event and
+ * blog pages resolve these ids in a Server Component, so the number is a
+ * direct multiplier on a guest-reachable read. Ten is already generous for a
+ * promotion readers are expected to scan; the write schemas reject more, and
+ * `couponsRepository.findByIds` re-clamps so a document hand-edited in the
+ * Firestore console still cannot widen the read.
+ *
+ * Raising it means re-checking both: the schemas AND the repository.
+ */
+export const ATTACHED_COUPON_MAX = 10;

package/dist/features/promotions/repository/coupons.repository.d.ts

@@ -27,6 +27,26 @@ export declare class CouponsRepository extends BaseRepository<CouponDocument> {
      * @returns Promise<CouponDocument | null>
      */
     getCouponByCode(code: string): Promise<CouponDocument | null>;
+    /**
+     * Batch-read coupons by id, for content that ATTACHES a set of them
+     * (`EventDocument.couponIds`, `BlogPostDocument.couponIds`).
+     *
+     * 🛑 ONE `getAll`, never a loop of `findById`. A blog post carrying six
+     * coupons would otherwise be six sequential round trips on a public,
+     * ISR-regenerated page — Rule #6 budgets about three for a whole request.
+     *
+     * 🛑 Order is PRESERVED and missing ids are DROPPED, not nulled — the same
+     * contract as `categoriesRepository.findByIds`, deliberately, so the two
+     * batch readers in this codebase cannot behave differently. A content
+     * editor's ordering is the display order, and a coupon that was deleted
+     * after being attached must not render as a hole in the grid.
+     *
+     * Bounded at `ATTACHED_COUPON_MAX`. The cap is the reason this is safe to
+     * call from a Server Component: the write schemas enforce the same number,
+     * so a hand-edited Firestore document cannot turn a public page into an
+     * unbounded read.
+     */
+    findByIds(ids: string[]): Promise<CouponDocument[]>;
     /**
      * Get all active coupons
      *

package/dist/features/promotions/repository/coupons.repository.js

@@ -9,6 +9,7 @@ import { serverLogger } from "../../../monitoring/server-logger.js";
  */
 import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
 import { COUPONS_COLLECTION, COUPON_FIELDS, isValidCouponCode, isCouponValid, canUserUseCoupon, calculateDiscount, createCouponId, } from "../schemas/index.js";
+import { ATTACHED_COUPON_MAX } from "../constants/attached-coupons.js";
 import { USER_COLLECTION } from "../../auth/schemas/index.js";
 import { DatabaseError } from "../../../errors/index.js";
 import { increment, arrayUnion, serverTimestamp } from "../../../contracts/field-ops.js";
@@ -71,6 +72,44 @@ export class CouponsRepository extends BaseRepository {
             throw new DatabaseError(`Failed to retrieve coupon by code: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
+    /**
+     * Batch-read coupons by id, for content that ATTACHES a set of them
+     * (`EventDocument.couponIds`, `BlogPostDocument.couponIds`).
+     *
+     * 🛑 ONE `getAll`, never a loop of `findById`. A blog post carrying six
+     * coupons would otherwise be six sequential round trips on a public,
+     * ISR-regenerated page — Rule #6 budgets about three for a whole request.
+     *
+     * 🛑 Order is PRESERVED and missing ids are DROPPED, not nulled — the same
+     * contract as `categoriesRepository.findByIds`, deliberately, so the two
+     * batch readers in this codebase cannot behave differently. A content
+     * editor's ordering is the display order, and a coupon that was deleted
+     * after being attached must not render as a hole in the grid.
+     *
+     * Bounded at `ATTACHED_COUPON_MAX`. The cap is the reason this is safe to
+     * call from a Server Component: the write schemas enforce the same number,
+     * so a hand-edited Firestore document cannot turn a public page into an
+     * unbounded read.
+     */
+    async findByIds(ids) {
+        const unique = Array.from(new Set(ids.filter(Boolean))).slice(0, ATTACHED_COUPON_MAX);
+        if (unique.length === 0)
+            return [];
+        try {
+            const refs = unique.map((id) => this.db.collection(this.collection).doc(id));
+            const snaps = await this.db.getAll(...refs);
+            return snaps.filter((s) => s.exists).map((s) => this.mapDoc(s));
+        }
+        catch (error) {
+            const e = normalizeError(error);
+            /*
+             * `kind` and a COUNT, never the raw message and never the ids —
+             * Root Cause #86 (a thrown message is written for a developer and this
+             * one can reach a user through a 500) plus Hobby's ~4 KB/s log budget.
+             */
+            throw new DatabaseError(`Failed to batch-read ${unique.length} coupon(s) by id (${e.kind})`);
+        }
+    }
     /**
      * Get all active coupons
      *

package/dist/features/promotions/schemas/attached-coupons.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+/**
+ * The write shape for any `couponIds`-style field — one definition, imported
+ * by the event schema, the blog schema and both admin API routes.
+ *
+ * 🛑 ONE definition on purpose. Four hand-written `z.array(z.string())`s would
+ * be four chances for the cap to drift, and a cap enforced on three of four
+ * write paths is not a cap — the fourth is simply the way in. This is the same
+ * failure as the ten hand-maintained copies of the `ListingType` union in
+ * Root Cause #61.
+ *
+ * `.max()` carries a message because this one is reachable by a human in an
+ * admin form, and "Too big: expected array to have <=10 items" is not an
+ * instruction.
+ */
+export declare const attachedCouponIdsSchema: z.ZodType<string[] | undefined>;
+/**
+ * Dedupe and drop blanks. Still ONE definition — it moved out of the schema,
+ * it did not become four copies.
+ *
+ * 🛑 WHY IT IS NOT A `.transform()` ANY MORE, which is where it started:
+ *
+ * `.transform()` wraps the schema in `z.ZodEffects`, and **`ZodEffects` is a
+ * zod 3 type that does not exist in zod 4**. This repo runs both — appkit is
+ * pinned to zod 3.25.76 (peer `^3.24.0`) while the consumer app resolves zod
+ * 4.4.3 — so appkit's emitted `.d.ts` referenced a type the consumer's zod
+ * cannot resolve, the inference collapsed to `unknown`, and four admin routes
+ * failed to typecheck with `Type 'unknown' is not assignable to type
+ * 'string[] | undefined'`.
+ *
+ * The declared peer range is the thing that is actually wrong here, and
+ * aligning the two majors is a real migration rather than a drive-by. Until
+ * then: no schema crossing the package boundary may use `.transform()`,
+ * `.refine()` or `.preprocess()`, because all three produce `ZodEffects`.
+ *
+ * Callers apply this after parsing, which is the same boundary the dedupe
+ * always ran at — the route, not the client.
+ */
+export declare function dedupeAttachedCouponIds(ids: readonly string[] | undefined): string[] | undefined;