@mohasinac/appkit 4.63.4 → 4.64.0

package/dist/features/events/utils/event-charts.js

@@ -0,0 +1,172 @@
+/**
+ * Chart specs for event pages — pure builders, no React, no recharts.
+ *
+ * Kept free of any import that reaches the DOM so a Server Component can call
+ * these and hand the result to `<Chart>`, whose own `"use client"` boundary is
+ * internal (`chart-spec.ts` is deliberately the same shape of module).
+ *
+ * ## 🛑 EVERY NUMBER HERE IS MEASURED, NOT ILLUSTRATIVE
+ *
+ * A chart asserts "we measured this". So each builder returns `null` rather
+ * than a plausible-looking shape when it has nothing real to plot — an absent
+ * chart says "not enough data yet", a flat or invented one says "we measured,
+ * and this is the result", which is a different and false claim.
+ *
+ * @tag domain:events
+ * @tag layer:utils
+ */
+import { calculateDiscount } from "../../promotions/schemas/firestore.js";
+/** A poll needs at least one real vote before a bar chart means anything. */
+const MIN_VOTES = 1;
+/**
+ * Poll results as bars.
+ *
+ * The data already existed and was rendered as the plain string
+ * "12 votes (34%)" — `getEventPollResults` computes both server-side and
+ * `EventLeaderboard` printed them in a flex row. This is the same numbers,
+ * shaped so the differences between options are visible at a glance.
+ */
+export function buildPollChart(
+// Structural, not the full `PollConfig`: this reads `options` and nothing
+// else, and the page carries a narrower local declaration of its own.
+pollConfig, results) {
+    if (!pollConfig?.options?.length || !results?.length)
+        return null;
+    const byId = new Map(results.map((r) => [r.optionId, r.count]));
+    const total = results.reduce((sum, r) => sum + r.count, 0);
+    if (total < MIN_VOTES)
+        return null;
+    return {
+        kind: "bar",
+        title: "Votes so far",
+        categories: pollConfig.options.map((o) => o.label),
+        series: [{ label: "Votes", values: pollConfig.options.map((o) => byId.get(o.id) ?? 0) }],
+        unit: "votes",
+        caption: `${total} vote${total === 1 ? "" : "s"} counted.`,
+    };
+}
+/**
+ * The basket sizes the savings chart compares across.
+ *
+ * 🛑 THE RANGE IS CHOSEN TO SHOW THE CROSSOVER, which is the only thing this
+ * chart can usefully tell someone. At ₹2,000 the two 10% codes TIE at ₹200 and
+ * their caps are irrelevant; an uncapped 5% only overtakes a ₹500-capped 10%
+ * once the basket passes ₹10,000. A single-basket bar chart would show three
+ * bars, two of them identical, and teach nothing.
+ */
+const BASKET_SIZES = [1000, 2000, 5000, 12000];
+const INR = new Intl.NumberFormat("en-IN", { maximumFractionDigits: 0 });
+/**
+ * What each cashback coupon actually saves, across basket sizes.
+ *
+ * 🛑 COMPUTED WITH THE REAL `calculateDiscount`, never a re-derived formula.
+ * That function is where `maxDiscount`, `minPurchase` and the tier table are
+ * honoured; computing the percentage inline here would silently ignore all three and
+ * overstate every capped code. Root Cause #75 is a money rule hand-copied into
+ * six places, where the copies never learned about a branch added later.
+ *
+ * 🛑 `free_shipping` AND `buy_x_get_y` ARE EXCLUDED, not plotted at zero.
+ * `calculateDiscount` returns 0 for free shipping BY DESIGN — the waiver is a
+ * shipping line, not a subtotal discount — and a BOGO's value depends on the
+ * basket's composition, not its total (₹500 on 4x₹500, ₹0 on 2x₹1,000). A bar
+ * at zero for either would read as "this code saves you nothing", which is a
+ * lie by omission. They belong in the caption, and that is where they go.
+ */
+/**
+ * 🛑 TAKES THE PUBLIC PROJECTION, NOT THE DOCUMENT — and still calls the
+ * real `calculateDiscount`.
+ *
+ * The event page only ever holds `AttachedCoupon`, the allow-list
+ * projection (Root Cause #70 — the full document carries fields no public
+ * surface should see). That projection carries exactly the four facts the
+ * calculator needs, under different names: `type`, `discountValue`,
+ * `maxDiscount`, `minPurchase`.
+ *
+ * So this MAPS NAMES and delegates. The tempting shortcut — computing
+ * the percentage inline right here, because the projection makes it
+ * easy — is precisely Root Cause #75: a money rule re-derived at a call
+ * site, which then never learns about the cap, the minimum or the tier
+ * table the real function honours.
+ */
+function toCalculable(c) {
+    return {
+        type: c.type,
+        discount: {
+            value: c.discountValue,
+            maxDiscount: c.maxDiscount,
+            minPurchase: c.minPurchase,
+        },
+    };
+}
+export function buildCouponSavingsChart(coupons) {
+    const plottable = coupons.filter((c) => c.type === "percentage" || c.type === "fixed");
+    if (plottable.length === 0)
+        return null;
+    const excluded = coupons
+        .filter((c) => !plottable.includes(c))
+        .map((c) => c.code);
+    const series = plottable.map((coupon) => ({
+        label: coupon.code,
+        values: BASKET_SIZES.map((basket) => Math.round(calculateDiscount(toCalculable(coupon), basket))),
+    }));
+    // Every code saving nothing at every size means the minimums are all above
+    // our largest basket — a chart of four empty groups.
+    if (series.every((s) => s.values.every((v) => v === 0)))
+        return null;
+    const captionParts = ["One code per order — this is a choose-one comparison."];
+    if (excluded.length) {
+        captionParts.push(`${excluded.join(" and ")} ${excluded.length === 1 ? "is" : "are"} not shown: ` +
+            `their value depends on delivery or on what is in the basket, not on the total.`);
+    }
+    return {
+        kind: "groupedBar",
+        title: "What each code saves",
+        categories: BASKET_SIZES.map((b) => `₹${INR.format(b)}`),
+        series,
+        unit: "₹",
+        caption: captionParts.join(" "),
+    };
+}
+/**
+ * Likes over time. Data comes from `getLikeTrend`, which returns `null` below
+ * `LIKE_TREND_MIN_POINTS` so a two-like event plots nothing rather than a flat
+ * line with axes.
+ */
+export function buildLikeTrendChart(trend) {
+    if (!trend)
+        return null;
+    return {
+        kind: "area",
+        title: "Interest over the last fortnight",
+        categories: trend.categories,
+        series: [{ label: "Likes", values: trend.values }],
+        unit: "likes",
+        caption: "Likes received per day.",
+    };
+}
+/**
+ * Time elapsed in the sale window, and redemptions against a real cap.
+ *
+ * 🛑 `claimedPercent` IS null UNLESS A REAL CAP EXISTS. `usage.totalLimit` is
+ * optional, and an uncapped coupon has no denominator — rendering a progress
+ * bar against an invented 100 would show a bar filling toward a limit nobody
+ * set. Absent is the honest state and the caller renders only the countdown.
+ */
+export function buildSaleProgress(startsAt, endsAt, coupon, now = new Date()) {
+    if (!startsAt || !endsAt)
+        return null;
+    const start = startsAt.getTime();
+    const end = endsAt.getTime();
+    if (!(end > start))
+        return null;
+    const elapsed = ((now.getTime() - start) / (end - start)) * 100;
+    const limit = coupon?.usage?.totalLimit;
+    const used = coupon?.usage?.currentUsage ?? 0;
+    const hasCap = typeof limit === "number" && limit > 0;
+    return {
+        elapsedPercent: Math.min(100, Math.max(0, Math.round(elapsed))),
+        endsAt: now.getTime() < end ? endsAt : null,
+        claimedPercent: hasCap ? Math.min(100, Math.round((used / limit) * 100)) : null,
+        claimedLabel: hasCap ? `${INR.format(used)} of ${INR.format(limit)} claimed` : null,
+    };
+}

package/dist/features/faq/constants/help-guides.js

@@ -52,6 +52,15 @@ export const FAQ_CATEGORY_HELP_GUIDE = {
     // live.
     scam_awareness: { path: "/help/account", label: "Account & Safety guide" },
     fees_and_taxes: { path: "/help/shopping", label: "Shopping & Checkout guide" },
+    /*
+     * The BUYER-facing badge page, not `/seller-guide`.
+     *
+     * This map sits on the public FAQ page, so its audience is a visitor rather
+     * than a seller — and "what does Trusted Seller mean" is the question they
+     * are most likely to have arrived with. A seller reading these FAQs still
+     * gets there: the badge page links on to the seller guide.
+     */
+    selling: { path: "/help/seller-badges", label: "What seller badges mean" },
     technical_support: null,
     general: null,
 };

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

@@ -31,6 +31,7 @@ export const FAQ_CATEGORY_LABELS = {
     general: "General Questions",
     scam_awareness: "Scam Awareness",
     fees_and_taxes: "Fees & Taxes",
+    selling: "Selling & Seller Badges",
 };
 export const DEFAULT_FAQ_DATA = {
     showOnHomepage: false,

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

@@ -1,5 +1,24 @@
 export type FAQAnswerFormat = "plain" | "markdown" | "html";
 export type FAQCategory = "orders_payment" | "shipping_delivery" | "returns_refunds" | "product_information" | "account_security" | "technical_support" | "general" | "scam_awareness"
+/**
+ * Questions asked by SELLERS, and the buyer-facing questions about them —
+ * how to open a store, what the badges mean, how standing is earned and
+ * lost.
+ *
+ * Kept out of `general` for the reason `fees_and_taxes` was: these have a
+ * distinct audience. A buyer browsing FAQs is not looking for "how do I
+ * list an item", and a seller looking for it should not have to read past
+ * twenty buyer questions to find it.
+ *
+ * 🛑 Adding a member here is FIVE coordinated edits, three of which are
+ * compile-checked and two of which are not: this union,
+ * `FAQ_CATEGORY_LABELS`, the `Record<FAQCategory, …>` in
+ * `constants/help-guides.ts` — and then the HARDCODED category arrays in
+ * `src/app/[locale]/faqs/page.tsx` and `faqs/[category]/page.tsx`, which
+ * nothing type-checks. A comment in those files records `fees_and_taxes`
+ * needing exactly this.
+ */
+ | "selling"
 /**
  * D6b. Money questions, kept out of `orders_payment` on purpose: that
  * category is about an ORDER (where is it, how do I pay, can I cancel),

package/dist/features/homepage/components/BrandsSection.js

@@ -29,7 +29,31 @@ function BrandLogo({ brand }) {
     const iconSrc = brand.display?.icon;
     const coverImage = brand.display?.coverImage;
     const initial = brand.name[0]?.toUpperCase() ?? "?";
-    return (_jsxs(Link, { href: ROUTES.PUBLIC.CATEGORY_DETAIL(brand.slug), className: "flex h-32 w-36 flex-col items-center justify-center gap-[var(--appkit-space-2)] rounded-xl border p-[var(--appkit-space-3)] shadow-sm transition-all hover:border-primary-300 hover:shadow-md border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] md:h-40", children: [iconSrc || coverImage ? (_jsx(Image, { src: resolveMediaUrl(iconSrc ?? coverImage), alt: brand.name, width: 64, height: 64, className: "h-16 w-16 rounded object-contain" })) : (_jsx(Row, { textWeight: "bold", textSize: "sm", className: "h-16 w-16 bg-primary-100 text-primary-700 dark:bg-primary-900 dark:text-primary-300", align: "center", justify: "center", rounded: "lg", children: initial })), _jsx(Text, { className: "w-full truncate", color: "muted", size: "xs", weight: "medium", align: "start", children: brand.name })] }));
+    return (_jsxs(Link
+    /*
+     * 🛑 BRAND_DETAIL, not CATEGORY_DETAIL.
+     *
+     * A brand IS a `categoryType: "brand"` row, so `/categories/brand-hasbro`
+     * resolves just as `/brands/brand-hasbro` does — and both are indexable.
+     * This component was the one surface linking brands by the category path
+     * while every other surface used `/brands/…`, so the homepage shipped two
+     * different URLs for the same entity and split its signals between them.
+     * `/brands/{slug}` is the one the sitemap advertises and the one the
+     * brand page declares canonical.
+     */
+    , { 
+        /*
+         * 🛑 BRAND_DETAIL, not CATEGORY_DETAIL.
+         *
+         * A brand IS a `categoryType: "brand"` row, so `/categories/brand-hasbro`
+         * resolves just as `/brands/brand-hasbro` does — and both are indexable.
+         * This component was the one surface linking brands by the category path
+         * while every other surface used `/brands/…`, so the homepage shipped two
+         * different URLs for the same entity and split its signals between them.
+         * `/brands/{slug}` is the one the sitemap advertises and the one the
+         * brand page declares canonical.
+         */
+        href: ROUTES.PUBLIC.BRAND_DETAIL(brand.slug), className: "flex h-32 w-36 flex-col items-center justify-center gap-[var(--appkit-space-2)] rounded-xl border p-[var(--appkit-space-3)] shadow-sm transition-all hover:border-primary-300 hover:shadow-md border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] md:h-40", children: [iconSrc || coverImage ? (_jsx(Image, { src: resolveMediaUrl(iconSrc ?? coverImage), alt: brand.name, width: 64, height: 64, className: "h-16 w-16 rounded object-contain" })) : (_jsx(Row, { textWeight: "bold", textSize: "sm", className: "h-16 w-16 bg-primary-100 text-primary-700 dark:bg-primary-900 dark:text-primary-300", align: "center", justify: "center", rounded: "lg", children: initial })), _jsx(Text, { className: "w-full truncate", color: "muted", size: "xs", weight: "medium", align: "start", children: brand.name })] }));
 }
 export function BrandsSection({ title = "Top Brands", subtitle, limit = 12, viewMoreHref, viewMoreLabel = "All brands →", className = "", initialItems, cta, filters, autoScroll = true, scrollInterval = 4000, loop = true, }) {
     const themed = { textPrimary: THEMED_TEXT_PRIMARY };

package/dist/features/homepage/components/HeroCarousel.js

@@ -72,7 +72,16 @@ function getSlideHeightClass(height) {
 /** Renders the slide background — image, video, solid colour, or gradient. */
 function SlideBackground({ bg, legacy, mobileLegacy, isMobile, priority, }) {
     const effectiveBg = bg ?? (legacy ? { type: legacy.type, url: legacy.url } : undefined);
-    const mobileUrl = effectiveBg?.mobileUrl ?? (isMobile && mobileLegacy ? mobileLegacy.url : undefined);
+    /*
+     * 🛑 Both halves are gated on `isMobile`. `effectiveBg.mobileUrl` was read
+     * UNCONDITIONALLY, so any slide carrying a mobile crop served that
+     * phone-sized image to desktop too — a narrow picture stretched across a
+     * 1920px hero, and the desktop asset never loaded at all. The legacy half
+     * was already gated correctly, which is what made the asymmetry easy to miss.
+     */
+    const mobileUrl = isMobile
+        ? (effectiveBg?.mobileUrl ?? mobileLegacy?.url)
+        : undefined;
     const src = mobileUrl ?? effectiveBg?.url ?? "";
     if (!effectiveBg) {
         return _jsx(Div, { className: `${POSITION_FILL} bg-neutral-900` });
@@ -111,17 +120,25 @@ function CardBackground({ bg }) {
     return null;
 }
 function CarouselCardRenderer({ card, isMobile, push, }) {
-    const mobileZone = card.mobileZone;
-    const gridPos = isMobile && mobileZone
-        ? { gridRow: mobileZone <= 3 ? 1 : 2, gridColumn: mobileZone <= 3 ? mobileZone : mobileZone - 3 }
-        : resolveZoneToGrid(card.zone);
+    /*
+     * 🛑 On mobile the card takes NO explicit grid placement at all — the parent
+     * is a one-column auto-flow grid, so source order is the layout.
+     *
+     * The old branch mapped `mobileZone` to a `gridColumn`, which against a
+     * single declared column created an implicit column 2 and stacked every
+     * card into one cell. `mobileZone` was also typed `2 | 5` only, so it could
+     * not express a six-card slide even in principle. Zones are a desktop
+     * concept; a phone has one column and nothing to place into.
+     */
+    const gridPos = isMobile ? null : resolveZoneToGrid(card.zone);
     const hoverClass = getHoverClass(card.hover?.effect);
     const textAlign = card.content?.textAlign ?? "left";
     // audit-content-alignment-ok: admin-configurable per-card textAlign field, defaults to "left" — not a hardcoded center
     const textAlignClass = textAlign === "center" ? "text-center" : textAlign === "right" ? "text-right" : "text-left";
     return (_jsxs(Div, { className: `relative overflow-hidden transition-all duration-300 ${hoverClass}`, rounded: "lg", shadow: "lg", style: {
-            gridRow: String(gridPos.gridRow),
-            gridColumn: String(gridPos.gridColumn),
+            ...(gridPos
+                ? { gridRow: String(gridPos.gridRow), gridColumn: String(gridPos.gridColumn) }
+                : {}),
             minHeight: isMobile ? 100 : 140,
         }, children: [_jsx(CardBackground, { bg: card.background }), !card.isButtonOnly && (_jsxs(_Fragment, { children: [_jsx(Scrim, { direction: "bottom-up", intensity: "strong", className: POSITION_FILL }), _jsxs(Stack, { justify: "end", className: `${POSITION_FILL} md:p-[1.5rem] ${textAlignClass}`, padding: "xs", children: [card.content?.eyebrow && (_jsx(Text, { color: "inverse", shadow: "sm", className: "text-[10px] opacity-70 mb-0.5 tracking-wider", mdSize: "xs", transform: "uppercase", children: card.content.eyebrow })), card.content?.subtitle && (_jsx(Text, { color: "inverse", shadow: "sm", className: "hidden md:block opacity-90 mb-0.5 md:mb-2", mdSize: "sm", size: "xs", children: card.content.subtitle })), card.content?.title && (
                             // level={3}: a card sits INSIDE a slide, so it is subordinate to
@@ -202,15 +219,35 @@ export function HeroCarousel({ initialSlides, push, height, defaultAutoplayDelay
         onMouseEnter: pauseOnHover ? () => setIsPaused(true) : undefined, onMouseLeave: pauseOnHover ? () => setIsPaused(false) : undefined, onFocus: () => setIsPaused(true), onBlur: () => setIsPaused(false), tabIndex: 0, children: [_jsx(Div, { "aria-live": "polite", "aria-atomic": "true", className: "sr-only", children: `Slide ${currentSlide + 1} of ${slides.length}` }), _jsx(Div, { className: POSITION_FILL, children: _jsx(Div, { layout: "flex", ref: slidesRef, onScroll: handleSlidesScroll, className: "h-full overflow-x-auto scroll-smooth snap-x snap-mandatory [scrollbar-width:none] [&::-webkit-scrollbar]:hidden", style: { gap: 0 }, children: slides.map((slide, slideIndex) => {
                         const slideHeightClass = getSlideHeightClass(slide.settings?.height);
                         const hasCards = slide.cards && slide.cards.length > 0;
-                        return (_jsxs(Div, { className: `snap-start flex-none w-full relative self-stretch bg-neutral-900 ${slideHeightClass}`, children: [_jsx(Div, { className: "absolute bottom-2 left-2 z-10", children: _jsx(OwnerQuickActions, { resource: "CAROUSEL", placement: "card", recordLabel: slide.title ?? `Slide ${slideIndex + 1}`, editHref: String(ROUTES.ADMIN.CAROUSEL_EDIT(slide.id)) }) }), _jsx(Div, { className: POSITION_FILL, children: _jsx(SlideBackground, { bg: slide.background, legacy: slide.media, mobileLegacy: slide.mobileMedia, isMobile: isMobile, priority: slideIndex === 0 }) }), slide.overlay && (_jsxs(Div, { layout: "flex-col", align: "start", justify: "center", className: `${POSITION_FILL} text-left md:px-[4rem] lg:px-[8rem]`, padding: "x-lg", children: [slide.overlay.subtitle && (_jsx(Text, { color: "inverse", shadow: "sm", className: "stagger-1 opacity-80 mb-1 md:mb-2 tracking-widest", mdSize: "sm", size: "xs", transform: "uppercase", children: slide.overlay.subtitle })), slide.overlay.title && (
+                        return (_jsxs(Div, { className: `snap-start flex-none w-full relative self-stretch bg-neutral-900 ${slideHeightClass}`, children: [_jsx(Div, { className: "absolute bottom-2 left-2 z-10", children: _jsx(OwnerQuickActions, { resource: "CAROUSEL", placement: "card", 
+                                        /* Sits on the slide photograph — without this it renders
+                                         * the light `surface-elevated` chip, a pale rounded box
+                                         * floating on the artwork. `onMedia` selects the dark
+                                         * translucent backdrop that variant exists for. */
+                                        onMedia: true, recordLabel: slide.title ?? `Slide ${slideIndex + 1}`, editHref: String(ROUTES.ADMIN.CAROUSEL_EDIT(slide.id)) }) }), _jsx(Div, { className: POSITION_FILL, children: _jsx(SlideBackground, { bg: slide.background, legacy: slide.media, mobileLegacy: slide.mobileMedia, isMobile: isMobile, priority: slideIndex === 0 }) }), slide.overlay && slide.overlay.enabled !== false && (_jsxs(Div, { layout: "flex-col", align: "start", justify: "center", className: `${POSITION_FILL} text-left md:px-[4rem] lg:px-[8rem]`, padding: "x-lg", children: [slide.overlay.subtitle && (_jsx(Text, { color: "inverse", shadow: "sm", className: "stagger-1 opacity-80 mb-1 md:mb-2 tracking-widest", mdSize: "sm", size: "xs", transform: "uppercase", children: slide.overlay.subtitle })), slide.overlay.title && (
                                         // level={2}, NOT 1. The welcome section above this
                                         // carousel owns the page's single <h1>; a carousel that
                                         // emits one <h1> per slide gives the document as many
                                         // h1s as it has slides. `size` is independent of `level`,
                                         // so this changes the outline and not one pixel.
-                                        _jsx(Heading, { color: "inverse", level: 2, className: "stagger-2 font-display ! mb-2 md:mb-4 break-words", size: "4xl", shadow: "2xl", mdSize: "6xl", lgSize: "8xl", children: slide.overlay.title })), slide.overlay.description && (_jsx(Text, { color: "inverse", shadow: "sm", className: "stagger-3 opacity-90 mb-4 md:mb-8 max-w-2xl", mdSize: "lg", lgSize: "xl", size: "sm", children: slide.overlay.description })), slide.overlay.button && (_jsx(Div, { className: "stagger-4", children: _jsx(Button, { variant: slide.overlay.button.variant, size: "sm", onClick: makeButtonClickHandler(slide.overlay.button.link, slide.overlay.button.openInNewTab, push), children: slide.overlay.button.text }) }))] })), hasCards && (_jsx(Div, { className: `${POSITION_FILL} grid gap-[var(--appkit-space-2)] md:gap-[var(--appkit-space-4)] md:p-[var(--appkit-space-8)]`, padding: "md", style: {
-                                        gridTemplateRows: "repeat(2, 1fr)",
+                                        _jsx(Heading, { color: "inverse", level: 2, 
+                                            /*
+                                             * 🛑 `max-w-[16ch]` is load-bearing, not taste. The box
+                                             * is `absolute inset-0`, so with no cap the title runs
+                                             * the full slide width minus padding and an 8xl
+                                             * headline wraps into a wall. A character-based cap
+                                             * tracks the font size instead of guessing at pixels.
+                                             *
+                                             * `text-balance` evens the lines so a two-line title
+                                             * does not leave one word stranded on line two.
+                                             *
+                                             * (A stray bare `!` token sat in this className and
+                                             * generated nothing — removed.)
+                                             */
+                                            className: "stagger-2 font-display mb-2 md:mb-4 break-words text-balance max-w-[16ch] md:max-w-[18ch] lg:max-w-[20ch]", size: "4xl", shadow: "2xl", mdSize: "6xl", lgSize: "8xl", children: slide.overlay.title })), slide.overlay.description && (_jsx(Text, { color: "inverse", shadow: "sm", className: "stagger-3 opacity-90 mb-4 md:mb-8 max-w-2xl", mdSize: "lg", lgSize: "xl", size: "sm", children: slide.overlay.description })), slide.overlay.button && (_jsx(Div, { className: "stagger-4", children: _jsx(Button, { variant: slide.overlay.button.variant, size: "sm", onClick: makeButtonClickHandler(slide.overlay.button.link, slide.overlay.button.openInNewTab, push), children: slide.overlay.button.text }) }))] })), hasCards && (_jsx(Div, { className: `${POSITION_FILL} grid gap-[var(--appkit-space-2)] md:gap-[var(--appkit-space-4)] md:p-[var(--appkit-space-8)] overflow-y-auto`, padding: "md", style: {
+                                        gridTemplateRows: isMobile ? "auto" : "repeat(2, 1fr)",
                                         gridTemplateColumns: isMobile ? "1fr" : "repeat(3, 1fr)",
+                                        gridAutoFlow: "row",
                                         alignContent: "center",
                                         alignItems: "stretch",
                                     }, children: slide.cards.slice(0, 6).map((card) => (_jsx(CarouselCardRenderer, { card: card, isMobile: isMobile, push: push }, card.id))) }))] }, slide.id));

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/homepage/types/index.d.ts

@@ -125,6 +125,13 @@ export interface CarouselSlide {
     };
     cards: CarouselSlideCard[];
     overlay?: {
+        /**
+         * Absent means SHOWN — most stored overlays predate this flag. Only an
+         * explicit `false` hides it. The seed and `push-editorial-content.mjs`
+         * have always written `enabled: true`; the renderer simply never read it,
+         * so an admin switching it off changed nothing.
+         */
+        enabled?: boolean;
         title?: string;
         subtitle?: string;
         description?: string;

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/search/action-index/settings-entries.js

@@ -169,6 +169,15 @@ export const SITE_SETTINGS_ENTRIES = [
         tab: "notifications",
         kind: "toggle",
     },
+    {
+        slug: "whatsapp-notifications",
+        anchored: true,
+        label: "WhatsApp notifications",
+        description: "Send order updates over WhatsApp.",
+        keywords: ["whatsapp", "order updates", "meta"],
+        tab: "notifications",
+        kind: "toggle",
+    },
     {
         slug: "daily-digest",
         anchored: true,

package/dist/features/store-extensions/repository/store-extensions.repositories.d.ts

@@ -14,7 +14,7 @@
  */
 import { BaseRepository } from "../../../providers/db-firebase";
 import type { DocumentSnapshot } from "firebase-admin/firestore";
-import { type AnalyticsAlertDocument, type AnalyticsCardDocument, type ItemRequestDocument, type ItemRequestReply, type ListingTemplateDocument, type ModerationQueueDocument, type PayoutMethodDocument, type ReportDocument, type ShippingConfigDocument, type StoreCategoryDocument, type StoreGoogleConfigDocument } from "../schemas/firestore";
+import { type AnalyticsAlertDocument, type AnalyticsCardDocument, type ItemRequestDocument, type ItemRequestReply, type ListingTemplateDocument, type ModerationQueueDocument, type PayoutMethodDocument, type ReportDocument, type ShippingConfigDocument, type StoreCategoryDocument, type StoreGoogleConfigDocument, type StoreWhatsAppConfigDocument } from "../schemas/firestore";
 export declare class PayoutMethodsRepository extends BaseRepository<PayoutMethodDocument> {
     /**
      * Bank/UPI details, encrypted at rest by BaseRepository's write hooks.
@@ -103,6 +103,10 @@ export declare class ItemRequestsRepository extends BaseRepository<ItemRequestDo
      */
     appendReply(id: string, reply: ItemRequestReply): Promise<void>;
 }
+export declare class StoreWhatsAppConfigRepository extends BaseRepository<StoreWhatsAppConfigDocument> {
+    constructor();
+    getByStore(storeId: string): Promise<StoreWhatsAppConfigDocument | null>;
+}
 export declare class StoreGoogleConfigRepository extends BaseRepository<StoreGoogleConfigDocument> {
     constructor();
     getByStore(storeId: string): Promise<StoreGoogleConfigDocument | null>;
@@ -116,4 +120,5 @@ export declare const listingTemplatesRepository: ListingTemplatesRepository;
 export declare const moderationQueueRepository: ModerationQueueRepository;
 export declare const reportsRepository: ReportsRepository;
 export declare const itemRequestsRepository: ItemRequestsRepository;
+export declare const storeWhatsAppConfigRepository: StoreWhatsAppConfigRepository;
 export declare const storeGoogleConfigRepository: StoreGoogleConfigRepository;

package/dist/features/store-extensions/repository/store-extensions.repositories.js

@@ -15,7 +15,7 @@
 import { BaseRepository } from "../../../providers/db-firebase/index.js";
 import { arrayUnion, increment } from "../../../contracts/field-ops.js";
 import { decryptPiiFields } from "../../../security/pii-encrypt.js";
-import { ANALYTICS_ALERTS_COLLECTION, ANALYTICS_CARDS_COLLECTION, ITEM_REQUESTS_COLLECTION, LISTING_TEMPLATES_COLLECTION, MODERATION_QUEUE_COLLECTION, PAYOUT_METHODS_COLLECTION, REPORTS_COLLECTION, SHIPPING_CONFIGS_COLLECTION, STORE_CATEGORIES_COLLECTION, STORE_GOOGLE_CONFIG_COLLECTION, } from "../schemas/firestore.js";
+import { ANALYTICS_ALERTS_COLLECTION, ANALYTICS_CARDS_COLLECTION, ITEM_REQUESTS_COLLECTION, LISTING_TEMPLATES_COLLECTION, MODERATION_QUEUE_COLLECTION, PAYOUT_METHODS_COLLECTION, REPORTS_COLLECTION, SHIPPING_CONFIGS_COLLECTION, STORE_CATEGORIES_COLLECTION, STORE_GOOGLE_CONFIG_COLLECTION, STORE_WHATSAPP_CONFIG_COLLECTION, } from "../schemas/firestore.js";
 export class PayoutMethodsRepository extends BaseRepository {
     constructor() {
         super(PAYOUT_METHODS_COLLECTION);
@@ -149,6 +149,14 @@ export class ItemRequestsRepository extends BaseRepository {
         });
     }
 }
+export class StoreWhatsAppConfigRepository extends BaseRepository {
+    constructor() {
+        super(STORE_WHATSAPP_CONFIG_COLLECTION);
+    }
+    async getByStore(storeId) {
+        return this.findOneBy("storeId", storeId);
+    }
+}
 export class StoreGoogleConfigRepository extends BaseRepository {
     constructor() {
         super(STORE_GOOGLE_CONFIG_COLLECTION);
@@ -166,4 +174,5 @@ export const listingTemplatesRepository = new ListingTemplatesRepository();
 export const moderationQueueRepository = new ModerationQueueRepository();
 export const reportsRepository = new ReportsRepository();
 export const itemRequestsRepository = new ItemRequestsRepository();
+export const storeWhatsAppConfigRepository = new StoreWhatsAppConfigRepository();
 export const storeGoogleConfigRepository = new StoreGoogleConfigRepository();

package/dist/features/store-extensions/schemas/firestore.d.ts

@@ -18,6 +18,7 @@ import type { BaseDocument } from "../../../_internal/shared/types/base-document
  *   7. moderationQueue       — video / media moderation queue items
  *   8. reports               — buyer-submitted reports against listings/stores
  *   9. itemRequests          — community item request bulletin board
+ *  10. storeWhatsAppConfig   — per-store WhatsApp business catalogue + auto-replies
  *  11. storeGoogleConfig     — per-store Google Business reviews integration
  */
 export type PayoutMethodType = "upi" | "bank" | "card" | "other";
@@ -88,7 +89,7 @@ export interface AnalyticsAlertDocument extends BaseDocument {
     threshold: number;
     windowHours: number;
     isActive: boolean;
-    notifyChannels: Array<"in-app" | "email">;
+    notifyChannels: Array<"in-app" | "email" | "whatsapp">;
     /**
      * When this alert last fired.
      *
@@ -220,6 +221,21 @@ export interface ItemRequestDocument extends BaseDocument {
 export declare const ITEM_REQUESTS_COLLECTION: "itemRequests";
 export declare const ITEM_REQUEST_INDEXED_FIELDS: readonly ["opUserId", "status", "category", "createdAt"];
 export declare const DEFAULT_ITEM_REQUEST_DATA: Partial<ItemRequestDocument>;
+export interface StoreWhatsAppConfigDocument extends BaseDocument {
+    storeId: string;
+    isConnected: boolean;
+    isPaid: boolean;
+    phoneNumber?: string;
+    businessProfileName?: string;
+    catalogUrl?: string;
+    autoReply?: string;
+    welcomeMessage?: string;
+    /** Status of pending WhatsApp Business onboarding (Meta Cloud API). */
+    onboardingStatus?: "pending" | "approved" | "rejected";
+}
+export declare const STORE_WHATSAPP_CONFIG_COLLECTION: "storeWhatsAppConfig";
+export declare const STORE_WHATSAPP_CONFIG_INDEXED_FIELDS: readonly ["storeId", "isConnected", "isPaid"];
+export declare const DEFAULT_STORE_WHATSAPP_CONFIG_DATA: Partial<StoreWhatsAppConfigDocument>;
 export interface StoreGoogleConfigDocument extends BaseDocument {
     storeId: string;
     isConnected: boolean;