@mohasinac/appkit 4.61.0 → 4.62.1

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

@@ -250,6 +250,32 @@ export interface Order {
     platformFee?: number;
     /** COD handling fee, charged only on cash-on-delivery orders. */
     codHandlingFee?: number;
+    /**
+     * D46/D47 — points spent on this order, in points (1 point = ₹1).
+     *
+     * Absent on every order placed before the tender existed, and absent on any
+     * order that used none.
+     */
+    pointsApplied?: number;
+    /**
+     * What was actually COLLECTED: `total − pointsApplied`.
+     *
+     * 🛑 Read it as **`amountDue ?? total`**, never `amountDue ?? 0`. Absent means
+     * "no points were used, so the whole total was collected"; zero would mean
+     * the order was free. The two are a long way apart on a receipt, and the
+     * wrong default turns every historical order into a ₹0 one.
+     */
+    amountDue?: number;
+    /**
+     * The invoice number from the gapless FY series, e.g. `LIR/26-27/0001`
+     * (Phase 7).
+     *
+     * Absent until the order is paid, and absent on every order placed before
+     * the series existed — so the invoice page must render its own fallback
+     * rather than printing "undefined" where a statutory field belongs.
+     */
+    invoiceNumber?: string;
+    invoiceIssuedAt?: string;
     trackingNumber?: string;
     shippingCarrier?: string;
     /** Carrier tracking page URL — rendered as an external link that opens in a new tab. No live-tracking API integration; this is just the passthrough URL a seller/admin entered. */

package/dist/features/orders/utils/courier-block.d.ts

@@ -0,0 +1,25 @@
+/**
+ * "Is this order waiting on OUR courier problem?" — one predicate, so the
+ * obligation engine, the seller's UI and the admin digest cannot disagree.
+ *
+ * Deliberately a function over the document rather than a stored boolean: a
+ * denormalised `isCourierBlocked` mirror drifts the first time a write path
+ * forgets it (Root Cause #42), and the field it derives from is right there.
+ */
+import type { OrderDocument } from "../schemas/firestore";
+/** The subset actually read, so callers need not hold a whole order. */
+export interface CourierBlockBearing {
+    courierBlock?: OrderDocument["courierBlock"];
+    shippingDate?: Date | null;
+}
+/**
+ * True while a courier booking we attempted is still unresolved.
+ *
+ * 🛑 A block is CLEARED by the parcel actually going out, not by anything
+ * clearing the field. So a `shippingDate` wins over a stale `courierBlock`:
+ * if the seller gave up waiting and posted it themselves, the order is
+ * dispatched and the block is history, even if nobody deleted it. Reading the
+ * field alone would pause the dispatch clock forever on an order that had in
+ * fact shipped.
+ */
+export declare function hasOpenCourierBlock(order: CourierBlockBearing): boolean;

package/dist/features/orders/utils/courier-block.js

@@ -0,0 +1,23 @@
+/**
+ * "Is this order waiting on OUR courier problem?" — one predicate, so the
+ * obligation engine, the seller's UI and the admin digest cannot disagree.
+ *
+ * Deliberately a function over the document rather than a stored boolean: a
+ * denormalised `isCourierBlocked` mirror drifts the first time a write path
+ * forgets it (Root Cause #42), and the field it derives from is right there.
+ */
+/**
+ * True while a courier booking we attempted is still unresolved.
+ *
+ * 🛑 A block is CLEARED by the parcel actually going out, not by anything
+ * clearing the field. So a `shippingDate` wins over a stale `courierBlock`:
+ * if the seller gave up waiting and posted it themselves, the order is
+ * dispatched and the block is history, even if nobody deleted it. Reading the
+ * field alone would pause the dispatch clock forever on an order that had in
+ * fact shipped.
+ */
+export function hasOpenCourierBlock(order) {
+    if (!order.courierBlock)
+        return false;
+    return !order.shippingDate;
+}

package/dist/features/payment-cases/schemas/firestore.d.ts

@@ -107,7 +107,32 @@ export type PaymentCaseKind = "missing_order" | "unprocessed_event" | "status_co
  * Keyed on the USER, so a persistently broken mirror is one case with a
  * rising `observedCount` rather than a new row every night.
  */
- | "ledger_drift";
+ | "ledger_drift"
+/**
+ * We could not book a courier, so one or more PAID orders cannot be
+ * dispatched by us.
+ *
+ * The commonest cause is our own prepaid courier wallet running dry —
+ * Shiprocket has no recharge API, so the top-up is irreducibly a human
+ * action, which is exactly what a case is for.
+ *
+ * 🛑 KEYED ON THE WALLET (the provider), NOT ON THE ORDER. Fifty blocked
+ * orders are ONE problem with one fix, and the daily email ceiling applies
+ * to staff mail too (`send-guard.ts:92`) — so a per-order case would open
+ * fifty rows and spend the whole 80/day budget telling an operator the same
+ * thing fifty times, leaving them blind to everything else. `openOrObserve`
+ * raises `observedCount` instead, which also makes "how many orders are
+ * stuck behind this" readable at a glance.
+ *
+ * 🛑 Its own kind rather than `shipping_unpriced`, which means we could not
+ * work out what shipping COSTS. Here the price is known and the money to pay
+ * it is not there. The kind chips are what an operator triages by, and this
+ * is the fourth time this file has had to say so — the shortcut is always
+ * attractive because a plausible kind already exists.
+ *
+ * `severity: "error"`: a buyer has paid and their parcel is not moving.
+ */
+ | "courier_unavailable";
 /**
  * Identical to `ReportStatus`, deliberately — see the header. `actioned` means
  * a human did something; `dismissed` means a human decided nothing was wrong.

package/dist/features/payment-cases/schemas/firestore.js

@@ -81,6 +81,7 @@ const PAYMENT_CASE_KIND_MAP = {
     protection_claim: true,
     manual_refund_due: true,
     ledger_drift: true,
+    courier_unavailable: true,
 };
 export const PAYMENT_CASE_KINDS = Object.keys(PAYMENT_CASE_KIND_MAP);
 const PAYMENT_CASE_STATUS_MAP = {

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

@@ -29,6 +29,7 @@ import { pluginFor } from "../../../_internal/shared/listing-types/_registry.js"
 import { normalizeListingType } from "../utils/listing-type.js";
 import { resolveGroupMemberImage } from "../utils/group-member-image.js";
 import { checkGroupRules, describeGroupRules, EMPTY_GROUP_RULES, } from "../../../_internal/shared/features/products/group-rules.js";
+import { toUserMessage } from "../../../errors/error-display-map.js";
 const __O = { xAuto: "overflow-x-auto", hidden: "overflow-hidden" };
 const memberImage = resolveGroupMemberImage;
 function memberHref(m) {
@@ -112,9 +113,11 @@ export function GroupMemberPicker({ groupId, groupSource, members, rules = EMPTY
                 onAuthRequired?.();
                 return;
             }
+            // `code` is the stable identifier the error envelope carries; `error` is
+            // the server's own sentence and is deliberately no longer read here.
             const json = (await res.json());
             if (!res.ok || json.success === false) {
-                setError(json.error ?? "Couldn't add those items to your cart.");
+                setError(toUserMessage(json.code, undefined, { fallback: "Couldn't add those items to your cart." }));
                 return;
             }
             setQty({});

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/PrizeDrawEntryActions.js

@@ -12,6 +12,7 @@ import { NonRefundableConsentModal } from "./NonRefundableConsentModal.js";
 import { useAuthGate } from "../../../react/hooks/useAuthGate.js";
 import { ACTION_ID } from "../constants/action-defs.js";
 import { ACTIONS } from "../../../_internal/shared/actions/action-registry.js";
+import { toUserMessage } from "../../../errors/error-display-map.js";
 /**
  * Client buy panel for a prize-draw detail page (SB4-G).
  *
@@ -81,7 +82,7 @@ export function PrizeDrawEntryActions({ productId, productSlug, title, pricePerE
              * a correct refusal look like the same silent nothing this flow did
              * before it was repaired.
              */
-            showToast(n.message, "error");
+            showToast(toUserMessage(n.code, undefined, { fallback: "We couldn't enter you into that draw. Please try again." }), "error");
             return;
         }
         router.push(String(ROUTES.USER.CART));

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

@@ -15,6 +15,7 @@ import { useBottomActions } from "../../layout/hooks/useBottomActions.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
 import { useCanSeePrices } from "../../../react/hooks/useCanSeePrices.js";
 import { normalizeError } from "../../../errors/normalize.js";
+import { toUserMessage } from "../../../errors/error-display-map.js";
 /**
  * Wires the three primary product-detail CTAs (Buy Now / Add to Cart / Wishlist)
  * to the server APIs with guest-fallback. Replaces the previously-unwired
@@ -35,7 +36,7 @@ export function ProductDetailActions({ productId, productTitle, productImage, pr
     // itself — centralised so every add-to-cart call site gets the same
     // richer toast, not just this one.
     const addCart = useAddToCart({
-        onError: (err) => showToast(err?.message ?? "Could not add to cart", "error"),
+        onError: (err) => showToast(toUserMessage(err?.code, undefined, { fallback: "Could not add to cart" }), "error"),
     });
     async function handleAddToCart(then) {
         setBusy("cart");

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/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",

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

@@ -72,6 +72,29 @@ export interface CouponDocument extends BaseDocument {
     discount: DiscountConfig;
     bxgy?: BXGYConfig;
     tiers?: TieredDiscount[];
+    /**
+     * D51 — percentage of the amount PAID that a `points_earn` coupon awards as
+     * points. Meaningless, and ignored, on every other type.
+     *
+     * ## 🛑 Why this is not `discount.value`
+     *
+     * `discount` is read by `computeGroupCouponDiscount` to reduce the order.
+     * Overloading its `value` to mean "percent awarded as points" would make a
+     * points coupon discount the order by the same number it was supposed to
+     * credit — the exact overloading that `bxgy` and `tiers` are separate fields
+     * to avoid.
+     *
+     * `discount` stays REQUIRED on the interface because every existing coupon
+     * has one and widening it to optional would ripple through ~30 readers; a
+     * points coupon carries `{ value: 0 }`. The protection that matters is in
+     * the discount loop, which skips on TYPE rather than trusting that zero
+     * (`coupon-discount.ts`) — bad data cannot bypass a type check.
+     *
+     * The base is the post-discount amount actually paid in money, which is
+     * `POINTS_EARN_PERCENT`'s existing rule; this field exists so a campaign can
+     * raise it (the festival double event) without editing a constant.
+     */
+    pointsPercent?: number;
     usage: UsageConfig;
     validity: ValidityConfig;
     restrictions: RestrictionsConfig;
@@ -143,6 +166,7 @@ export declare const COUPON_FIELDS: {
         readonly FIXED: CouponType;
         readonly FREE_SHIPPING: CouponType;
         readonly BUY_X_GET_Y: CouponType;
+        readonly POINTS_EARN: CouponType;
     };
     readonly SCOPE_VALUES: {
         readonly ADMIN: "admin";

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

@@ -48,6 +48,7 @@ export const COUPON_FIELDS = {
         FIXED: "fixed",
         FREE_SHIPPING: "free_shipping",
         BUY_X_GET_Y: "buy_x_get_y",
+        POINTS_EARN: "points_earn",
     },
     SCOPE_VALUES: {
         ADMIN: "admin",
@@ -59,6 +60,9 @@ export const COUPON_TYPE_LABELS = {
     fixed: "Fixed Amount Discount",
     free_shipping: "Free Shipping",
     buy_x_get_y: "Buy X Get Y",
+    // Named for what the buyer gets, not for the mechanism. "Points earn" is
+    // our word for it; "Points back" is what appears on their balance.
+    points_earn: "Points Back",
 };
 export const DEFAULT_COUPON_DATA = {
     usage: { currentUsage: 0 },

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

@@ -1,4 +1,22 @@
-export type CouponType = "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
+export type CouponType = "percentage" | "fixed" | "free_shipping" | "buy_x_get_y"
+/**
+ * D51 — a coupon that awards POINTS rather than discounting the order.
+ *
+ * 🛑 It carries `pointsPercent`, not a discount value, and it must never
+ * reach the discount arithmetic: a `points_earn` coupon with a `discount`
+ * field read by `computeGroupCouponDiscount` would silently discount the
+ * order as well as award points.
+ *
+ * It exists because `RIPLI05` is a PERMANENT, site-wide coupon, and
+ * `detectCouponConflict` permits exactly one admin coupon site-wide — so
+ * putting it in the admin slot would make every other platform coupon
+ * unusable for as long as it exists. It gets its own stacking bucket.
+ *
+ * Adding it here is a compile error at `COUPON_TYPE_LABELS`, which is a
+ * `Record<CouponType, string>` — that is the point of declaring the union
+ * first.
+ */
+ | "points_earn";
 export type CouponScope = "admin" | "seller";
 export interface CouponItem {
     id: string;