@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/features/pricing/components/AdminPricingView.js

@@ -0,0 +1,157 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Badge, Button, Heading, Row, Stack, Text } from "../../../ui/index.js";
+import { Modal } from "../../../ui/components/Modal.js";
+import { useToast } from "../../../ui/components/Toast.js";
+import { Form } from "../../../ui/components/Form.js";
+import { FieldInput } from "../../../ui/forms/FieldInput.js";
+import { FieldTextarea } from "../../../ui/forms/FieldTextarea.js";
+import { FormErrorSummary } from "../../../ui/forms/FormErrorSummary.js";
+import { apiClient } from "../../../http/ApiClient.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { toUserMessage } from "../../../errors/error-display-map.js";
+import { ACTIONS } from "../../../_internal/shared/actions/action-registry.js";
+import { RATE_TIER_ORDER, } from "../../../_internal/shared/features/pricing/rate-registry.js";
+const TIER_LABEL = {
+    statutory: "Statutory",
+    policy: "Policy ceiling",
+    operational: "Operational",
+};
+const TIER_BLURB = {
+    statutory: "Set by law, not by us. Sourced per HSN code in Tax codes — they deliberately do not appear below.",
+    policy: "A ceiling the owner decides. Administrator only, and a reason is required.",
+    operational: "Tuned, audited and reversible by back-office staff.",
+};
+const TIER_TONE = {
+    statutory: "warning",
+    policy: "info",
+    operational: "default",
+};
+/**
+ * 🛑 Format by the descriptor's UNIT, never by guessing from the value.
+ *
+ * `2` is 2% as a commission, ₹2 as a floor and 2 days as a hold, and the three
+ * are side by side in one table. A bare number would make the COD ceiling and
+ * the COD percentage read as the same kind of thing.
+ */
+function formatRate(value, unit) {
+    if (value === null)
+        return "—";
+    switch (unit) {
+        case "percent":
+            return `${value}%`;
+        case "rupees":
+            return `₹${value.toLocaleString("en-IN")}`;
+        case "days":
+            return value === 1 ? "1 day" : `${value} days`;
+        case "minutes":
+            return value === 1 ? "1 minute" : `${value} minutes`;
+        case "count":
+            return String(value);
+    }
+}
+function formatWhen(iso) {
+    const d = new Date(iso);
+    return Number.isNaN(d.getTime()) ? "—" : d.toLocaleDateString("en-IN", { dateStyle: "medium" });
+}
+export function AdminPricingView({ endpoint }) {
+    const { showToast } = useToast();
+    const [rates, setRates] = useState(null);
+    const [loadError, setLoadError] = useState(null);
+    const [editing, setEditing] = useState(null);
+    const [draftValue, setDraftValue] = useState("");
+    const [draftReason, setDraftReason] = useState("");
+    const [saving, setSaving] = useState(false);
+    const load = useCallback(async () => {
+        setLoadError(null);
+        try {
+            const payload = await apiClient.get(endpoint);
+            setRates(payload?.rates ?? []);
+        }
+        catch (err) {
+            /*
+             * Surfaced, never swallowed into an empty table. An empty rate list and
+             * a failed read look identical, and the first reads as "we charge
+             * nothing" (Root Cause #59/#72 — undefined must never render as zero).
+             *
+             * 🛑 A FIXED string, never `normalized.message`. The server's own text
+             * is how a Node `MODULE_NOT_FOUND` with a require stack ended up inside
+             * "Place your bid" (Root Cause #86) — and `mapToHttpError` scrubs 5xx
+             * messages in production anyway, so the raw value is either useless or
+             * dangerous. `normalizeError` still runs: it is what keeps `unknown`
+             * out of the catch body.
+             */
+            void normalizeError(err);
+            setLoadError("Could not load the rate table. Try again.");
+            setRates([]);
+        }
+    }, [endpoint]);
+    useEffect(() => {
+        void load();
+    }, [load]);
+    const byTier = useMemo(() => {
+        const groups = new Map();
+        for (const tier of RATE_TIER_ORDER)
+            groups.set(tier, []);
+        for (const rate of rates ?? [])
+            groups.get(rate.tier)?.push(rate);
+        return groups;
+    }, [rates]);
+    const openEditor = useCallback((rate) => {
+        setEditing(rate);
+        setDraftValue(rate.value === null ? "" : String(rate.value));
+        setDraftReason("");
+    }, []);
+    const submit = useCallback(async (setFieldError) => {
+        if (!editing)
+            return;
+        const parsed = Number(draftValue);
+        if (!Number.isFinite(parsed)) {
+            setFieldError("newValue", "Enter a number.");
+            return;
+        }
+        setSaving(true);
+        try {
+            await apiClient.post(endpoint, {
+                path: editing.path,
+                newValue: parsed,
+                ...(draftReason.trim() ? { reason: draftReason.trim() } : {}),
+            });
+            showToast(`${editing.label} updated.`, "success");
+            setEditing(null);
+            await load();
+        }
+        catch (err) {
+            void normalizeError(err);
+            /*
+             * 🛑 `toUserMessage`, never the server's own message — and no
+             * `?? normalized.message` fallback either. That fallback IS the bug:
+             * `toUserMessage` already terminates at `errors.codes.UNKNOWN`, so
+             * adding a raw-text branch for the unmapped case reintroduces exactly
+             * what Root Cause #86 describes — a require stack rendered inside a
+             * modal. The first draft of this file had it.
+             */
+            const code = err?.code;
+            setFieldError("newValue", toUserMessage(code ?? "UNKNOWN"));
+        }
+        finally {
+            setSaving(false);
+        }
+    }, [draftReason, draftValue, editing, endpoint, load, showToast]);
+    return (_jsxs(Stack, { gap: "loose", children: [_jsxs(Stack, { gap: "dense", children: [_jsx(Heading, { level: 1, children: "Pricing" }), _jsx(Text, { color: "muted", children: "Every rate the platform charges, what kind of number it is, and when it last moved. Changes take effect from the moment they are saved and never restate past orders." })] }), loadError ? (_jsxs(Stack, { surface: "danger-surface", padding: "md", rounded: "lg", gap: "dense", children: [_jsx(Text, { weight: "semibold", children: "The rate table could not be loaded." }), _jsx(Text, { size: "sm", children: loadError }), _jsx(Row, { children: _jsx(Button, { variant: "secondary", onClick: () => void load(), children: "Try again" }) })] })) : null, RATE_TIER_ORDER.map((tier) => {
+                const rows = byTier.get(tier) ?? [];
+                /*
+                 * The statutory section renders with NO rows and that is the point —
+                 * it tells a reader the tier exists and where it is set. Hiding an
+                 * empty section would make statutory rates look like something this
+                 * platform does not have.
+                 */
+                if (rows.length === 0 && tier !== "statutory")
+                    return null;
+                return (_jsxs(Stack, { gap: "comfortable", children: [_jsxs(Stack, { gap: "dense", children: [_jsxs(Row, { gap: "dense", align: "center", children: [_jsx(Heading, { level: 2, children: TIER_LABEL[tier] }), _jsx(Badge, { variant: TIER_TONE[tier], children: rows.length || "set elsewhere" })] }), _jsx(Text, { size: "sm", color: "muted", children: TIER_BLURB[tier] })] }), rows.map((rate) => (_jsxs(Row, { surface: "card", padding: "card", rounded: "lg", gap: "comfortable", align: "start", justify: "between", children: [_jsxs(Stack, { gap: "dense", children: [_jsxs(Row, { gap: "dense", align: "center", children: [_jsx(Text, { weight: "semibold", children: rate.label }), rate.sellerOnly ? _jsx(Badge, { variant: "default", children: "Seller-facing" }) : null] }), _jsx(Text, { size: "sm", color: "muted", children: rate.description }), rate.lastChange ? (_jsxs(Text, { size: "xs", color: "muted", children: [formatRate(rate.lastChange.previousValue, rate.unit), " \u2192", " ", formatRate(rate.lastChange.newValue, rate.unit), " on", " ", formatWhen(rate.lastChange.effectiveFrom), rate.lastChange.changedByName ? ` by ${rate.lastChange.changedByName}` : "", rate.lastChange.reason ? ` — ${rate.lastChange.reason}` : ""] })) : (_jsx(Text, { size: "xs", color: "muted", children: "No recorded change \u2014 this is the value it was configured with." }))] }), _jsxs(Row, { gap: "comfortable", align: "center", children: [_jsx(Text, { weight: "bold", numeric: true, children: formatRate(rate.value, rate.unit) }), _jsx(Button, { variant: "secondary", size: "sm", disabled: !rate.editable, onClick: () => openEditor(rate), children: "Change" })] })] }, rate.path)))] }, tier));
+            }), _jsx(Modal, { isOpen: editing !== null, onClose: () => setEditing(null), title: editing ? `Change ${editing.label}` : "Change rate", children: editing ? (_jsx(Form, { onSubmit: (e) => e.preventDefault(), children: ({ setFieldError, clearErrors }) => (_jsxs(Stack, { gap: "comfortable", children: [_jsx(FormErrorSummary, {}), _jsx(Text, { size: "sm", color: "muted", children: editing.description }), _jsx(FieldInput, { name: "newValue", label: `New value (${editing.unit})`, required: true, value: draftValue, onChange: setDraftValue }), _jsx(FieldTextarea, { name: "reason", label: editing.tier === "policy" ? "Reason (required)" : "Reason (optional)", value: draftReason, onChange: setDraftReason }), _jsx(Text, { size: "xs", color: "muted", children: "This takes effect now. Orders, invoices and payouts already recorded keep the rate they were charged at \u2014 nothing is restated." }), _jsxs(Row, { gap: "dense", justify: "end", children: [_jsx(Button, { variant: "ghost", onClick: () => setEditing(null), children: "Cancel" }), _jsx(Button, { action: ACTIONS.ADMIN["update-pricing"], isLoading: saving, onClick: () => {
+                                            clearErrors();
+                                            void submit(setFieldError);
+                                        } })] })] })) })) : null })] }));
+}

package/dist/features/products/components/PrizeDrawDetailPageView.js

@@ -11,7 +11,7 @@ import { ROUTES } from "../../../next/routing/route-map.js";
 import { getDefaultCurrency } from "../../../core/baseline-resolver.js";
 import { normalizeRichTextHtml } from "../../../utils/string.formatter.js";
 import { safeDisplayName } from "../../../security/index.js";
-import { Container, Div, Heading, Main, RichText, Row, Section, Span, Stack, Text, } from "../../../ui/index.js";
+import { Container, Disclaimer, Div, Heading, Main, RichText, Row, Section, Span, Stack, Text, } from "../../../ui/index.js";
 import { PreOrderDetailView } from "./PreOrderDetailView.js";
 import { PrizeDrawBottomActions } from "./PrizeDrawBottomActions.js";
 import { ProductTabsShell } from "./ProductTabsShell.js";
@@ -133,5 +133,5 @@ export async function PrizeDrawDetailPageView({ id, initialPrizeDraw, currentUse
                     price: pricePerEntry,
                     storeId: typeof p.storeId === "string" ? p.storeId : undefined,
                     storeName: storeName ?? undefined,
-                } }), _jsxs(Container, { size: "xl", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs("nav", { "aria-label": "Breadcrumb", className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] text-[var(--appkit-color-text-muted)] flex-wrap", children: [_jsx(Link, { href: String(ROUTES.HOME), className: "hover:text-primary-600 dark:hover:text-primary-400 transition-colors", children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.PRIZE_DRAWS), className: "hover:text-primary-600 dark:hover:text-primary-400 transition-colors", children: "Prize Draws" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: title })] }), _jsx(ShareButton, { title: title })] }), _jsx(PreOrderDetailView, { renderGallery: () => (_jsx(PrizeDrawCollage, { items: items, hideWonState: true })), renderInfo: () => (_jsxs(Stack, { gap: "md", children: [_jsx(OwnerQuickActions, { resource: "PRODUCT", placement: "detail", recordLabel: String(product.title ?? product.id), storeId: product.storeId ? String(product.storeId) : undefined, editHref: String(ROUTES.STORE.PRODUCTS_EDIT(String(product.id))) }), _jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_PRIZE_BADGE, children: "Prize Draw" }), _jsx(Span, { size: "xs", weight: "semibold", className: `inline-block ${statusClass(revealStatus)}`, padding: "pill-sm", rounded: "full", children: statusLabel(revealStatus) }), maxPerUser !== null && (_jsxs(Span, { size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", surface: "subtle", color: "muted", children: ["Limit: ", maxPerUser, " entries per customer"] })), maxPerUser !== null && userEntriesUsed !== null && (_jsxs(Span, { size: "xs", weight: "semibold", className: CLS_PRIZE_BADGE, children: ["You have used ", userEntriesUsed, "/", maxPerUser] }))] }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title })] }), _jsx(Div, { className: `${__P.p4}`, border: "subtle", rounded: "xl", surface: "muted", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { justify: "between", align: "center", children: [_jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "sm", children: "Entries" }), _jsxs(Text, { size: "sm", weight: "semibold", children: [current, " / ", max, " (", remaining, " left)"] })] }), revealStart && (_jsxs(Row, { justify: "between", align: "center", children: [_jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "sm", children: "Reveal window opens" }), _jsx(Text, { size: "sm", weight: "medium", children: revealStart.toLocaleString() })] })), revealEnd && (_jsxs(Row, { justify: "between", align: "center", children: [_jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "sm", children: "Reveal window closes" }), _jsx(Text, { size: "sm", weight: "medium", children: revealEnd.toLocaleString() })] }))] }) }), descriptionHtml && (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] line-clamp-4" })), safeSeller && (_jsx(Div, { className: `${__P.p3}`, border: "subtle", rounded: "xl", surface: "muted", children: _jsxs(Row, { justify: "between", align: "center", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Sold by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: safeSeller })] }), storeHref && (_jsx(Link, { href: storeHref, className: "shrink-0 rounded-lg bg-primary/10 dark:bg-primary/20 px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-semibold text-primary-700 dark:text-primary-300 hover:bg-primary/20 dark:hover:bg-primary/30 transition-colors", children: "Visit Store \u2192" }))] }) }))] })), renderTabs: () => (_jsx(ProductTabsShell, { descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined })), renderBuyBar: () => (_jsx(Div, { padding: "5", id: "prize-draw-buy-bar", border: "subtle", surface: "muted", rounded: "xl", children: _jsx(PrizeDrawEntryActions, { productId: String(product.id), productSlug: slug, title: title, pricePerEntry: pricePerEntry, currency: currency, remainingEntries: remaining, revealStatus: revealStatus, prizeGithubFileUrl: githubUrl }) })), renderRelated: () => (_jsxs(Stack, { gap: "xl", children: [_jsx(PurchaseReviewAffordance, { productId: String(product.id), storeId: product.storeId ? String(product.storeId) : undefined }), _jsx(GroupedListingsCarousel, { groups: groups }), _jsx(RelatedItemsSection, { relatedItems: relatedItems, relatedByBrand: relatedByBrand, relatedByTags: relatedByTags, relatedByStore: relatedByStore, categoryLabel: categoryName, brandLabel: brand, storeLabel: storeName ?? undefined })] })) }), _jsx(PrizeDrawBottomActions, { pricePerEntry: pricePerEntry, currency: currency, closed: revealStatus === "closed" || remaining === 0 })] })] }));
+                } }), _jsxs(Container, { size: "xl", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs("nav", { "aria-label": "Breadcrumb", className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] text-[var(--appkit-color-text-muted)] flex-wrap", children: [_jsx(Link, { href: String(ROUTES.HOME), className: "hover:text-primary-600 dark:hover:text-primary-400 transition-colors", children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.PRIZE_DRAWS), className: "hover:text-primary-600 dark:hover:text-primary-400 transition-colors", children: "Prize Draws" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: title })] }), _jsx(ShareButton, { title: title })] }), _jsx(PreOrderDetailView, { renderGallery: () => (_jsx(PrizeDrawCollage, { items: items, hideWonState: true })), renderInfo: () => (_jsxs(Stack, { gap: "md", children: [_jsx(OwnerQuickActions, { resource: "PRODUCT", placement: "detail", recordLabel: String(product.title ?? product.id), storeId: product.storeId ? String(product.storeId) : undefined, editHref: String(ROUTES.STORE.PRODUCTS_EDIT(String(product.id))) }), _jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_PRIZE_BADGE, children: "Prize Draw" }), _jsx(Span, { size: "xs", weight: "semibold", className: `inline-block ${statusClass(revealStatus)}`, padding: "pill-sm", rounded: "full", children: statusLabel(revealStatus) }), maxPerUser !== null && (_jsxs(Span, { size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", surface: "subtle", color: "muted", children: ["Limit: ", maxPerUser, " entries per customer"] })), maxPerUser !== null && userEntriesUsed !== null && (_jsxs(Span, { size: "xs", weight: "semibold", className: CLS_PRIZE_BADGE, children: ["You have used ", userEntriesUsed, "/", maxPerUser] }))] }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title })] }), _jsx(Div, { className: `${__P.p4}`, border: "subtle", rounded: "xl", surface: "muted", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { justify: "between", align: "center", children: [_jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "sm", children: "Entries" }), _jsxs(Text, { size: "sm", weight: "semibold", children: [current, " / ", max, " (", remaining, " left)"] })] }), revealStart && (_jsxs(Row, { justify: "between", align: "center", children: [_jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "sm", children: "Reveal window opens" }), _jsx(Text, { size: "sm", weight: "medium", children: revealStart.toLocaleString() })] })), revealEnd && (_jsxs(Row, { justify: "between", align: "center", children: [_jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "sm", children: "Reveal window closes" }), _jsx(Text, { size: "sm", weight: "medium", children: revealEnd.toLocaleString() })] }))] }) }), descriptionHtml && (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] line-clamp-4" })), safeSeller && (_jsx(Div, { className: `${__P.p3}`, border: "subtle", rounded: "xl", surface: "muted", children: _jsxs(Row, { justify: "between", align: "center", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Sold by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: safeSeller })] }), storeHref && (_jsx(Link, { href: storeHref, className: "shrink-0 rounded-lg bg-primary/10 dark:bg-primary/20 px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-semibold text-primary-700 dark:text-primary-300 hover:bg-primary/20 dark:hover:bg-primary/30 transition-colors", children: "Visit Store \u2192" }))] }) })), _jsx(Disclaimer, { id: "prize-draw" })] })), renderTabs: () => (_jsx(ProductTabsShell, { descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined })), renderBuyBar: () => (_jsx(Div, { padding: "5", id: "prize-draw-buy-bar", border: "subtle", surface: "muted", rounded: "xl", children: _jsx(PrizeDrawEntryActions, { productId: String(product.id), productSlug: slug, title: title, pricePerEntry: pricePerEntry, currency: currency, remainingEntries: remaining, revealStatus: revealStatus, prizeGithubFileUrl: githubUrl }) })), renderRelated: () => (_jsxs(Stack, { gap: "xl", children: [_jsx(PurchaseReviewAffordance, { productId: String(product.id), storeId: product.storeId ? String(product.storeId) : undefined }), _jsx(GroupedListingsCarousel, { groups: groups }), _jsx(RelatedItemsSection, { relatedItems: relatedItems, relatedByBrand: relatedByBrand, relatedByTags: relatedByTags, relatedByStore: relatedByStore, categoryLabel: categoryName, brandLabel: brand, storeLabel: storeName ?? undefined })] })) }), _jsx(PrizeDrawBottomActions, { pricePerEntry: pricePerEntry, currency: currency, closed: revealStatus === "closed" || remaining === 0 })] })] }));
 }

package/dist/features/products/components/ProductDetailPageView.d.ts

@@ -77,5 +77,21 @@ export interface ProductDetailPageViewProps {
      * Available" feature badge.
      */
     emiEnabled?: boolean;
+    /**
+     * Site-wide returns availability (`siteSettings.returns.windowDays > 0`),
+     * threaded from the page's data layer. Drives the "Returnable" badge.
+     *
+     * 🛑 A SITE feature gate, not a product attribute. The badge used to read
+     * `returnable={!finalSale}` — purely the product's own flag — so a platform
+     * with returns switched off still promised "Returnable" on every listing
+     * that was not a final sale. Same shape as the COD gate beside it: the
+     * product may carry the attribute, and we simply do not advertise it while
+     * the feature is off. Nothing is written to the product.
+     *
+     * Defaults to `true` when omitted so the two detail views that do not thread
+     * site settings keep their current behaviour rather than silently losing a
+     * badge they were correctly showing.
+     */
+    returnsEnabled?: boolean;
 }
-export declare function ProductDetailPageView({ slug, initialProduct, renderOfferAction, renderPrimaryActions, compositionContent, productFeatures, codEnabled, emiEnabled, }: ProductDetailPageViewProps): Promise<import("react").JSX.Element>;
+export declare function ProductDetailPageView({ slug, initialProduct, renderOfferAction, renderPrimaryActions, compositionContent, productFeatures, codEnabled, emiEnabled, returnsEnabled, }: ProductDetailPageViewProps): Promise<import("react").JSX.Element>;

package/dist/features/products/components/ProductDetailPageView.js

@@ -79,7 +79,7 @@ function StarRating({ value }) {
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
-export async function ProductDetailPageView({ slug, initialProduct, renderOfferAction, renderPrimaryActions, compositionContent, productFeatures, codEnabled, emiEnabled, }) {
+export async function ProductDetailPageView({ slug, initialProduct, renderOfferAction, renderPrimaryActions, compositionContent, productFeatures, codEnabled, emiEnabled, returnsEnabled = true, }) {
     // Use pre-fetched data when available to avoid a redundant repository call.
     // The page layer wraps getProductForDetail in React.cache(), so both
     // generateMetadata() and this component share the same in-flight promise.
@@ -386,7 +386,7 @@ export async function ProductDetailPageView({ slug, initialProduct, renderOfferA
                                                 ? "✓ In Stock"
                                                 : "✗ Out of Stock", inStock && effectiveStock !== null && effectiveStock <= 10
                                             ? ` — only ${effectiveStock} left`
-                                            : ""] })), (categorySlugs.length > 0 || subcategory || brand) && (_jsxs(Row, { gap: "sm", wrap: true, children: [categorySlugs.map((slug, i) => (_jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(slug)), className: "inline-flex items-center rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-2-5)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] transition-colors hover:border-primary-300 hover:bg-primary-surface hover:text-primary-700 dark:hover:border-primary-700/60 dark:hover:text-primary-400", children: categoryNames[i] ?? slug }, slug))), subcategory && (_jsx(Span, { layout: "inline-flex", size: "xs", weight: "medium", border: "subtle", rounded: "full", padding: "pill-sm-tall", surface: "muted", color: "muted", transform: "capitalize", children: subcategory })), brand && brandSlug && (_jsx(Link, { href: String(ROUTES.PUBLIC.BRAND_DETAIL(brandSlug)), className: "inline-flex items-center rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-2-5)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] transition-colors hover:border-primary-300 hover:bg-primary-surface hover:text-primary-700 dark:hover:border-primary-700/60 dark:hover:text-primary-400", children: brand })), brand && !brandSlug && (_jsx(Span, { layout: "inline-flex", size: "xs", weight: "medium", border: "subtle", rounded: "full", padding: "pill-sm-tall", surface: "muted", color: "muted", children: brand }))] })), bundleMemberships.length > 0 && (_jsx(Row, { gap: "sm", wrap: true, children: bundleMemberships.map((b) => (_jsxs(Link, { href: String(ROUTES.PUBLIC.BUNDLE_DETAIL(b.id)), className: CLS_BUNDLE_PILL, children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83D\uDCE6" }), "In bundle: ", b.title] }, b.id))) })), _jsx(ProductFeatureBadges, { featured: featured, freeShipping: freeShipping, codAvailable: codEnabled === true, codHref: String(ROUTES.PUBLIC.HOW_CHECKOUT_WORKS), emiAvailable: emiEnabled === true, emiHref: String(ROUTES.PUBLIC.HOW_EMI_WORKS), condition: condition ?? undefined, returnable: !finalSale, finalSale: finalSale, labels: {
+                                            : ""] })), (categorySlugs.length > 0 || subcategory || brand) && (_jsxs(Row, { gap: "sm", wrap: true, children: [categorySlugs.map((slug, i) => (_jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(slug)), className: "inline-flex items-center rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-2-5)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] transition-colors hover:border-primary-300 hover:bg-primary-surface hover:text-primary-700 dark:hover:border-primary-700/60 dark:hover:text-primary-400", children: categoryNames[i] ?? slug }, slug))), subcategory && (_jsx(Span, { layout: "inline-flex", size: "xs", weight: "medium", border: "subtle", rounded: "full", padding: "pill-sm-tall", surface: "muted", color: "muted", transform: "capitalize", children: subcategory })), brand && brandSlug && (_jsx(Link, { href: String(ROUTES.PUBLIC.BRAND_DETAIL(brandSlug)), className: "inline-flex items-center rounded-full border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] px-[var(--appkit-space-2-5)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] transition-colors hover:border-primary-300 hover:bg-primary-surface hover:text-primary-700 dark:hover:border-primary-700/60 dark:hover:text-primary-400", children: brand })), brand && !brandSlug && (_jsx(Span, { layout: "inline-flex", size: "xs", weight: "medium", border: "subtle", rounded: "full", padding: "pill-sm-tall", surface: "muted", color: "muted", children: brand }))] })), bundleMemberships.length > 0 && (_jsx(Row, { gap: "sm", wrap: true, children: bundleMemberships.map((b) => (_jsxs(Link, { href: String(ROUTES.PUBLIC.BUNDLE_DETAIL(b.id)), className: CLS_BUNDLE_PILL, children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83D\uDCE6" }), "In bundle: ", b.title] }, b.id))) })), _jsx(ProductFeatureBadges, { featured: featured, freeShipping: freeShipping, codAvailable: codEnabled === true, codHref: String(ROUTES.PUBLIC.HOW_CHECKOUT_WORKS), emiAvailable: emiEnabled === true, emiHref: String(ROUTES.PUBLIC.HOW_EMI_WORKS), condition: condition ?? undefined, returnable: !finalSale && returnsEnabled, finalSale: finalSale, labels: {
                                         featured: "Featured",
                                         fasterDelivery: "Faster Delivery",
                                         ratedSeller: "Rated Seller",

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

@@ -603,6 +603,31 @@ export interface ProductDocument extends BaseDocument {
     howToUse?: string[];
     allowOffers?: boolean;
     minOfferPercent?: number;
+    /**
+     * The seller permits a COORDINATED purchase on this listing.
+     *
+     * ## 🛑 A coordinated purchase is a SPECIALISED OFFER, not a listing type
+     *
+     * Owner, 2026-10-22: *"it is not a variant, it is similar to an offer, which
+     * the seller enables on the listing, then the customer can coordinate on it,
+     * it is a specialized offer."*
+     *
+     * That framing REMOVES work rather than adding it, and the removals are the
+     * part worth knowing — otherwise somebody rebuilds them:
+     *
+     * | Looks like it needs | Actually |
+     * |---|---|
+     * | a 7th `OrderSourceContext` variant | **nothing** — it is `offer-accepted`, and the provenance card already renders that branch |
+     * | an `orderType` tab | **nothing** — the Offer-wins tab already covers it |
+     * | a commit/settlement path | the offer lifecycle, with its chain fields, `checkoutDeadline` and lapse sweep |
+     * | a new money term | **none** — `unitPriceFor` already honours `lockedPrice`, so tax, payout base, refund ceiling and the invoice all follow |
+     *
+     * So this flag is deliberately shaped exactly like `allowOffers` above: same
+     * optional boolean, same seller control, same projection list. A listing
+     * with `allowOffers: false` and this `true` is coherent — the seller takes
+     * no solo offers but will consider a group — and nothing needs to forbid it.
+     */
+    allowCoordination?: boolean;
     customFields?: CustomField[];
     customSections?: CustomSection[];
     sublistingCategoryId?: string;
@@ -837,7 +862,7 @@ export declare const ProductStatusValues: {
 export declare const PRODUCT_COLLECTION: "products";
 export declare const PRODUCT_INDEXED_FIELDS: readonly ["storeId", "status", "category", "categoryIds", "featured", "listingType", "isPromoted", "isOnSale", "isSold", "searchTxt", "createdAt", "barcodeId", "physicalLocation.zone"];
 export declare const DEFAULT_PRODUCT_DATA: Partial<ProductDocument>;
-export declare const PRODUCT_PUBLIC_FIELDS: readonly ["allowOffers", "minOfferPercent", "id", "title", "description", "category", "categoryIds", "categoryIdNames", "subcategory", "brand", "price", "originalPrice", "currency", "stockQuantity", "availableQuantity", "images", "status", "storeName", "featured", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "views7d", "views30d", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "listingType", "auctionEndDate", "startingBid", "currentBid", "bidCount", "reservePrice", "buyNowPrice", "minBidIncrement", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderCurrentCount", "preOrderProductionStatus", "preOrderCancellable", "condition", "insurance", "insuranceCost", "shippingPaidBy", "isPromoted", "isOnSale", "isSold", "madeToOrder", "sourceStickerSheetId", "sourceStickerPartOrdinal", "slug", "seoTitle", "seoDescription", "seoKeywords", "viewCount", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "groupMinMembers", "groupMaxMembers", "groupMaxUnitsPerMember", "groupRequiredMemberIds", "groupDiscountPercent", "createdAt"];
+export declare const PRODUCT_PUBLIC_FIELDS: readonly ["allowOffers", "minOfferPercent", "allowCoordination", "id", "title", "description", "category", "categoryIds", "categoryIdNames", "subcategory", "brand", "price", "originalPrice", "currency", "stockQuantity", "availableQuantity", "images", "status", "storeName", "featured", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "views7d", "views30d", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "listingType", "auctionEndDate", "startingBid", "currentBid", "bidCount", "reservePrice", "buyNowPrice", "minBidIncrement", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderCurrentCount", "preOrderProductionStatus", "preOrderCancellable", "condition", "insurance", "insuranceCost", "shippingPaidBy", "isPromoted", "isOnSale", "isSold", "madeToOrder", "sourceStickerSheetId", "sourceStickerPartOrdinal", "slug", "seoTitle", "seoDescription", "seoKeywords", "viewCount", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "groupMinMembers", "groupMaxMembers", "groupMaxUnitsPerMember", "groupRequiredMemberIds", "groupDiscountPercent", "createdAt"];
 export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "categoryIds", "subcategory", "brand", "price", "originalPrice", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "physicalLocation", "sku", "pickupAddressId", "condition", "insurance", "shippingPaidBy", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "reservePrice", "buyNowPrice", "minBidIncrement", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "listingType", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderProductionStatus", "preOrderCancellable", "isOnSale", "isSold", "madeToOrder", "sourceStickerSheetId", "sourceStickerPartOrdinal", "allowShipBeforeEmiComplete", "gstRate", "hsnCode", "authenticity", "printMeta", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "groupMinMembers", "groupMaxMembers", "groupMaxUnitsPerMember", "groupRequiredMemberIds", "groupDiscountPercent", "barcodeId"];
 export type ProductCreateInput = Omit<ProductDocument, "id" | "createdAt" | "updatedAt" | "availableQuantity" | "bidCount" | "currentBid" | "auctionOriginalEndDate">;
 export type ProductUpdateInput = Partial<Pick<ProductDocument, (typeof PRODUCT_UPDATABLE_FIELDS)[number]>>;

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

@@ -142,6 +142,8 @@ export const PRODUCT_PUBLIC_FIELDS = [
     // the moment something starts projecting through it.
     "allowOffers",
     "minOfferPercent",
+    /* Same reasoning as `allowOffers`: the card renders a pill from it. */
+    "allowCoordination",
     "id",
     "title",
     "description",

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

@@ -449,10 +449,10 @@ export declare const productItemSchema: z.ZodObject<{
         wonByOrderId?: string | undefined;
     }[] | undefined;
     prizeGithubFileUrl?: string | undefined;
+    attributes?: Record<string, string> | undefined;
     inStock?: boolean | undefined;
     sellerAvatar?: string | undefined;
     stockCount?: number | undefined;
-    attributes?: Record<string, string> | undefined;
 }, {
     status: "published" | "draft" | "in_review" | "archived";
     id: string;
@@ -589,10 +589,10 @@ export declare const productItemSchema: z.ZodObject<{
         wonByOrderId?: string | undefined;
     }[] | undefined;
     prizeGithubFileUrl?: string | undefined;
+    attributes?: Record<string, string> | undefined;
     inStock?: boolean | undefined;
     sellerAvatar?: string | undefined;
     stockCount?: number | undefined;
-    attributes?: Record<string, string> | undefined;
 }>;
 /** Base Zod schema for list-query parameters. */
 export declare const productListParamsSchema: z.ZodObject<{

package/dist/features/products/schemas/product-features.validators.d.ts

@@ -28,7 +28,7 @@ export declare const productFeatureAdminCreateSchema: z.ZodObject<{
     category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[];
+    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
     storeId?: string | undefined;
     description?: string | undefined;
     iconColor?: string | undefined;
@@ -39,7 +39,7 @@ export declare const productFeatureAdminCreateSchema: z.ZodObject<{
     category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[];
+    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
     storeId?: string | undefined;
     description?: string | undefined;
     iconColor?: string | undefined;
@@ -60,7 +60,7 @@ export declare const productFeatureStoreCreateSchema: z.ZodObject<{
     category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[];
+    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
     description?: string | undefined;
     iconColor?: string | undefined;
 }, {
@@ -69,7 +69,7 @@ export declare const productFeatureStoreCreateSchema: z.ZodObject<{
     category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[];
+    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
     description?: string | undefined;
     iconColor?: string | undefined;
 }>;
@@ -91,7 +91,7 @@ export declare const productFeatureUpdateSchema: z.ZodObject<{
     isActive?: boolean | undefined;
     displayOrder?: number | undefined;
     iconColor?: string | undefined;
-    productTypes?: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[] | undefined;
+    productTypes?: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[] | undefined;
 }, {
     label?: string | undefined;
     icon?: string | undefined;
@@ -100,7 +100,7 @@ export declare const productFeatureUpdateSchema: z.ZodObject<{
     isActive?: boolean | undefined;
     displayOrder?: number | undefined;
     iconColor?: string | undefined;
-    productTypes?: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[] | undefined;
+    productTypes?: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[] | undefined;
 }>;
 /**
  * The FORM schema for the product-feature editor, with UI metadata.
@@ -136,7 +136,7 @@ export declare const productFeatureFormSchema: z.ZodEffects<z.ZodObject<{
     category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[];
+    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
     storeId?: string | undefined;
     description?: string | undefined;
     iconColor?: string | undefined;
@@ -147,7 +147,7 @@ export declare const productFeatureFormSchema: z.ZodEffects<z.ZodObject<{
     category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[];
+    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
     storeId?: string | undefined;
     description?: string | undefined;
     iconColor?: string | undefined;
@@ -158,7 +158,7 @@ export declare const productFeatureFormSchema: z.ZodEffects<z.ZodObject<{
     category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[];
+    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
     storeId?: string | undefined;
     description?: string | undefined;
     iconColor?: string | undefined;
@@ -169,7 +169,7 @@ export declare const productFeatureFormSchema: z.ZodEffects<z.ZodObject<{
     category: "shipping" | "seller" | "custom" | "condition" | "auction" | "platform" | "preorder";
     isActive: boolean;
     displayOrder: number;
-    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[];
+    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "preorder" | "product")[];
     storeId?: string | undefined;
     description?: string | undefined;
     iconColor?: string | undefined;

package/dist/features/promotions/actions/coupon-stacking.d.ts

@@ -4,21 +4,48 @@
  * A cart may hold at most one seller-scoped coupon per store, plus at most
  * one admin (platform-wide) coupon on top. Both scopes stack with each
  * other freely — the old `combineWithSellerCoupons` opt-out was removed
- * (2026-08-21): stacking is now unconditional as long as the two "buckets"
- * (per-store, and the single platform-wide slot) don't collide.
+ * (2026-08-21): stacking is now unconditional as long as the buckets
+ * (per-store, the single platform-wide slot, and the points-earn slot) don't
+ * collide.
+ *
+ * ## 🛑 THREE buckets since 2026-10-22, and the third is not a nicety (D51)
+ *
+ * `RIPLI05` is a PERMANENT, site-wide, undeletable coupon that awards points
+ * rather than discounting. With only the admin bucket it would occupy the one
+ * platform-wide slot forever, and **every other platform coupon would be
+ * unusable for as long as the points programme existed** — a seasonal sale
+ * coupon could never be applied by anyone.
+ *
+ * The spec also requires it to stack with a discount coupon, because it awards
+ * a percentage of the POST-discount amount paid. A design where the two cannot
+ * coexist cannot implement that sentence at all.
+ *
+ * So the bucket is keyed on the coupon's TYPE, not its scope: a `points_earn`
+ * coupon is admin-scoped like any platform coupon, and it is the type that
+ * decides which slot it competes for.
  *
  * Pure function, no I/O — safe to call from both the cart-apply route and
  * the checkout re-validation pass.
  */
 import type { CartAppliedCoupon } from "../../cart/schemas/firestore";
+import type { CouponType } from "../types";
 export interface IncomingCoupon {
     code: string;
     scope: "admin" | "seller";
     storeId?: string;
+    /**
+     * The coupon's type, which decides its bucket (D51).
+     *
+     * Optional, and absence means "a discount coupon" — every cart written
+     * before `points_earn` existed carries no type on its applied-coupon
+     * entries, and treating those as discount coupons is both correct and what
+     * preserves the previous behaviour exactly.
+     */
+    type?: CouponType;
 }
 /**
  * Returns a human-readable conflict message, or null when `incoming` can be
  * added alongside `existing` without violating the one-per-store +
- * one-global rule.
+ * one-global + one-points-earn rule.
  */
 export declare function detectCouponConflict(existing: CartAppliedCoupon[], incoming: IncomingCoupon): string | null;

package/dist/features/promotions/actions/coupon-stacking.js

@@ -1,9 +1,14 @@
+/** A points-earn coupon competes for its own slot, never the admin one. */
+function isPointsEarn(coupon) {
+    return coupon.type === "points_earn";
+}
 /**
  * Returns a human-readable conflict message, or null when `incoming` can be
  * added alongside `existing` without violating the one-per-store +
- * one-global rule.
+ * one-global + one-points-earn rule.
  */
 export function detectCouponConflict(existing, incoming) {
+    const incomingIsPoints = isPointsEarn(incoming);
     for (const applied of existing) {
         if (applied.code === incoming.code) {
             return `Coupon ${incoming.code} is already applied.`;
@@ -13,7 +18,21 @@ export function detectCouponConflict(existing, incoming) {
             applied.storeId === incoming.storeId) {
             return `A coupon for this store is already applied (${applied.code}). Remove it first.`;
         }
-        if (incoming.scope === "admin" && applied.scope === "admin") {
+        const appliedIsPoints = isPointsEarn(applied);
+        /*
+         * 🛑 The two admin-scoped buckets are checked SEPARATELY, and the order of
+         * these two branches does not matter precisely because each requires both
+         * sides to be in the same bucket. An earlier shape — testing scope first
+         * and type second — would have let a points coupon collide with a discount
+         * coupon, which is the whole defect.
+         */
+        if (incomingIsPoints && appliedIsPoints) {
+            return `A points offer is already applied (${applied.code}). Remove it first.`;
+        }
+        if (!incomingIsPoints &&
+            !appliedIsPoints &&
+            incoming.scope === "admin" &&
+            applied.scope === "admin") {
             return `Only one platform-wide coupon can be applied at a time (${applied.code}). Remove it first.`;
         }
     }

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

@@ -13,6 +13,19 @@ const TYPE_COLORS = {
     fixed: { card: "bg-success-surface border-success dark:bg-success-surface dark:border-success", code: "bg-success-surface dark:bg-success-surface text-success dark:text-success border-success dark:border-success" },
     free_shipping: { card: "bg-info-surface border-info dark:bg-info-surface dark:border-info", code: "bg-info-surface dark:bg-info-surface text-info dark:text-info border-info dark:border-info" },
     buy_x_get_y: { card: "bg-warning-surface border-warning dark:bg-warning-surface dark:border-warning", code: "bg-warning-surface dark:bg-warning-surface text-warning dark:text-warning border-warning dark:border-warning" },
+    /*
+     * D51. A `Record<CouponType, …>`, so this entry is a COMPILE requirement
+     * rather than a nicety — which is the reason the union was widened first.
+     *
+     * 🛑 `-surface` + the matching status ink, never a literal `text-white`.
+     * A past sweep paired `bg-{status}-surface` with `text-white` on 26
+     * surfaces, and since `-surface` is a near-white tint in light themes and a
+     * dark tint in dark ones, every one of them was invisible in exactly one
+     * theme (Root Cause #67). `primary` rather than a status colour because
+     * earning points is neither a warning nor an error — it is the brand's own
+     * offer.
+     */
+    points_earn: { card: "bg-primary-surface border-primary dark:bg-primary-surface dark:border-primary", code: "bg-primary-surface dark:bg-primary-surface text-primary dark:text-primary border-primary dark:border-primary" },
 };
 function pick(obj, ...keys) {
     for (const k of keys) {

package/dist/features/promotions/constants/coupon-help.d.ts

@@ -15,10 +15,10 @@ export declare const COUPON_HELP: {
     readonly title: "How coupons work";
     /** The stacking rules — the part buyers most often get wrong. */
     readonly stackingHeading: "You can use more than one coupon";
-    readonly stackingRules: readonly ["One store coupon per store. If your cart has items from three stores, you can apply each of those stores' coupons at the same time.", "Plus one platform-wide LetItRip coupon, on top of any store coupons.", "A second coupon for the same store, or a second platform-wide coupon, will be declined — remove the first one to swap it."];
+    readonly stackingRules: readonly ["One store coupon per store. If your cart has items from three stores, you can apply each of those stores' coupons at the same time.", "Plus one platform-wide LetItRip coupon, on top of any store coupons.", "Plus one points offer, which stacks with everything else — it earns you points rather than discounting, so it never takes the place of a discount coupon.", "A second coupon for the same store, a second platform-wide coupon, or a second points offer will be declined — remove the first one to swap it."];
     /** How the discount is actually distributed. */
     readonly applicationHeading: "Where each discount lands";
-    readonly applicationRules: readonly ["A store coupon only discounts that store's items.", "A platform-wide coupon is spread proportionally across every store in your cart.", "Orders are placed per store, so each store's order shows its own share of the discount."];
+    readonly applicationRules: readonly ["A store coupon only discounts that store's items.", "A platform-wide coupon is spread proportionally across every store in your cart.", "Orders are placed per store, so each store's order shows its own share of the discount.", "A points offer earns points on what you pay after any discounts, so the two interact rather than ignoring each other."];
     /** Reuses the failure reasons already written for the buyer shopping guide. */
     readonly failureHeading: "Why a coupon might not apply";
     readonly failureReasons: readonly ["The eligible items in your cart are below the coupon's minimum purchase amount — minimum spend is measured against the items the coupon actually covers, not your whole cart.", "The coupon has expired, or hasn't started yet.", "The coupon is limited to certain products or categories, and your cart has none of them.", "The coupon is first-order-only and you've ordered before.", "You've already used the coupon the maximum number of times allowed.", "The coupon ran out — some coupons have a total limit across all buyers."];

package/dist/features/promotions/constants/coupon-help.js

@@ -18,7 +18,11 @@ export const COUPON_HELP = {
     stackingRules: [
         "One store coupon per store. If your cart has items from three stores, you can apply each of those stores' coupons at the same time.",
         "Plus one platform-wide LetItRip coupon, on top of any store coupons.",
-        "A second coupon for the same store, or a second platform-wide coupon, will be declined — remove the first one to swap it.",
+        // D51's third bucket, stated for the buyer. Without this line the rule
+        // above reads as "one platform coupon" and a buyer with a points offer
+        // applied would reasonably think it was using up that slot.
+        "Plus one points offer, which stacks with everything else — it earns you points rather than discounting, so it never takes the place of a discount coupon.",
+        "A second coupon for the same store, a second platform-wide coupon, or a second points offer will be declined — remove the first one to swap it.",
     ],
     /** How the discount is actually distributed. */
     applicationHeading: "Where each discount lands",
@@ -26,6 +30,10 @@ export const COUPON_HELP = {
         "A store coupon only discounts that store's items.",
         "A platform-wide coupon is spread proportionally across every store in your cart.",
         "Orders are placed per store, so each store's order shows its own share of the discount.",
+        // Stated because the ORDER of operations is what a buyer would otherwise
+        // guess wrong — points are earned on what you actually paid, so a discount
+        // reduces the points as well as the price.
+        "A points offer earns points on what you pay after any discounts, so the two interact rather than ignoring each other.",
     ],
     /** Reuses the failure reasons already written for the buyer shopping guide. */
     failureHeading: "Why a coupon might not apply",