@mohasinac/appkit 4.71.0 → 4.71.2

package/dist/features/products/utils/listing-type.js

@@ -8,7 +8,7 @@ export function isListingType(value) {
  * Parse a multi-select listing-type URL value into canonical types.
  *
  * The type filter is a checkbox group, so its URL value is a pipe-joined set
- * (`auction|pre-order`) — the same shape the Sieve adapter upgrades to a
+ * (`collector drop|pre-order`) — the same shape the Sieve adapter upgrades to a
  * Firestore `in` query. Unknown tokens are DROPPED rather than passed through:
  * an unrecognised value reaching `where("listingType","==",x)` matches zero
  * documents forever with no error (Root Cause #33), so silently ignoring it and
@@ -35,7 +35,7 @@ export function parseSelectedListingTypes(raw) {
  * Toggle one type in a pipe-joined selection, returning the new URL value
  * (`""` when nothing is left selected). Keeps canonical iteration order so the
  * URL is stable regardless of the order the user ticked the boxes — otherwise
- * `auction|art` and `art|auction` would be two different React Query keys for
+ * `collector drop|art-and-stickers` and `art-and-stickers|collector drop` would be two different React Query keys for
  * the same result set.
  */
 export function toggleListingTypeSelection(raw, type) {
@@ -49,27 +49,48 @@ export function toggleListingTypeSelection(raw, type) {
 /**
  * Canonical accessor for the listing-kind discriminator. `listingType` is the
  * single source of truth on every `ProductDocument` / `ProductItem` — the
- * legacy `isAuction` / `isPreOrder` booleans were removed in S3 (SB1-G final,
+ * legacy `isCollectorDrop` / `isPreOrder` booleans were removed in S3 (SB1-G final,
  * 2026-05-13).
  *
  * Returns `"standard"` when the input is undefined or missing the field, so
  * legacy payloads still classify safely without a separate guard.
  */
 export function normalizeListingType(input) {
-    return input?.listingType ?? "standard";
+    const raw = input?.listingType;
+    if (raw === undefined)
+        return "standard";
+    /*
+     * Pre-rename spellings a stored document may still carry. Normalising them
+     * HERE is what gives every `is*Listing` predicate below back-compat for
+     * free, rather than each call site having to remember both spellings
+     * (Root Cause #58).
+     */
+    if (raw === "auction")
+        return "collector-drop";
+    if (raw === "prize-draw")
+        return "clearance";
+    if (raw === "random-lots")
+        return "clearance";
+    // 1.34 — `art` and `stickers` MERGED. Both spellings are live in stored
+    // product documents, so both must keep resolving here.
+    if (raw === "art")
+        return "art-and-stickers";
+    if (raw === "stickers")
+        return "art-and-stickers";
+    return raw;
 }
 /** Convenience predicates that read the canonical `listingType` discriminator. */
-export const isAuctionListing = (input) => normalizeListingType(input) === "auction";
+export const isCollectorDropListing = (input) => normalizeListingType(input) === "collector-drop";
 export const isPreOrderListing = (input) => normalizeListingType(input) === "pre-order";
 export const isStandardListing = (input) => normalizeListingType(input) === "standard";
-export const isPrizeDrawListing = (input) => normalizeListingType(input) === "prize-draw";
+export const isClearanceListing = (input) => normalizeListingType(input) === "clearance";
 // SB-UNI-F 2026-05-13 — Phase 2 union extension predicates.
 export const isClassifiedListing = (input) => normalizeListingType(input) === "classified";
 export const isDigitalCodeListing = (input) => normalizeListingType(input) === "digital-code";
 export const isLiveListing = (input) => normalizeListingType(input) === "live";
-// Art/stickers session — printed-only physical-goods listing types.
-export const isArtListing = (input) => normalizeListingType(input) === "art";
-export const isStickersListing = (input) => normalizeListingType(input) === "stickers";
+// Printed-only physical goods — ONE merged type (1.34). Reads through
+// `normalizeListingType`, so a stored `art` or `stickers` still answers true.
+export const isArtAndStickersListing = (input) => normalizeListingType(input) === "art-and-stickers";
 // SB-UNI-D — isBundleListing removed. Bundles are now a categoryType
 // discriminator on CategoryDocument; consumers should query
 // `categoriesRepository.findBySlugAndType(slug, "bundle")` instead.

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

@@ -10,7 +10,7 @@ export interface SellerCreateCouponInput {
     name: string;
     description: string;
     type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
-    applicableToAuctions: boolean;
+    applicableToCollectorDrops: boolean;
     discount: {
         value: number;
         maxDiscount?: number;
@@ -34,7 +34,7 @@ export interface SellerCreateCouponInput {
         firstTimeUserOnly: boolean;
     };
 }
-export type SellerUpdateCouponInput = Partial<Omit<SellerCreateCouponInput, "sellerCode" | "applicableToAuctions">>;
+export type SellerUpdateCouponInput = Partial<Omit<SellerCreateCouponInput, "sellerCode" | "applicableToCollectorDrops">>;
 export declare function sellerCreateCoupon(userId: string, input: SellerCreateCouponInput): Promise<CouponDocument>;
 export declare function sellerUpdateCoupon(userId: string, userRole: string, id: string, input: SellerUpdateCouponInput): Promise<CouponDocument>;
 export declare function sellerDeleteCoupon(userId: string, userRole: string, id: string): Promise<void>;

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

@@ -14,7 +14,7 @@ export async function sellerCreateCoupon(userId, input) {
     const store = await storeRepository.findByOwnerId(userId);
     if (!store || store.status !== "active")
         throw new AuthorizationError("Your store must be active before you can create coupons.");
-    const { sellerCode, applicableToAuctions, ...rest } = input;
+    const { sellerCode, applicableToCollectorDrops, ...rest } = input;
     const fullCode = buildSellerCouponCode(store.storeSlug, sellerCode);
     const existing = await couponsRepository.getCouponByCode(fullCode);
     if (existing)
@@ -24,7 +24,7 @@ export async function sellerCreateCoupon(userId, input) {
         code: fullCode,
         scope: "seller",
         storeId: store.id,
-        applicableToAuctions,
+        applicableToCollectorDrops,
         createdBy: userId,
         validity: {
             ...rest.validity,

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

@@ -39,7 +39,7 @@ interface CouponCardProps {
      */
     hideClaim?: boolean;
     /** Source enum forwarded to /api/user/coupons/claim for analytics. */
-    claimSource?: "manual" | "promo" | "spin" | "raffle" | "prize-draw";
+    claimSource?: "manual" | "promo" | "spin" | "giveaway" | "clearance";
 }
 export declare function CouponCard({ coupon, labels: labelsProp, onCopy, className, selectable, isSelected, onSelect, onEdit, onToggleActive, onDelete, hideClaim, claimSource, }: CouponCardProps): import("react").JSX.Element;
 export {};

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

@@ -118,7 +118,9 @@ export function CouponsIndexListing({ initialCoupons, storeId, }) {
     const clearFilters = () => {
         table.setMany({ type: "", [TABLE_KEYS.DATE_FROM]: "", [TABLE_KEYS.DATE_TO]: "" });
     };
-    return (_jsxs(Div, { className: "min-h-[40vh]", children: [_jsxs(StickyToolbar, { offset: "header", tone: "default", border: true, padding: "md", z: "above-toolbar", dismissible: true, id: "coupons-toolbar", children: [_jsxs(Row, { gap: "xs", className: "max-w-full", children: [_jsxs(Button, { type: "button", variant: hasActiveFilters ? "outline" : "ghost", onClick: openFilters, gap: "sm", rounded: "lg", paddingX: "md", paddingY: "sm", textSize: "sm", weight: "medium", className: hasActiveFilters ? "border-primary bg-primary-50 text-primary-700 dark:bg-primary-900/30 dark:text-primary-300 shrink-0" : "border-[var(--appkit-color-border)] text-[var(--appkit-color-text-muted)] shrink-0", children: [_jsx(SlidersHorizontal, { className: "h-4 w-4" }), _jsxs(Span, { className: "hidden sm:inline", children: ["Filters", hasActiveFilters ? " •" : ""] })] }), _jsxs(Row, { surface: "default", className: `flex-1 ${__O.hidden}`, border: "strong", rounded: "lg", children: [_jsx(Input, { bare: true, type: "text", value: searchInput, onChange: (e) => setSearchInput(e.target.value), onKeyDown: handleKeyDown, placeholder: "Search by name or description\u2026", className: "min-w-0 flex-1 bg-transparent px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] text-[var(--appkit-color-text)] placeholder-zinc-400 outline-none" }), searchInput && (_jsx(IconButton, { type: "button", onClick: () => { setSearchInput(""); table.set(TABLE_KEYS.QUERY, ""); }, "aria-label": "Clear search", variant: "ghost", size: "sm", children: _jsx(X, { className: "h-3.5 w-3.5" }) })), _jsx(IconButton, { type: "button", onClick: commitSearch, "aria-label": "Search", variant: "ghost", size: "sm", children: _jsx(Search, { className: "h-4 w-4" }) })] }), _jsxs(Row, { color: "muted", textSize: "sm", gap: "xs", className: "shrink-0", children: [_jsx(Span, { className: "hidden md:inline whitespace-nowrap", children: "Sort by" }), _jsx(SortDropdown, { value: table.get(TABLE_KEYS.SORT) || DEFAULT_SORT, onChange: (v) => { table.set(TABLE_KEYS.SORT, v); }, options: COUPON_SORT_OPTIONS })] })] }), hasActiveFilters && (_jsxs(Row, { gap: "xs", wrap: true, className: "mt-2", children: [activeType && (_jsxs(Span, { layout: "flex", gap: "xs", size: "xs", weight: "medium", className: "bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", padding: "pill-sm-tall", children: [COUPON_TYPES.find((t) => t.value === activeType)?.label ?? activeType, _jsx(Button, { variant: "ghost", type: "button", onClick: () => { table.set(TABLE_KEYS.TYPE, ""); }, "aria-label": "Remove type filter", className: CLS_CHIP_BTN, children: _jsx(X, { className: "h-3 w-3" }) })] })), table.get(TABLE_KEYS.DATE_FROM) && (_jsxs(Span, { layout: "flex", gap: "xs", size: "xs", weight: "medium", className: "bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", padding: "pill-sm-tall", children: ["From: ", table.get(TABLE_KEYS.DATE_FROM), _jsx(Button, { variant: "ghost", type: "button", onClick: () => { table.set(TABLE_KEYS.DATE_FROM, ""); }, "aria-label": "Remove from-date filter", className: CLS_CHIP_BTN, children: _jsx(X, { className: "h-3 w-3" }) })] })), table.get(TABLE_KEYS.DATE_TO) && (_jsxs(Span, { layout: "flex", gap: "xs", size: "xs", weight: "medium", className: "bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", padding: "pill-sm-tall", children: ["To: ", table.get(TABLE_KEYS.DATE_TO), _jsx(Button, { variant: "ghost", type: "button", onClick: () => { table.set(TABLE_KEYS.DATE_TO, ""); }, "aria-label": "Remove to-date filter", className: CLS_CHIP_BTN, children: _jsx(X, { className: "h-3 w-3" }) })] })), _jsx(Button, { variant: "ghost", type: "button", onClick: clearFilters, textSize: "xs", textColor: "muted", className: "underline", children: "Clear all" })] }))] }), _jsx(Div, { paddingY: "y-md", paddingX: "x-md", children: _jsx(CouponHelpDetails, {}) }), _jsxs(Div, { paddingY: "y-lg", paddingX: "x-md", children: [isLoading ? (_jsx(Grid, { cols: "cardsWide", gap: "sm", children: Array.from({ length: 6 }).map((_, i) => (_jsxs(Stack, { border: "skeleton", gap: "sm", rounded: "xl", padding: "md", className: "animate-pulse", children: [_jsx(Div, { className: "h-6 w-2/3", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-4 w-full", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-3 w-1/2", surface: "subtle", rounded: "default" })] }, i))) })) : displayCoupons.length === 0 ? (_jsx(Div, { className: "text-left", padding: "y-4xl", children: _jsx(Text, { color: "faint", children: "No coupons match your search." }) })) : (_jsx(Grid, { cols: "cardsWide", gap: "sm", children: displayCoupons.map((coupon) => (_jsx(CouponCard, { coupon: coupon, labels: {
+    return (_jsxs(Div, { className: "min-h-[40vh]", children: [_jsxs(StickyToolbar, { offset: "header", tone: "default", border: true, padding: "md", z: "above-toolbar", dismissible: true, id: "coupons-toolbar", children: [_jsxs(Row, { gap: "xs", className: "max-w-full", children: [_jsxs(Button, { type: "button", variant: hasActiveFilters ? "outline" : "ghost", onClick: openFilters, gap: "sm", rounded: "lg", paddingX: "md", paddingY: "sm", textSize: "sm", weight: "medium", className: hasActiveFilters ? "border-primary bg-primary-50 text-primary-700 dark:bg-primary-900/30 dark:text-primary-300 shrink-0" : "border-[var(--appkit-color-border)] text-[var(--appkit-color-text-muted)] shrink-0", children: [_jsx(SlidersHorizontal, { className: "h-4 w-4" }), _jsxs(Span, { className: "hidden sm:inline", children: ["Filters", hasActiveFilters ? " •" : ""] })] }), _jsxs(Row, { surface: "default", className: `flex-1 ${__O.hidden}`, border: "strong", rounded: "lg", children: [_jsx(Input, { bare: true, type: "text", value: searchInput, onChange: (e) => setSearchInput(e.target.value), onKeyDown: handleKeyDown, placeholder: "Search by name or description\u2026", className: "min-w-0 flex-1 bg-transparent px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] text-[var(--appkit-color-text)] placeholder-zinc-400 outline-none" }), searchInput && (_jsx(IconButton, { type: "button", onClick: () => { setSearchInput(""); table.set(TABLE_KEYS.QUERY, ""); }, "aria-label": "Clear search", variant: "ghost", size: "sm", children: _jsx(X, { className: "h-3.5 w-3.5" }) })), _jsx(IconButton, { type: "button", onClick: commitSearch, "aria-label": "Search", variant: "ghost", size: "sm", children: _jsx(Search, { className: "h-4 w-4" }) })] }), _jsxs(Row, { color: "muted", textSize: "sm", gap: "xs", className: "shrink-0", children: [_jsx(Span, { className: "hidden md:inline whitespace-nowrap", children: "Sort by" }), _jsx(SortDropdown, { value: table.get(TABLE_KEYS.SORT) || DEFAULT_SORT, onChange: (v) => { table.set(TABLE_KEYS.SORT, v); }, options: COUPON_SORT_OPTIONS })] })] }), hasActiveFilters && (_jsxs(Row, { gap: "xs", wrap: true, className: "mt-2", children: [activeType && (_jsxs(Span, { layout: "flex", gap: "xs", size: "xs", weight: "medium", className: "bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", padding: "pill-sm-tall", children: [COUPON_TYPES.find((t) => t.value === activeType)?.label ?? activeType, _jsx(Button, { variant: "ghost", type: "button", onClick: () => { table.set(TABLE_KEYS.TYPE, ""); }, "aria-label": "Remove type filter", className: CLS_CHIP_BTN, children: _jsx(X, { className: "h-3 w-3" }) })] })), table.get(TABLE_KEYS.DATE_FROM) && (_jsxs(Span, { layout: "flex", gap: "xs", size: "xs", weight: "medium", className: "bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", padding: "pill-sm-tall", children: ["From: ", table.get(TABLE_KEYS.DATE_FROM), _jsx(Button, { variant: "ghost", type: "button", onClick: () => { table.set(TABLE_KEYS.DATE_FROM, ""); }, "aria-label": "Remove from-date filter", className: CLS_CHIP_BTN, children: _jsx(X, { className: "h-3 w-3" }) })] })), table.get(TABLE_KEYS.DATE_TO) && (_jsxs(Span, { layout: "flex", gap: "xs", size: "xs", weight: "medium", className: "bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", padding: "pill-sm-tall", children: ["To: ", table.get(TABLE_KEYS.DATE_TO), _jsx(Button, { variant: "ghost", type: "button", onClick: () => { table.set(TABLE_KEYS.DATE_TO, ""); }, "aria-label": "Remove to-date filter", className: CLS_CHIP_BTN, children: _jsx(X, { className: "h-3 w-3" }) })] })), _jsx(Button, { variant: "ghost", type: "button", onClick: clearFilters, textSize: "xs", textColor: "muted", className: "underline", children: "Clear all" })] }))] }), _jsx(Div, { paddingY: "y-md", paddingX: "x-md", children: _jsx(CouponHelpDetails, {}) }), _jsxs(Div, { paddingY: "y-lg", paddingX: "x-md", children: [isLoading ? (_jsx(Grid, { cols: "cardsWide", gap: "sm", children: Array.from({ length: 6 }).map((_, i) => (_jsxs(Stack, { border: "skeleton", gap: "sm", rounded: "xl", padding: "md", className: "animate-pulse", children: [_jsx(Div, { className: "h-6 w-2/3", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-4 w-full", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-3 w-1/2", surface: "subtle", rounded: "default" })] }, i))) })) : displayCoupons.length === 0 ? (_jsx(Div, { className: "text-left", padding: "y-4xl", children: _jsx(Text, { color: "faint", children: table.get(TABLE_KEYS.QUERY) || activeFilterCount > 0
+                                ? "No coupons match your search."
+                                : "No active coupons right now — check back soon." }) })) : (_jsx(Grid, { cols: "cardsWide", gap: "sm", children: displayCoupons.map((coupon) => (_jsx(CouponCard, { coupon: coupon, labels: {
                                 copy: "Copy",
                                 copied: "Copied!",
                                 expires: "Expires",

package/dist/features/promotions/hooks/useCouponValidate.d.ts

@@ -1,4 +1,4 @@
-import type { JsonValue } from "@mohasinac/appkit";
+import type { JsonValue } from "../../../schemas/types";
 import type { ListingType } from "../../products/types";
 interface ValidateCouponPayload {
     code: string;

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

@@ -11,9 +11,6 @@ import { CouponDocument, CouponUsageDocument, CouponCreateInput } from "../schem
 import type { CouponType } from "../types";
 import type { FirestoreDocument } from "../../../schemas/types";
 import type { DocumentReference, WriteBatch } from "firebase-admin/firestore";
-/**
- * Repository for coupon management
- */
 export declare class CouponsRepository extends BaseRepository<CouponDocument> {
     constructor();
     /**
@@ -159,10 +156,10 @@ export declare class CouponsRepository extends BaseRepository<CouponDocument> {
      * - Admin coupons apply to all non-pre-order items that satisfy product/
      *   category restrictions.
      * - Seller coupons apply only to non-pre-order items from that seller.
-     * - If `applicableToAuctions` is true, only auction items from that seller
+     * - If `applicableToCollectorDrops` is true, only collector drop items from that seller
      *   are eligible; regular (fixed-price) items from the same store are
      *   excluded.
-     * - If `applicableToAuctions` is false/undefined, only non-auction items
+     * - If `applicableToCollectorDrops` is false/undefined, only non-collectorDrop items
      *   from that seller are eligible.
      *
      * @returns An object that mirrors `validateCoupon` but also includes

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

@@ -17,6 +17,17 @@ const COUPON_USAGE_SUBCOLLECTION = "couponUsage";
 /**
  * Repository for coupon management
  */
+/**
+ * Is this cart line a collector drop?
+ *
+ * Inlined rather than importing `isCollectorDropListing` from the products
+ * feature — no repository in this codebase imports another feature's modules
+ * (the Turbopack import-chain trap, Root Cause #6/#18). Accepts the pre-rename
+ * "auction" spelling a stored cart line may still carry (Root Cause #58).
+ */
+function isCollectorDropLine(item) {
+    return item.listingType === "collector-drop" || item.listingType === "auction";
+}
 export class CouponsRepository extends BaseRepository {
     constructor() {
         super(COUPONS_COLLECTION);
@@ -449,10 +460,10 @@ export class CouponsRepository extends BaseRepository {
      * - Admin coupons apply to all non-pre-order items that satisfy product/
      *   category restrictions.
      * - Seller coupons apply only to non-pre-order items from that seller.
-     * - If `applicableToAuctions` is true, only auction items from that seller
+     * - If `applicableToCollectorDrops` is true, only collector drop items from that seller
      *   are eligible; regular (fixed-price) items from the same store are
      *   excluded.
-     * - If `applicableToAuctions` is false/undefined, only non-auction items
+     * - If `applicableToCollectorDrops` is false/undefined, only non-collectorDrop items
      *   from that seller are eligible.
      *
      * @returns An object that mirrors `validateCoupon` but also includes
@@ -465,7 +476,7 @@ export class CouponsRepository extends BaseRepository {
             return check.result;
         const { coupon } = check;
         // Determine eligible items — no blanket exclusion by product type.
-        // Coupon flags (applicableToAuctions) decide type eligibility below.
+        // Coupon flags (applicableToCollectorDrops) decide type eligibility below.
         let eligible = [...cartItems];
         const scope = coupon.scope ?? "admin";
         if (scope === "seller") {
@@ -473,14 +484,14 @@ export class CouponsRepository extends BaseRepository {
             eligible = eligible.filter((item) => item.storeId === coupon.storeId);
         }
         // Apply product-type filter based on the coupon's own flag:
-        //   true       → auction-only coupon
-        //   false      → explicitly excludes auctions (still allows pre-orders + standard)
+        //   true       → collector-drop-only coupon
+        //   false      → explicitly excludes collector drops (still allows pre-orders + standard)
         //   undefined  → no restriction; applies to every listing type
-        if (coupon.applicableToAuctions === true) {
-            eligible = eligible.filter((item) => item.listingType === "auction");
+        if (coupon.applicableToCollectorDrops === true) {
+            eligible = eligible.filter((item) => isCollectorDropLine(item));
         }
-        else if (coupon.applicableToAuctions === false) {
-            eligible = eligible.filter((item) => item.listingType !== "auction");
+        else if (coupon.applicableToCollectorDrops === false) {
+            eligible = eligible.filter((item) => !isCollectorDropLine(item));
         }
         // Apply product/category restrictions from the coupon itself
         const { applicableProducts, applicableCategories, excludeProducts, excludeCategories, } = coupon.restrictions;
@@ -509,8 +520,8 @@ export class CouponsRepository extends BaseRepository {
             return {
                 valid: false,
                 coupon,
-                message: coupon.applicableToAuctions === true
-                    ? "This coupon only applies to auction items"
+                message: coupon.applicableToCollectorDrops === true
+                    ? "This coupon only applies to collector drop items"
                     : needsCategories
                         ? "This coupon does not apply to any of the categories in your cart"
                         : scope === "seller"

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

@@ -68,7 +68,7 @@ export interface CouponDocument extends BaseDocument {
     scope: "admin" | "seller";
     /** For seller-scoped coupons: the storeId (= storeSlug = store.id) of the issuing store */
     storeId?: string;
-    applicableToAuctions?: boolean;
+    applicableToCollectorDrops?: boolean;
     discount: DiscountConfig;
     bxgy?: BXGYConfig;
     tiers?: TieredDiscount[];
@@ -110,7 +110,15 @@ export type CouponUsageDocument = {
     orders: string[];
 };
 export type ClaimedCouponStatus = "active" | "expired" | "used";
-export type ClaimedCouponSource = "manual" | "promo" | "spin" | "raffle" | "prize-draw";
+/**
+ * How a coupon landed in a user's wallet. PERSISTED on `claimedCoupons`.
+ *
+ * `raffle` -> `giveaway` on 2026-10-31 with the `EventType` rename; the
+ * migration script rewrites stored rows. 🛑 `spin` is NOT renamed — it is the
+ * bare spin-prize source (`assignSpinPrize`), not the `spin_wheel` event type
+ * that became `bonus-spin`.
+ */
+export type ClaimedCouponSource = "manual" | "promo" | "spin" | "giveaway" | "clearance";
 export interface ClaimedCouponSnapshot {
     name: string;
     description?: string;
@@ -180,7 +188,7 @@ export declare const COUPONS_UPDATABLE_FIELDS: readonly ["name", "description",
 export type CouponCreateInput = Omit<CouponDocument, "id" | "createdAt" | "updatedAt" | "stats"> & {
     stats?: Partial<CouponStats>;
 };
-export type CouponUpdateInput = Partial<Pick<CouponDocument, "name" | "description" | "discount" | "bxgy" | "tiers" | "usage" | "validity" | "restrictions" | "applicableToAuctions">>;
+export type CouponUpdateInput = Partial<Pick<CouponDocument, "name" | "description" | "discount" | "bxgy" | "tiers" | "usage" | "validity" | "restrictions" | "applicableToCollectorDrops">>;
 export interface CouponValidationResult {
     valid: boolean;
     discountAmount: number;

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

@@ -146,7 +146,7 @@ export declare const couponFirestoreSchema: z.ZodObject<{
     type: z.ZodEnum<["percentage", "fixed", "free_shipping", "buy_x_get_y"]>;
     scope: z.ZodEnum<["admin", "seller"]>;
     storeId: z.ZodOptional<z.ZodString>;
-    applicableToAuctions: z.ZodOptional<z.ZodBoolean>;
+    applicableToCollectorDrops: z.ZodOptional<z.ZodBoolean>;
     discount: z.ZodObject<{
         value: z.ZodNumber;
         maxDiscount: z.ZodOptional<z.ZodEffects<z.ZodNumber, number, number>>;
@@ -273,8 +273,8 @@ export declare const couponFirestoreSchema: z.ZodObject<{
     }>;
 }, "strip", z.ZodTypeAny, {
     code: string;
-    type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
     id: string;
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     description: string;
     createdAt: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
@@ -318,7 +318,7 @@ export declare const couponFirestoreSchema: z.ZodObject<{
         excludeCategories?: string[] | undefined;
     };
     storeId?: string | undefined;
-    applicableToAuctions?: boolean | undefined;
+    applicableToCollectorDrops?: boolean | undefined;
     bxgy?: {
         buyQuantity: number;
         getQuantity: number;
@@ -332,8 +332,8 @@ export declare const couponFirestoreSchema: z.ZodObject<{
     }[] | undefined;
 }, {
     code: string;
-    type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
     id: string;
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     description: string;
     createdAt: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
@@ -377,7 +377,7 @@ export declare const couponFirestoreSchema: z.ZodObject<{
         excludeCategories?: string[] | undefined;
     };
     storeId?: string | undefined;
-    applicableToAuctions?: boolean | undefined;
+    applicableToCollectorDrops?: boolean | undefined;
     bxgy?: {
         buyQuantity: number;
         getQuantity: number;
@@ -508,7 +508,7 @@ export declare const couponCreateBodySchema: z.ZodEffects<z.ZodObject<{
     createdBy: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, "strip", z.ZodTypeAny, {
     code: string;
-    type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     description: string;
     createdBy: string;
     name: string;
@@ -548,7 +548,7 @@ export declare const couponCreateBodySchema: z.ZodEffects<z.ZodObject<{
     }[] | undefined;
 }, {
     code: string;
-    type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     name: string;
     discount: {
         value: number;
@@ -588,7 +588,7 @@ export declare const couponCreateBodySchema: z.ZodEffects<z.ZodObject<{
     } | undefined;
 }>, {
     code: string;
-    type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     description: string;
     createdBy: string;
     name: string;
@@ -628,7 +628,7 @@ export declare const couponCreateBodySchema: z.ZodEffects<z.ZodObject<{
     }[] | undefined;
 }, {
     code: string;
-    type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     name: string;
     discount: {
         value: number;
@@ -888,7 +888,7 @@ export declare const couponUsageFirestoreSchema: z.ZodObject<{
     orders: string[];
 }>;
 export declare const claimedCouponStatusSchema: z.ZodEnum<["active", "expired", "used"]>;
-export declare const claimedCouponSourceSchema: z.ZodEnum<["manual", "promo", "spin", "raffle", "prize-draw"]>;
+export declare const claimedCouponSourceSchema: z.ZodEnum<["manual", "promo", "spin", "giveaway", "clearance"]>;
 export declare const claimedCouponSnapshotSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
@@ -931,7 +931,7 @@ export declare const claimedCouponSnapshotSchema: z.ZodObject<{
         excludeCategories?: string[] | undefined;
     }>;
 }, "strip", z.ZodTypeAny, {
-    type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     name: string;
     scope: "seller" | "admin";
     discount: {
@@ -950,7 +950,7 @@ export declare const claimedCouponSnapshotSchema: z.ZodObject<{
     description?: string | undefined;
     storeId?: string | undefined;
 }, {
-    type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     name: string;
     scope: "seller" | "admin";
     discount: {
@@ -974,7 +974,7 @@ export declare const claimedCouponFirestoreSchema: z.ZodObject<{
     userId: z.ZodString;
     couponId: z.ZodString;
     couponCode: z.ZodString;
-    source: z.ZodEnum<["manual", "promo", "spin", "raffle", "prize-draw"]>;
+    source: z.ZodEnum<["manual", "promo", "spin", "giveaway", "clearance"]>;
     couponSnapshot: z.ZodObject<{
         name: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
@@ -1017,7 +1017,7 @@ export declare const claimedCouponFirestoreSchema: z.ZodObject<{
             excludeCategories?: string[] | undefined;
         }>;
     }, "strip", z.ZodTypeAny, {
-        type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
+        type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
         name: string;
         scope: "seller" | "admin";
         discount: {
@@ -1036,7 +1036,7 @@ export declare const claimedCouponFirestoreSchema: z.ZodObject<{
         description?: string | undefined;
         storeId?: string | undefined;
     }, {
-        type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
+        type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
         name: string;
         scope: "seller" | "admin";
         discount: {
@@ -1086,9 +1086,9 @@ export declare const claimedCouponFirestoreSchema: z.ZodObject<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">>]>;
 }, "strip", z.ZodTypeAny, {
-    status: "used" | "active" | "expired";
-    source: "prize-draw" | "raffle" | "manual" | "promo" | "spin";
+    source: "manual" | "giveaway" | "clearance" | "promo" | "spin";
     id: string;
+    status: "used" | "active" | "expired";
     updatedAt: string | Date | z.objectOutputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -1099,7 +1099,7 @@ export declare const claimedCouponFirestoreSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">;
     couponId: string;
     couponSnapshot: {
-        type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
+        type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
         name: string;
         scope: "seller" | "admin";
         discount: {
@@ -1126,9 +1126,9 @@ export declare const claimedCouponFirestoreSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough"> | undefined;
     usedOrderId?: string | undefined;
 }, {
-    status: "used" | "active" | "expired";
-    source: "prize-draw" | "raffle" | "manual" | "promo" | "spin";
+    source: "manual" | "giveaway" | "clearance" | "promo" | "spin";
     id: string;
+    status: "used" | "active" | "expired";
     updatedAt: string | Date | z.objectInputType<{
         toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
     }, z.ZodTypeAny, "passthrough">;
@@ -1139,7 +1139,7 @@ export declare const claimedCouponFirestoreSchema: z.ZodObject<{
     }, z.ZodTypeAny, "passthrough">;
     couponId: string;
     couponSnapshot: {
-        type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
+        type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
         name: string;
         scope: "seller" | "admin";
         discount: {
@@ -1209,8 +1209,8 @@ export declare const couponItemSchema: z.ZodObject<{
     updatedAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     code: string;
-    type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
     id: string;
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     description: string;
     createdAt: string;
     updatedAt: string;
@@ -1233,8 +1233,8 @@ export declare const couponItemSchema: z.ZodObject<{
     applicableCategoryIds?: string[] | undefined;
 }, {
     code: string;
-    type: "percentage" | "fixed" | "free_shipping" | "buy_x_get_y";
     id: string;
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
     description: string;
     createdAt: string;
     updatedAt: string;

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

@@ -82,7 +82,7 @@ export const couponFirestoreSchema = z.object({
     type: couponTypeEnumSchema,
     scope: z.enum(["admin", "seller"]),
     storeId: z.string().optional(),
-    applicableToAuctions: z.boolean().optional(),
+    applicableToCollectorDrops: z.boolean().optional(),
     discount: discountConfigSchema,
     bxgy: bxgyConfigSchema.optional(),
     tiers: z.array(tieredDiscountSchema).optional(),
@@ -236,8 +236,8 @@ export const claimedCouponSourceSchema = z.enum([
     "manual",
     "promo",
     "spin",
-    "raffle",
-    "prize-draw",
+    "giveaway",
+    "clearance",
 ]);
 export const claimedCouponSnapshotSchema = z.object({
     name: z.string(),

package/dist/features/reviews/actions/review-actions.js

@@ -4,7 +4,7 @@
  * Pure business functions for review create/update/delete/vote and query flows.
  * Auth and rate-limit stay in consumer server-action wrappers.
  */
-import { sortBy } from "@mohasinac/appkit";
+import { sortBy } from "../../../constants/sort.js";
 import { AuthorizationError, NotFoundError, ValidationError, } from "../../../errors/index.js";
 import { serverLogger } from "../../../monitoring/index.js";
 import { finalizeStagedMediaArray, finalizeStagedMediaUrl, } from "../../media/finalize.js";

package/dist/features/reviews/api/[id]/route.js

@@ -27,7 +27,22 @@ import { createRouteHandler } from "../../../../next/api/routeHandler.js";
  */
 import { reviewRepository } from "../../repository/reviews.repository.js";
 import { normalizeError } from "../../../../errors/normalize.js";
-import { isAdminUser, isModeratorUser } from "../../../auth/role-predicates.js";
+/*
+ * ── Review moderation is a PERMISSION, not a role ─────────────────────────────
+ *
+ * `isOwner || isModeratorUser(user) || isAdminUser(user)` stood here until
+ * 2026-11-08. Folding `moderator` into `employee` (A9) made the middle term
+ * true for every employee, so editing or deleting ANY buyer's review — and
+ * changing its moderation `status`, which the owner branch below is explicitly
+ * forbidden from doing — widened to every employee account.
+ *
+ * Owner's decision: keep the fold, gate on an explicit permission. PATCH asks
+ * for `admin:reviews:write`, DELETE for `admin:reviews:delete`: the existing
+ * keys, already in the `content_moderator` / `review_manager` /
+ * `trust_and_safety` presets, so granting review moderation is one click and
+ * NOT a consequence of being an employee.
+ */
+import { canModerateServer } from "../../../../_internal/server/features/auth/permissions.js";
 const ERR_REVIEW_NOT_FOUND = "Review not found";
 // ---- GET /api/reviews/[id] ---------------------------------------------------
 export async function GET(_request, context) {
@@ -114,9 +129,17 @@ export const reviewItemPATCH = createRouteHandler({
         if (!review)
             return NextResponse.json({ success: false, error: ERR_REVIEW_NOT_FOUND }, { status: 404 });
         const isOwner = review.userId === user.uid;
-        const isModerator = isModeratorUser(user);
-        const isAdmin = isAdminUser(user);
-        if (!isOwner && !isModerator && !isAdmin) {
+        /*
+         * 🛑 Resolved even when `isOwner` is true, unlike every other gate in this
+         * sweep — and that is deliberate, not a missed optimisation. The value is
+         * load-bearing TWICE: once to admit the caller, and once below to decide
+         * whether `status` may move. An author who ALSO holds the grant must be
+         * able to moderate their own review; short-circuiting on ownership would
+         * silently pin their `status` edits and return 200, which is exactly the
+         * invisible-regression shape this rework exists to remove.
+         */
+        const mayModerate = await canModerateServer(user?.uid, "reviews:moderate");
+        if (!isOwner && !mayModerate) {
             return NextResponse.json({ success: false, error: "Forbidden" }, { status: 403 });
         }
         /*
@@ -125,9 +148,9 @@ export const reviewItemPATCH = createRouteHandler({
          * edited by its author stays approved and is NOT sent back for
          * re-moderation.
          */
-        const patch = isOwner && !isModerator && !isAdmin
-            ? { ...body, status: review.status }
-            : body;
+        const patch = mayModerate
+            ? body
+            : { ...body, status: review.status };
         /*
          * 🛑 `hasImages` is DERIVED and has to move with `images`, or the two
          * disagree. It is a real queryable field (`hasImages` is `canFilter` in
@@ -163,9 +186,10 @@ export const reviewItemDELETE = createRouteHandler({
         if (!review)
             return NextResponse.json({ success: false, error: ERR_REVIEW_NOT_FOUND }, { status: 404 });
         const isOwner = review.userId === user.uid;
-        const isModerator = isModeratorUser(user);
-        const isAdmin = isAdminUser(user);
-        if (!isOwner && !isModerator && !isAdmin) {
+        // `reviews:remove` (`admin:reviews:delete`), not the PATCH key — deleting
+        // someone else's review is a separate grant from editing it.
+        const mayModerate = isOwner || (await canModerateServer(user?.uid, "reviews:remove"));
+        if (!mayModerate) {
             return NextResponse.json({ success: false, error: "Forbidden" }, { status: 403 });
         }
         await reviewRepository.delete(id);

package/dist/features/reviews/components/ReviewDetailPageView.d.ts

@@ -1,5 +1,8 @@
 import React from "react";
+import type { DashboardCard } from "../../../_internal/shared/features/dashboard/recent-entry";
 export interface ReviewDetailPageViewProps {
     id: string;
+    /** Admin-curated page-region cards (Phase 12). Omit for no extra content. */
+    pageRegionCards?: DashboardCard[];
 }
-export declare function ReviewDetailPageView({ id }: ReviewDetailPageViewProps): Promise<React.JSX.Element>;
+export declare function ReviewDetailPageView({ id, pageRegionCards }: ReviewDetailPageViewProps): Promise<React.JSX.Element>;