@mohasinac/appkit 2.3.1 → 2.4.0

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

@@ -0,0 +1,80 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState, useCallback } from "react";
+import { Search, SlidersHorizontal, X } from "lucide-react";
+import { useUrlTable } from "../../../react/hooks/useUrlTable";
+import { Pagination, SortDropdown, Div, Text, Heading } from "../../../ui";
+import { usePromotions } from "../hooks/usePromotions";
+import { CouponCard } from "./CouponCard";
+const COUPON_SORT_OPTIONS = [
+    { value: "name", label: "Name A–Z" },
+    { value: "-name", label: "Name Z–A" },
+    { value: "-validity.endDate", label: "Expiring Soon" },
+    { value: "-createdAt", label: "Newest First" },
+    { value: "createdAt", label: "Oldest First" },
+];
+const COUPON_TYPES = [
+    { value: "percentage", label: "% Off" },
+    { value: "fixed", label: "Fixed Amount" },
+    { value: "free_shipping", label: "Free Shipping" },
+    { value: "buy_x_get_y", label: "Buy X Get Y" },
+];
+export function CouponsIndexListing({ initialCoupons, storeSlug, sellerId, }) {
+    const table = useUrlTable({ defaults: { pageSize: "12", sort: "-createdAt" } });
+    const [searchInput, setSearchInput] = useState(table.get("q") || "");
+    const [filterOpen, setFilterOpen] = useState(false);
+    // Build Sieve filter string
+    const buildFilters = () => {
+        const parts = ["validity.isActive==true"];
+        const typeFilter = table.get("type");
+        if (typeFilter)
+            parts.push(`type==${typeFilter}`);
+        const dateFrom = table.get("dateFrom");
+        if (dateFrom)
+            parts.push(`validity.startDate>=${dateFrom}`);
+        const dateTo = table.get("dateTo");
+        if (dateTo)
+            parts.push(`validity.endDate<=${dateTo}`);
+        if (sellerId)
+            parts.push(`sellerId==${sellerId}`);
+        return parts.join(",");
+    };
+    const { promotions: coupons, total, totalPages, isLoading } = usePromotions({
+        page: table.getNumber("page", 1),
+        pageSize: table.getNumber("pageSize", 12),
+        sort: table.get("sort") || "-createdAt",
+        filters: buildFilters(),
+    });
+    // Use initial data on first load if available and no search/filter active
+    const displayCoupons = !isLoading && coupons.length > 0
+        ? coupons
+        : !isLoading && initialCoupons && !table.get("q") && !table.get("type")
+            ? initialCoupons
+            : coupons;
+    const commitSearch = useCallback(() => {
+        table.set("q", searchInput.trim());
+        table.setPage(1);
+    }, [searchInput, table]);
+    const handleKeyDown = (e) => {
+        if (e.key === "Enter")
+            commitSearch();
+    };
+    const activeType = table.get("type");
+    const hasActiveFilters = !!activeType || !!table.get("dateFrom") || !!table.get("dateTo");
+    const clearFilters = () => {
+        table.set("type", "");
+        table.set("dateFrom", "");
+        table.set("dateTo", "");
+        table.setPage(1);
+    };
+    return (_jsxs("div", { className: "min-h-[40vh]", children: [_jsxs("div", { className: "sticky top-[var(--header-height,0px)] z-20 border-b border-zinc-200 dark:border-slate-700 bg-white/95 dark:bg-slate-900/95 backdrop-blur-sm py-2.5 px-4", children: [_jsxs("div", { className: "flex items-center gap-2.5 max-w-full", children: [_jsxs("button", { type: "button", onClick: () => setFilterOpen(true), className: `flex shrink-0 items-center gap-2 rounded-lg border px-3.5 py-2 text-sm font-medium transition-colors ${hasActiveFilters
+                                    ? "border-primary bg-primary-50 text-primary-700 dark:bg-primary-900/30 dark:text-primary-300"
+                                    : "border-zinc-300 dark:border-slate-600 text-zinc-700 dark:text-zinc-200 hover:bg-zinc-50 dark:hover:bg-slate-800"}`, children: [_jsx(SlidersHorizontal, { className: "h-4 w-4" }), _jsxs("span", { className: "hidden sm:inline", children: ["Filters", hasActiveFilters ? " •" : ""] })] }), _jsxs("div", { className: "flex flex-1 items-center overflow-hidden rounded-lg border border-zinc-300 dark:border-slate-600 bg-white dark:bg-slate-900", children: [_jsx("input", { 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-3 py-2 text-sm text-zinc-900 dark:text-zinc-100 placeholder-zinc-400 outline-none" }), searchInput && (_jsx("button", { type: "button", onClick: () => { setSearchInput(""); table.set("q", ""); table.setPage(1); }, className: "p-2 text-zinc-400 hover:text-zinc-600 dark:hover:text-zinc-300", "aria-label": "Clear search", children: _jsx(X, { className: "h-3.5 w-3.5" }) })), _jsx("button", { type: "button", onClick: commitSearch, className: "flex shrink-0 items-center justify-center px-3 py-2 text-zinc-400 hover:text-primary dark:hover:text-primary-400 transition-colors", "aria-label": "Search", children: _jsx(Search, { className: "h-4 w-4" }) })] }), _jsxs("div", { className: "flex shrink-0 items-center gap-1.5 text-sm text-zinc-500 dark:text-zinc-400", children: [_jsx("span", { className: "hidden md:inline whitespace-nowrap", children: "Sort by" }), _jsx(SortDropdown, { value: table.get("sort") || "-createdAt", onChange: (v) => { table.set("sort", v); table.setPage(1); }, options: COUPON_SORT_OPTIONS })] })] }), hasActiveFilters && (_jsxs("div", { className: "flex flex-wrap items-center gap-2 mt-2", children: [activeType && (_jsxs("span", { className: "flex items-center gap-1 rounded-full bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300 text-xs font-medium px-2.5 py-1", children: [COUPON_TYPES.find((t) => t.value === activeType)?.label ?? activeType, _jsx("button", { type: "button", onClick: () => { table.set("type", ""); table.setPage(1); }, "aria-label": "Remove type filter", children: _jsx(X, { className: "h-3 w-3" }) })] })), table.get("dateFrom") && (_jsxs("span", { className: "flex items-center gap-1 rounded-full bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300 text-xs font-medium px-2.5 py-1", children: ["From: ", table.get("dateFrom"), _jsx("button", { type: "button", onClick: () => { table.set("dateFrom", ""); table.setPage(1); }, "aria-label": "Remove from-date filter", children: _jsx(X, { className: "h-3 w-3" }) })] })), table.get("dateTo") && (_jsxs("span", { className: "flex items-center gap-1 rounded-full bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300 text-xs font-medium px-2.5 py-1", children: ["To: ", table.get("dateTo"), _jsx("button", { type: "button", onClick: () => { table.set("dateTo", ""); table.setPage(1); }, "aria-label": "Remove to-date filter", children: _jsx(X, { className: "h-3 w-3" }) })] })), _jsx("button", { type: "button", onClick: clearFilters, className: "text-xs text-zinc-500 hover:text-zinc-700 dark:hover:text-zinc-300 underline", children: "Clear all" })] }))] }), _jsxs("div", { className: "py-6 px-4", children: [isLoading ? (_jsx("div", { className: "grid gap-3 md:grid-cols-2 lg:grid-cols-3", children: Array.from({ length: 6 }).map((_, i) => (_jsxs("div", { className: "rounded-xl border-2 border-zinc-100 dark:border-slate-700 p-4 animate-pulse space-y-3", children: [_jsx("div", { className: "h-6 bg-zinc-200 dark:bg-slate-700 rounded w-2/3" }), _jsx("div", { className: "h-4 bg-zinc-200 dark:bg-slate-700 rounded w-full" }), _jsx("div", { className: "h-3 bg-zinc-200 dark:bg-slate-700 rounded w-1/2" })] }, i))) })) : displayCoupons.length === 0 ? (_jsx("div", { className: "py-16 text-center", children: _jsx(Text, { className: "text-zinc-400 dark:text-zinc-500", children: "No coupons match your search." }) })) : (_jsx("div", { className: "grid gap-3 md:grid-cols-2 lg:grid-cols-3", children: displayCoupons.map((coupon) => (_jsx(CouponCard, { coupon: coupon, labels: {
+                                copy: "Copy",
+                                copied: "Copied!",
+                                expires: "Expires",
+                                minOrder: "Min. order",
+                                off: "OFF",
+                                freeShipping: "Free Shipping",
+                            } }, coupon.id))) })), totalPages > 1 && (_jsx("div", { className: "mt-8 flex justify-center", children: _jsx(Pagination, { currentPage: table.getNumber("page", 1), totalPages: totalPages, onPageChange: (p) => table.setPage(p) }) })), !isLoading && total > 0 && (_jsx(Div, { className: "mt-4 text-center", children: _jsxs(Text, { className: "text-xs text-zinc-400 dark:text-zinc-500", children: [total, " coupon", total !== 1 ? "s" : "", " available"] }) }))] }), filterOpen && (_jsxs(_Fragment, { children: [_jsx("div", { className: "fixed inset-0 z-40 bg-black/40", "aria-hidden": "true", onClick: () => setFilterOpen(false) }), _jsxs("div", { className: "fixed inset-y-0 left-0 z-50 flex w-80 flex-col bg-white dark:bg-slate-900 shadow-2xl", children: [_jsxs("div", { className: "flex items-center justify-between border-b border-zinc-200 dark:border-slate-700 px-4 py-3.5", children: [_jsxs("span", { className: "flex items-center gap-2 text-base font-semibold text-zinc-900 dark:text-zinc-100", children: [_jsx(SlidersHorizontal, { className: "h-4 w-4" }), "Filters"] }), _jsx("button", { type: "button", onClick: () => setFilterOpen(false), "aria-label": "Close filters", className: "rounded-lg p-1.5 text-zinc-500 hover:bg-zinc-100 dark:hover:bg-slate-800 transition-colors", children: _jsx(X, { className: "h-5 w-5" }) })] }), _jsxs("div", { className: "flex-1 overflow-y-auto px-4 py-4 space-y-6", children: [_jsxs("div", { children: [_jsx(Heading, { level: 6, className: "text-xs font-semibold uppercase tracking-wider text-zinc-500 dark:text-zinc-400 mb-3", children: "Discount Type" }), _jsxs("div", { className: "space-y-2", children: [COUPON_TYPES.map((t) => (_jsxs("label", { className: "flex items-center gap-2 cursor-pointer text-sm text-zinc-700 dark:text-zinc-300", children: [_jsx("input", { type: "radio", name: "coupon-type", value: t.value, checked: table.get("type") === t.value, onChange: () => { table.set("type", t.value); table.setPage(1); }, className: "accent-primary" }), t.label] }, t.value))), table.get("type") && (_jsx("button", { type: "button", onClick: () => { table.set("type", ""); table.setPage(1); }, className: "text-xs text-zinc-400 hover:text-zinc-600 dark:hover:text-zinc-300 underline", children: "Clear type" }))] })] }), _jsxs("div", { children: [_jsx(Heading, { level: 6, className: "text-xs font-semibold uppercase tracking-wider text-zinc-500 dark:text-zinc-400 mb-3", children: "Valid Date Range" }), _jsxs("div", { className: "space-y-3", children: [_jsxs("div", { children: [_jsx("label", { className: "block text-xs text-zinc-500 dark:text-zinc-400 mb-1", children: "From date" }), _jsx("input", { type: "date", value: table.get("dateFrom") || "", onChange: (e) => { table.set("dateFrom", e.target.value); table.setPage(1); }, className: "w-full rounded-lg border border-zinc-300 dark:border-slate-600 bg-white dark:bg-slate-800 px-3 py-2 text-sm text-zinc-900 dark:text-zinc-100 outline-none focus:ring-2 focus:ring-primary" })] }), _jsxs("div", { children: [_jsx("label", { className: "block text-xs text-zinc-500 dark:text-zinc-400 mb-1", children: "To date" }), _jsx("input", { type: "date", value: table.get("dateTo") || "", onChange: (e) => { table.set("dateTo", e.target.value); table.setPage(1); }, className: "w-full rounded-lg border border-zinc-300 dark:border-slate-600 bg-white dark:bg-slate-800 px-3 py-2 text-sm text-zinc-900 dark:text-zinc-100 outline-none focus:ring-2 focus:ring-primary" })] })] })] })] }), _jsxs("div", { className: "border-t border-zinc-200 dark:border-slate-700 px-4 py-3.5 flex gap-2", children: [_jsx("button", { type: "button", onClick: clearFilters, className: "flex-1 rounded-lg border border-zinc-300 dark:border-slate-600 py-2.5 text-sm font-medium text-zinc-700 dark:text-zinc-200 hover:bg-zinc-50 dark:hover:bg-slate-800 transition-colors", children: "Clear all" }), _jsx("button", { type: "button", onClick: () => setFilterOpen(false), className: "flex-1 rounded-lg bg-primary py-2.5 text-sm font-semibold text-white hover:bg-primary-600 transition-colors", children: "Apply" })] })] })] }))] }));
+}

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

@@ -9,12 +9,20 @@ export interface PromotionProductItem {
 export interface PromotionsViewProductSectionProps {
     title: string;
     subtitle?: string;
-    /** Render the product grid — use your app's ProductGrid/ProductCard here */
     renderProducts: () => React.ReactNode;
-    /** If false/undefined, the section is hidden */
     hasProducts?: boolean;
 }
 export declare function PromotionsViewProductSection({ title, subtitle, renderProducts, hasProducts, }: PromotionsViewProductSectionProps): import("react/jsx-runtime").JSX.Element | null;
+export interface PromotionsHeroProps {
+    labels: {
+        exclusiveOffersBadge: string;
+        title: string;
+        subtitle: string;
+    };
+    heroBannerClass?: string;
+}
+/** Slim hero banner for the promotions page — tabs + content live in the page. */
+export declare function PromotionsHero({ labels, heroBannerClass, }: PromotionsHeroProps): import("react/jsx-runtime").JSX.Element;
 export interface PromotionsViewProps {
     labels: {
         exclusiveOffersBadge: string;
@@ -32,12 +40,10 @@ export interface PromotionsViewProps {
     };
     hasContent: boolean;
     heroBannerClass?: string;
-    /** Render the coupon grid */
     renderCoupons?: () => React.ReactNode;
     couponsCount?: number;
-    /** Render the promoted products section */
     renderDealsSection?: () => React.ReactNode;
-    /** Render the featured products section */
     renderFeaturedSection?: () => React.ReactNode;
 }
+/** @deprecated Use PromotionsHero + per-tab content in your page instead. */
 export declare function PromotionsView({ labels, hasContent, heroBannerClass, renderCoupons, couponsCount, renderDealsSection, renderFeaturedSection, }: PromotionsViewProps): import("react/jsx-runtime").JSX.Element;

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

@@ -5,6 +5,11 @@ export function PromotionsViewProductSection({ title, subtitle, renderProducts,
         return null;
     return (_jsxs(Section, { children: [_jsxs(Div, { className: "mb-6", children: [_jsx(Heading, { level: 2, children: title }), subtitle && (_jsx(Text, { variant: "secondary", className: "mt-1", children: subtitle }))] }), renderProducts()] }));
 }
+/** Slim hero banner for the promotions page — tabs + content live in the page. */
+export function PromotionsHero({ labels, heroBannerClass = "bg-gradient-to-br from-rose-500 to-orange-500", }) {
+    return (_jsx(Div, { className: `${heroBannerClass} text-white py-14`, children: _jsxs(Div, { className: "max-w-5xl mx-auto px-4 sm:px-6 lg:px-8 text-center", children: [_jsxs(Text, { className: "text-white font-medium mb-2 uppercase tracking-widest text-sm", children: ["\uD83C\uDF89 ", labels.exclusiveOffersBadge] }), _jsx(Heading, { level: 1, variant: "none", className: "text-white mb-4", children: labels.title }), _jsx(Text, { variant: "none", className: "text-lg text-white/90 max-w-2xl mx-auto", children: labels.subtitle })] }) }));
+}
+/** @deprecated Use PromotionsHero + per-tab content in your page instead. */
 export function PromotionsView({ labels, hasContent, heroBannerClass = "bg-gradient-to-br from-rose-500 to-orange-500", renderCoupons, couponsCount = 0, renderDealsSection, renderFeaturedSection, }) {
-    return (_jsxs(Div, { className: "min-h-screen bg-white dark:bg-slate-900", children: [_jsx(Div, { className: `${heroBannerClass} text-white py-16`, children: _jsxs(Div, { className: "max-w-5xl mx-auto px-4 sm:px-6 lg:px-8 text-center", children: [_jsxs(Text, { className: "text-white font-medium mb-2 uppercase tracking-widest text-sm", children: ["\uD83C\uDF89 ", labels.exclusiveOffersBadge] }), _jsx(Heading, { level: 1, variant: "none", className: "text-white mb-4", children: labels.title }), _jsx(Text, { variant: "none", className: "text-lg text-white/90 max-w-2xl mx-auto", children: labels.subtitle })] }) }), _jsxs(Div, { className: "max-w-5xl mx-auto px-4 sm:px-6 lg:px-8 py-12 space-y-12", children: [!hasContent && (_jsxs(Div, { className: "text-center py-16", children: [_jsx(Heading, { level: 2, className: "mb-2", children: labels.emptyDeals }), _jsx(Text, { variant: "secondary", children: labels.checkBack })] })), hasContent && (_jsxs(Div, { className: "space-y-12", children: [_jsxs(Section, { children: [_jsxs(Div, { className: "mb-6", children: [_jsx(Heading, { level: 2, children: labels.couponsTitle }), couponsCount > 0 && (_jsx(Text, { variant: "secondary", className: "mt-1", children: labels.couponsSubtitle }))] }), couponsCount > 0 ? (renderCoupons?.()) : (_jsx(Text, { variant: "secondary", size: "sm", children: labels.emptyCoupons }))] }), renderDealsSection?.(), renderFeaturedSection?.()] }))] })] }));
+    return (_jsxs(Div, { className: "min-h-screen bg-white dark:bg-slate-900", children: [_jsx(PromotionsHero, { labels: labels, heroBannerClass: heroBannerClass }), _jsxs(Div, { className: "max-w-5xl mx-auto px-4 sm:px-6 lg:px-8 py-12 space-y-12", children: [!hasContent && (_jsxs(Div, { className: "text-center py-16", children: [_jsx(Heading, { level: 2, className: "mb-2", children: labels.emptyDeals }), _jsx(Text, { variant: "secondary", children: labels.checkBack })] })), hasContent && (_jsxs(Div, { className: "space-y-12", children: [renderCoupons && (_jsxs(Section, { children: [_jsxs(Div, { className: "mb-6", children: [_jsx(Heading, { level: 2, children: labels.couponsTitle }), couponsCount > 0 && (_jsx(Text, { variant: "secondary", className: "mt-1", children: labels.couponsSubtitle }))] }), couponsCount > 0 ? (renderCoupons()) : (_jsx(Text, { variant: "secondary", size: "sm", children: labels.emptyCoupons }))] })), renderDealsSection?.(), renderFeaturedSection?.()] }))] })] }));
 }

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

@@ -1,3 +1,5 @@
 export { CouponCard } from "./CouponCard";
-export { PromotionsView, PromotionsViewProductSection } from "./PromotionsView";
-export type { PromotionsViewProps, PromotionsViewProductSectionProps, PromotionProductItem, } from "./PromotionsView";
+export { CouponsIndexListing } from "./CouponsIndexListing";
+export type { CouponsIndexListingProps } from "./CouponsIndexListing";
+export { PromotionsView, PromotionsViewProductSection, PromotionsHero, } from "./PromotionsView";
+export type { PromotionsViewProps, PromotionsViewProductSectionProps, PromotionProductItem, PromotionsHeroProps, } from "./PromotionsView";

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

@@ -1,2 +1,3 @@
 export { CouponCard } from "./CouponCard";
-export { PromotionsView, PromotionsViewProductSection } from "./PromotionsView";
+export { CouponsIndexListing } from "./CouponsIndexListing";
+export { PromotionsView, PromotionsViewProductSection, PromotionsHero, } from "./PromotionsView";

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

@@ -3,7 +3,7 @@ interface ValidateCouponPayload {
     orderTotal?: number;
     cartItems?: Array<{
         productId: string;
-        sellerId?: string;
+        storeId?: string;
         price: number;
         quantity: number;
         isPreOrder?: boolean;

package/dist/features/promotions/hooks/usePromotions.js

@@ -7,8 +7,8 @@ export function usePromotions(params = {}, opts) {
         sp.set("scope", params.scope);
     if (params.isActive !== undefined)
         sp.set("isActive", String(params.isActive));
-    if (params.sellerId)
-        sp.set("sellerId", params.sellerId);
+    if (params.storeId)
+        sp.set("storeId", params.storeId);
     if (params.page)
         sp.set("page", String(params.page));
     if (params.pageSize)

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

@@ -52,12 +52,14 @@ export declare class CouponsRepository extends BaseRepository<CouponDocument> {
      */
     getCouponsExpiringSoon(days?: number): Promise<CouponDocument[]>;
     /**
-     * Validate coupon code (format and availability)
+     * Steps shared by all public validate methods:
+     * 1. Code format  2. DB lookup  3. Validity  4. Per-user limit
      *
-     * @param code - Coupon code to validate
-     * @param userId - User ID attempting to use coupon
-     * @param orderTotal - Order total amount (for validation)
-     * @returns Promise<{valid: boolean, coupon?: CouponDocument, message?: string}>
+     * Returns either an early-exit failure result or the resolved coupon.
+     */
+    private _fetchAndValidateCoupon;
+    /**
+     * Validate coupon against a flat order total (no cart breakdown).
      */
     validateCoupon(code: string, userId: string, orderTotal: number): Promise<{
         valid: boolean;
@@ -66,15 +68,19 @@ export declare class CouponsRepository extends BaseRepository<CouponDocument> {
         message?: string;
     }>;
     /**
-     * Apply coupon to order (increment usage counters)
+     * Record coupon usage after a successful checkout.
      *
-     * @param couponId - Coupon ID
-     * @param userId - User ID
-     * @param orderId - Order ID
-     * @param discountAmount - Applied discount amount
-     * @returns Promise<void>
+     * Increments both the global coupon counter and the per-user usage doc so
+     * that subsequent `validateCoupon` calls respect `perUserLimit` and
+     * `totalLimit` correctly.
+     *
+     * @param couponId      - Coupon document ID (e.g. "coupon-welcome10")
+     * @param couponCode    - Human-readable code (e.g. "WELCOME10")
+     * @param userId        - Buyer UID
+     * @param orderIds      - All order IDs created in this checkout that used the coupon
+     * @param discountAmount - Total discount amount applied across all order groups
      */
-    applyCoupon(couponId: string, userId: string, orderId: string, discountAmount: number): Promise<void>;
+    applyCoupon(couponId: string, couponCode: string, userId: string, orderIds: string[], discountAmount: number): Promise<void>;
     /**
      * Get user's coupon usage count for a specific coupon
      *
@@ -109,7 +115,7 @@ export declare class CouponsRepository extends BaseRepository<CouponDocument> {
      *
      * @param sellerId - The seller's user UID
      */
-    getSellerCoupons(sellerId: string): Promise<CouponDocument[]>;
+    getStoreCoupons(storeId: string): Promise<CouponDocument[]>;
     /**
      * Validate a coupon against the cart items and return a per-item breakdown.
      *
@@ -130,7 +136,7 @@ export declare class CouponsRepository extends BaseRepository<CouponDocument> {
      */
     validateCouponForCart(code: string, userId: string, cartItems: Array<{
         productId: string;
-        sellerId: string;
+        storeId: string;
         price: number;
         quantity: number;
         isPreOrder: boolean;
@@ -142,7 +148,7 @@ export declare class CouponsRepository extends BaseRepository<CouponDocument> {
         eligibleSubtotal?: number;
         eligibleProductIds?: string[];
         scope?: "admin" | "seller";
-        sellerId?: string;
+        storeId?: string;
         message?: string;
     }>;
     static readonly SIEVE_FIELDS: {

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

@@ -4,23 +4,11 @@
  * Manages coupon creation, validation, and usage tracking
  */
 import { BaseRepository, prepareForFirestore, } from "../../../providers/db-firebase";
-import { COUPONS_COLLECTION, isValidCouponCode, isCouponValid, canUserUseCoupon, calculateDiscount, createCouponId, } from "../schemas";
+import { COUPONS_COLLECTION, COUPON_FIELDS, isValidCouponCode, isCouponValid, canUserUseCoupon, calculateDiscount, createCouponId, } from "../schemas";
 import { USER_COLLECTION } from "../../auth/schemas";
 import { DatabaseError } from "../../../errors";
-import { increment, serverTimestamp } from "../../../contracts/field-ops";
+import { increment, arrayUnion, serverTimestamp } from "../../../contracts/field-ops";
 const COUPON_USAGE_SUBCOLLECTION = "couponUsage";
-const COUPON_FIELDS = {
-    CODE: "code",
-    TYPE: "type",
-    CREATED_BY: "createdBy",
-    SELLER_ID: "sellerId",
-    CREATED_AT: "createdAt",
-    VALIDITY_FIELDS: {
-        IS_ACTIVE: "validity.isActive",
-        START_DATE: "validity.startDate",
-        END_DATE: "validity.endDate",
-    },
-};
 /**
  * Repository for coupon management
  */
@@ -87,9 +75,9 @@ export class CouponsRepository extends BaseRepository {
             // validity.isActive ASC + validity.endDate ASC (see firestore.indexes.json)
             const snapshot = await this.db
                 .collection(this.collection)
-                .where(COUPON_FIELDS.VALIDITY_FIELDS.IS_ACTIVE, "==", true)
-                .where(COUPON_FIELDS.VALIDITY_FIELDS.END_DATE, ">=", now)
-                .orderBy(COUPON_FIELDS.VALIDITY_FIELDS.END_DATE, "asc")
+                .where(COUPON_FIELDS.VALIDITY.IS_ACTIVE, "==", true)
+                .where(COUPON_FIELDS.VALIDITY.END_DATE, ">=", now)
+                .orderBy(COUPON_FIELDS.VALIDITY.END_DATE, "asc")
                 .get();
             return snapshot.docs
                 .map((doc) => this.mapDoc(doc))
@@ -147,13 +135,13 @@ export class CouponsRepository extends BaseRepository {
         try {
             const now = new Date();
             const futureDate = new Date(now.getTime() + days * 24 * 60 * 60 * 1000);
-            // Firestore-native range filter — reuses the same composite index as getActiveCoupons()
+            // Firestore-native range filter — reuses the same composite index as getActiveCoupons()
             const snapshot = await this.db
                 .collection(this.collection)
-                .where(COUPON_FIELDS.VALIDITY_FIELDS.IS_ACTIVE, "==", true)
-                .where(COUPON_FIELDS.VALIDITY_FIELDS.END_DATE, ">", now)
-                .where(COUPON_FIELDS.VALIDITY_FIELDS.END_DATE, "<=", futureDate)
-                .orderBy(COUPON_FIELDS.VALIDITY_FIELDS.END_DATE, "asc")
+                .where(COUPON_FIELDS.VALIDITY.IS_ACTIVE, "==", true)
+                .where(COUPON_FIELDS.VALIDITY.END_DATE, ">", now)
+                .where(COUPON_FIELDS.VALIDITY.END_DATE, "<=", futureDate)
+                .orderBy(COUPON_FIELDS.VALIDITY.END_DATE, "asc")
                 .get();
             return snapshot.docs.map((doc) => this.mapDoc(doc));
         }
@@ -161,99 +149,91 @@ export class CouponsRepository extends BaseRepository {
             throw new DatabaseError(`Failed to retrieve expiring coupons: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
     /**
-     * Validate coupon code (format and availability)
+     * Steps shared by all public validate methods:
+     * 1. Code format  2. DB lookup  3. Validity  4. Per-user limit
      *
-     * @param code - Coupon code to validate
-     * @param userId - User ID attempting to use coupon
-     * @param orderTotal - Order total amount (for validation)
-     * @returns Promise<{valid: boolean, coupon?: CouponDocument, message?: string}>
+     * Returns either an early-exit failure result or the resolved coupon.
      */
-    async validateCoupon(code, userId, orderTotal) {
-        // Validate code format
+    async _fetchAndValidateCoupon(code, userId) {
         if (!isValidCouponCode(code)) {
-            return {
-                valid: false,
-                message: "Invalid coupon code format",
-            };
+            return { ok: false, result: { valid: false, message: "Invalid coupon code format" } };
         }
-        // Get coupon from database
         const coupon = await this.getCouponByCode(code);
         if (!coupon) {
-            return {
-                valid: false,
-                message: "Coupon not found",
-            };
+            return { ok: false, result: { valid: false, message: "Coupon not found" } };
         }
-        // Check if coupon is valid (active, date range, usage limits)
         if (!isCouponValid(coupon)) {
-            return {
-                valid: false,
-                coupon,
-                message: "Coupon is not currently valid",
-            };
+            return { ok: false, result: { valid: false, coupon, message: "Coupon is not currently valid" } };
         }
-        // Check minimum purchase requirement
-        if (coupon.discount.minPurchase &&
-            orderTotal < coupon.discount.minPurchase) {
-            return {
-                valid: false,
-                coupon,
-                message: "Minimum purchase requirement not met",
-            };
-        }
-        // Check user-specific usage limit
         const userUsageCount = await this.getUserCouponUsageCount(userId, coupon.id);
         if (!canUserUseCoupon(coupon, userUsageCount)) {
-            return {
-                valid: false,
-                coupon,
-                message: "You have reached the usage limit for this coupon",
-            };
+            return { ok: false, result: { valid: false, coupon, message: "You have reached the usage limit for this coupon" } };
+        }
+        return { ok: true, coupon };
+    }
+    // ---------------------------------------------------------------------------
+    // Public validation methods
+    // ---------------------------------------------------------------------------
+    /**
+     * Validate coupon against a flat order total (no cart breakdown).
+     */
+    async validateCoupon(code, userId, orderTotal) {
+        const check = await this._fetchAndValidateCoupon(code, userId);
+        if (!check.ok)
+            return check.result;
+        const { coupon } = check;
+        if (coupon.discount.minPurchase && orderTotal < coupon.discount.minPurchase) {
+            return { valid: false, coupon, message: "Minimum purchase requirement not met" };
         }
-        // Calculate discount
-        const discountAmount = calculateDiscount(coupon, orderTotal);
         return {
             valid: true,
             coupon,
-            discountAmount,
+            discountAmount: calculateDiscount(coupon, orderTotal),
             message: "Coupon is valid",
         };
     }
     /**
-     * Apply coupon to order (increment usage counters)
+     * Record coupon usage after a successful checkout.
      *
-     * @param couponId - Coupon ID
-     * @param userId - User ID
-     * @param orderId - Order ID
-     * @param discountAmount - Applied discount amount
-     * @returns Promise<void>
+     * Increments both the global coupon counter and the per-user usage doc so
+     * that subsequent `validateCoupon` calls respect `perUserLimit` and
+     * `totalLimit` correctly.
+     *
+     * @param couponId      - Coupon document ID (e.g. "coupon-welcome10")
+     * @param couponCode    - Human-readable code (e.g. "WELCOME10")
+     * @param userId        - Buyer UID
+     * @param orderIds      - All order IDs created in this checkout that used the coupon
+     * @param discountAmount - Total discount amount applied across all order groups
      */
-    async applyCoupon(couponId, userId, orderId, discountAmount) {
+    async applyCoupon(couponId, couponCode, userId, orderIds, discountAmount) {
         try {
             const batch = this.db.batch();
-            // Update coupon usage stats
+            // Increment global coupon counters
             const couponRef = this.db.collection(this.collection).doc(couponId);
             batch.update(couponRef, {
                 "usage.currentUsage": increment(1),
-                "stats.totalDiscountGiven": increment(discountAmount),
-                "stats.totalOrders": increment(1),
+                "stats.totalDiscount": increment(discountAmount),
+                "stats.totalUses": increment(1),
                 updatedAt: new Date(),
             });
-            // Create user coupon usage record
-            const usageData = {
-                userId,
-                couponCode: "", // Will be filled by getCouponByCode
-                orderId,
-                discountAmount,
-                usedAt: new Date(),
-            };
+            // Upsert per-user usage doc — safe for perUserLimit > 1
             const usageRef = this.db
                 .collection(USER_COLLECTION)
                 .doc(userId)
                 .collection(COUPON_USAGE_SUBCOLLECTION)
                 .doc(couponId);
-            batch.set(usageRef, prepareForFirestore(usageData));
+            // FieldValue sentinels (increment, arrayUnion) must NOT go through
+            // prepareForFirestore — it recurses into objects and Object.keys() on a
+            // FieldValue returns [] (non-enumerable internals), silently dropping them.
+            batch.set(usageRef, {
+                ...prepareForFirestore({ userId, couponCode: couponCode.toUpperCase(), lastUsedAt: new Date() }),
+                usageCount: increment(1),
+                orders: arrayUnion(...orderIds),
+            }, { merge: true });
             await batch.commit();
         }
         catch (error) {
@@ -275,7 +255,10 @@ export class CouponsRepository extends BaseRepository {
                 .collection(COUPON_USAGE_SUBCOLLECTION)
                 .doc(couponId)
                 .get();
-            return doc.exists ? 1 : 0; // Document exists = used once (per our schema)
+            if (!doc.exists)
+                return 0;
+            const data = doc.data();
+            return data.usageCount ?? 1;
         }
         catch {
             return 0;
@@ -345,17 +328,17 @@ export class CouponsRepository extends BaseRepository {
      *
      * @param sellerId - The seller's user UID
      */
-    async getSellerCoupons(sellerId) {
+    async getStoreCoupons(storeId) {
         try {
             const snapshot = await this.db
                 .collection(this.collection)
-                .where(COUPON_FIELDS.SELLER_ID, "==", sellerId)
+                .where(COUPON_FIELDS.STORE_ID, "==", storeId)
                 .orderBy(COUPON_FIELDS.CREATED_AT, "desc")
                 .get();
             return snapshot.docs.map((doc) => this.mapDoc(doc));
         }
         catch (error) {
-            throw new DatabaseError(`Failed to retrieve seller coupons: ${error instanceof Error ? error.message : "Unknown error"}`);
+            throw new DatabaseError(`Failed to retrieve store coupons: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
     /**
@@ -377,40 +360,27 @@ export class CouponsRepository extends BaseRepository {
      *          and `eligibleProductIds` (the `productId` values that qualify).
      */
     async validateCouponForCart(code, userId, cartItems) {
-        // Format check
-        if (!isValidCouponCode(code)) {
-            return { valid: false, message: "Invalid coupon code format" };
-        }
-        const coupon = await this.getCouponByCode(code);
-        if (!coupon) {
-            return { valid: false, message: "Coupon not found" };
-        }
-        if (!isCouponValid(coupon)) {
-            return { valid: false, coupon, message: "Coupon is not currently valid" };
-        }
-        const userUsageCount = await this.getUserCouponUsageCount(userId, coupon.id);
-        if (!canUserUseCoupon(coupon, userUsageCount)) {
-            return {
-                valid: false,
-                coupon,
-                message: "You have reached the usage limit for this coupon",
-            };
-        }
-        // Determine eligible items
-        // Pre-order items are always excluded
-        let eligible = cartItems.filter((item) => !item.isPreOrder);
+        const check = await this._fetchAndValidateCoupon(code, userId);
+        if (!check.ok)
+            return check.result;
+        const { coupon } = check;
+        // Determine eligible items — no blanket exclusion by product type.
+        // Coupon flags (applicableToAuctions) decide type eligibility below.
+        let eligible = [...cartItems];
         const scope = coupon.scope ?? "admin";
         if (scope === "seller") {
-            // Restrict to this seller's items
-            eligible = eligible.filter((item) => item.sellerId === coupon.sellerId);
-            if (coupon.applicableToAuctions === true) {
-                // Auction-only coupon
-                eligible = eligible.filter((item) => item.isAuction);
-            }
-            else {
-                // Regular (fixed-price) items only — exclude auctions
-                eligible = eligible.filter((item) => !item.isAuction);
-            }
+            // Restrict to this store's items
+            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 (but includes pre-orders & simple)
+        //   undefined → no restriction; applies to all product types
+        if (coupon.applicableToAuctions === true) {
+            eligible = eligible.filter((item) => item.isAuction);
+        }
+        else if (coupon.applicableToAuctions === false) {
+            eligible = eligible.filter((item) => !item.isAuction);
         }
         // Apply product/category restrictions from the coupon itself
         const { applicableProducts, applicableCategories, excludeProducts } = coupon.restrictions;
@@ -420,16 +390,18 @@ export class CouponsRepository extends BaseRepository {
         if (excludeProducts && excludeProducts.length > 0) {
             eligible = eligible.filter((item) => !excludeProducts.includes(item.productId));
         }
-        // Note: category filtering requires product metadata — skipped here but
+        // Note: category filtering requires product metadata — skipped here but
         // the restriction is stored and can be enforced by the order service.
         void applicableCategories;
         if (eligible.length === 0) {
             return {
                 valid: false,
                 coupon,
-                message: scope === "seller"
-                    ? "This coupon is not valid for the items in your cart from this store"
-                    : "No eligible items found for this coupon",
+                message: coupon.applicableToAuctions === true
+                    ? "This coupon only applies to auction items"
+                    : scope === "seller"
+                        ? "This coupon is not valid for the items in your cart from this seller"
+                        : "No eligible items found for this coupon",
             };
         }
         const eligibleSubtotal = eligible.reduce((sum, item) => sum + item.price * item.quantity, 0);
@@ -449,7 +421,7 @@ export class CouponsRepository extends BaseRepository {
             eligibleSubtotal,
             eligibleProductIds: eligible.map((item) => item.productId),
             scope,
-            sellerId: coupon.sellerId,
+            storeId: coupon.storeId,
             message: "Coupon is valid",
         };
     }
@@ -478,8 +450,8 @@ export class CouponsRepository extends BaseRepository {
     async getExpiredActiveRefs(now) {
         const snap = await this.db
             .collection(this.collection)
-            .where(COUPON_FIELDS.VALIDITY_FIELDS.IS_ACTIVE, "==", true)
-            .where(COUPON_FIELDS.VALIDITY_FIELDS.END_DATE, "<=", now)
+            .where(COUPON_FIELDS.VALIDITY.IS_ACTIVE, "==", true)
+            .where(COUPON_FIELDS.VALIDITY.END_DATE, "<=", now)
             .limit(500)
             .get();
         return snap.docs.map((d) => d.ref);
@@ -489,7 +461,7 @@ export class CouponsRepository extends BaseRepository {
      */
     deactivateInBatch(batch, ref) {
         batch.update(ref, {
-            [COUPON_FIELDS.VALIDITY_FIELDS.IS_ACTIVE]: false,
+            [COUPON_FIELDS.VALIDITY.IS_ACTIVE]: false,
             updatedAt: serverTimestamp(),
         });
     }