@mohasinac/appkit 4.13.1 → 4.15.0

package/dist/features/seller/repository/offer.repository.d.ts

@@ -4,35 +4,103 @@
  * Data access layer for the `offers` Firestore collection.
  * Handles buyer make-an-offer, seller counter/accept/decline lifecycle.
  */
-import { BaseRepository } from "../../../providers/db-firebase";
+import { BaseRepository, parseSieveDateValue } from "../../../providers/db-firebase";
 import type { SieveModel, FirebaseSieveResult } from "../../../providers/db-firebase";
 import type { OfferDocument, OfferCreateInput, OfferUpdateInput } from "../schemas";
+import { type HistoryActor } from "../../../_internal/shared/history/index";
+/**
+ * Who/why for a write that lands in an offer's `statusHistory`.
+ * Optional throughout so existing callers keep compiling and record `system`.
+ */
+export interface OfferWriteContext {
+    actor?: HistoryActor;
+    trigger?: string;
+    reason?: string;
+    note?: string;
+}
 declare class OfferRepository extends BaseRepository<OfferDocument> {
     constructor();
     /** Override mapDoc to auto-decrypt PII on every offer read */
     protected mapDoc<D = OfferDocument>(snap: import("../../../providers/db-firebase").DocumentSnapshot): D;
+    /**
+     * Every Timestamp field here carries `parseValue: parseSieveDateValue`.
+     *
+     * Without it a GTE/LTE on a Timestamp field silently matches ZERO documents:
+     * sievejs's default coercion leaves an ISO string as a string, and Firestore
+     * requires an inequality's value to match the stored type. That is Root Cause
+     * #47, and `createdAt` flipping from `canFilter: false` to `true` here is
+     * exactly the transition that introduces it.
+     *
+     * `checkoutDeadline` is added by hand: `audit-sieve-date-fields` recognises
+     * Timestamp fields by an `...At` / `...Date` / `...Time` suffix, which this
+     * name does not have, so the audit cannot flag it for you.
+     */
     static readonly SIEVE_FIELDS: {
-        readonly status: {
-            readonly canFilter: true;
-            readonly canSort: false;
+        id: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        status: {
+            canFilter: boolean;
+            canSort: boolean;
         };
-        readonly productId: {
-            readonly canFilter: true;
-            readonly canSort: false;
+        productId: {
+            canFilter: boolean;
+            canSort: boolean;
         };
-        readonly buyerUid: {
-            readonly canFilter: true;
-            readonly canSort: false;
+        productTitle: {
+            canFilter: boolean;
+            canSort: boolean;
         };
-        readonly storeId: {
-            readonly canFilter: true;
-            readonly canSort: false;
+        buyerUid: {
+            canFilter: boolean;
+            canSort: boolean;
         };
-        readonly createdAt: {
-            readonly canFilter: false;
-            readonly canSort: true;
+        buyerName: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        storeId: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        storeName: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        offerAmount: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        listedPrice: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        createdAt: {
+            canFilter: boolean;
+            canSort: boolean;
+            parseValue: typeof parseSieveDateValue;
+        };
+        expiresAt: {
+            canFilter: boolean;
+            canSort: boolean;
+            parseValue: typeof parseSieveDateValue;
+        };
+        checkoutDeadline: {
+            canFilter: boolean;
+            canSort: boolean;
+            parseValue: typeof parseSieveDateValue;
         };
     };
+    /**
+     * Paginated, Firestore-native offer list (admin use).
+     *
+     * Mirrors `BidRepository.list`. The seller- and buyer-scoped reads have their
+     * own dedicated methods (`findByStore` / `findByBuyer`) because they carry
+     * mandatory ownership filters; this one is deliberately unscoped and is only
+     * reachable behind `admin:offers:read`.
+     */
+    list(model: SieveModel): Promise<FirebaseSieveResult<OfferDocument>>;
     create(input: OfferCreateInput): Promise<OfferDocument>;
     findByBuyer(buyerUid: string, model?: SieveModel): Promise<FirebaseSieveResult<OfferDocument>>;
     findByStore(storeId: string, model?: SieveModel): Promise<FirebaseSieveResult<OfferDocument>>;
@@ -50,12 +118,32 @@ declare class OfferRepository extends BaseRepository<OfferDocument> {
      * `product.updatedAt` advances past the previously-created offer dates.
      */
     countByBuyerAndProduct(buyerUid: string, productId: string, since: Date): Promise<number>;
-    updateStatus(offerId: string, patch: OfferUpdateInput): Promise<OfferDocument>;
-    accept(offerId: string, lockedPrice: number, sellerNote?: string, checkoutDeadline?: Date): Promise<OfferDocument>;
-    decline(offerId: string, sellerNote?: string): Promise<OfferDocument>;
-    counter(offerId: string, counterAmount: number, sellerNote?: string): Promise<OfferDocument>;
-    acceptCounter(offerId: string, checkoutDeadline?: Date): Promise<OfferDocument>;
-    withdraw(offerId: string): Promise<OfferDocument>;
+    /**
+     * The single write choke point for offers, so `statusHistory` is appended
+     * in ONE place rather than at every call site — the same shape
+     * `OrderRepository.updateWithHistory` uses.
+     *
+     * `prior` is the already-fetched document when the caller has one. Every
+     * real caller does (`respondToOffer`, `acceptCounterOffer`, `withdrawOffer`,
+     * `counterOfferByBuyer`, `finalizeLockedLines`, the admin PATCH, both expiry
+     * sweeps), so threading it through means history costs **zero extra reads**.
+     */
+    updateStatus(offerId: string, patch: OfferUpdateInput, ctx?: OfferWriteContext, prior?: OfferDocument | null): Promise<OfferDocument>;
+    accept(offerId: string, lockedPrice: number, sellerNote?: string, checkoutDeadline?: Date, ctx?: OfferWriteContext, prior?: OfferDocument | null): Promise<OfferDocument>;
+    decline(offerId: string, sellerNote?: string, ctx?: OfferWriteContext, prior?: OfferDocument | null): Promise<OfferDocument>;
+    counter(offerId: string, counterAmount: number, sellerNote?: string, ctx?: OfferWriteContext, prior?: OfferDocument | null): Promise<OfferDocument>;
+    acceptCounter(offerId: string, checkoutDeadline?: Date, ctx?: OfferWriteContext, prior?: OfferDocument | null): Promise<OfferDocument>;
+    /**
+     * Two distinct events share this method:
+     *  - the buyer walks away        → status alone
+     *  - the buyer counters          → status + `supersededByOfferId`
+     *
+     * The second is what makes the chain walkable forward, and it is ONE write
+     * with ONE history entry. A `withdrawn` document carrying
+     * `supersededByOfferId` renders as *Superseded* (neutral) rather than
+     * *Withdrawn* (negative) — the negotiation continued, it did not end.
+     */
+    withdraw(offerId: string, supersededByOfferId?: string, ctx?: OfferWriteContext, prior?: OfferDocument | null): Promise<OfferDocument>;
     /**
      * Terminal transition, called once the buyer's order for this offer exists.
      *
@@ -64,7 +152,21 @@ declare class OfferRepository extends BaseRepository<OfferDocument> {
      * client-side patch in UserOffersPanel, which meant a reload showed the offer
      * back at "accepted" and it could be added to the cart and ordered again.
      */
-    markPaid(offerId: string, orderId: string): Promise<OfferDocument>;
+    markPaid(offerId: string, orderId: string, prior?: OfferDocument | null): Promise<OfferDocument>;
+    /**
+     * Every round of one negotiation, oldest first.
+     *
+     * A single-field equality — served by Firestore's AUTOMATIC index, so this
+     * adds no composite index and none of the existing `offers` indexes is
+     * affected. The sort is done in memory because the result is at most 3 rows
+     * (the per-buyer offer limit), which is cheaper than the index a compound
+     * orderBy would demand.
+     *
+     * Offers written before `chainRootOfferId` existed return ZERO rows, not
+     * one — callers must fall back to `[offer]` and never read empty as
+     * "this offer is missing".
+     */
+    findChain(chainRootOfferId: string): Promise<OfferDocument[]>;
     /**
      * Cloud Functions compatibility: pending/countered offers already expired.
      */
@@ -76,7 +178,23 @@ declare class OfferRepository extends BaseRepository<OfferDocument> {
      * price remained claimable long after the seller expected it to lapse.
      */
     findExpiredAccepted(now: Date): Promise<OfferDocument[]>;
-    expireMany(offerIds: string[]): Promise<void>;
+    /**
+     * Bulk-expire, taking the DOCUMENTS rather than their ids.
+     *
+     * The signature changed deliberately. `arrayUnion` would let a batch append
+     * without a read, but it **cannot enforce the FIFO cap** — so history would
+     * grow unbounded on exactly the path that touches the most documents at
+     * once. Folding entries in memory and writing whole arrays keeps the cap,
+     * and costs **zero extra reads**: `findExpiredActive`, `findExpiredAccepted`
+     * and the admin cancel route all already hold full `OfferDocument`s.
+     *
+     * Also carries the admin path: a reasoned cancel is an expiry with an actor
+     * and a reason, recorded in the offer's own history as well as in
+     * `adminAuditLog`.
+     */
+    expireMany(offers: OfferDocument[], ctx?: OfferWriteContext & {
+        cancelledByAdminUid?: string;
+    }): Promise<void>;
 }
 export declare const offerRepository: OfferRepository;
 export { OfferRepository };

package/dist/features/seller/repository/offer.repository.js

@@ -4,9 +4,12 @@
  * Data access layer for the `offers` Firestore collection.
  * Handles buyer make-an-offer, seller counter/accept/decline lifecycle.
  */
-import { BaseRepository, prepareForFirestore, } from "../../../providers/db-firebase";
-import { OFFER_COLLECTION, OFFER_FIELDS, createOfferId } from "../schemas";
+import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
+import { OFFER_COLLECTION, OFFER_FIELDS, OFFER_TRACKED_FIELDS, createOfferId } from "../schemas";
+import { withHistory } from "../../../_internal/shared/history/index";
 import { encryptPiiFields, decryptPiiFields, OFFER_PII_FIELDS, } from "../../../security";
+/** Max rounds in one negotiation chain — matches the per-buyer offer limit. */
+const OFFER_CHAIN_MAX = 3;
 class OfferRepository extends BaseRepository {
     constructor() {
         super(OFFER_COLLECTION);
@@ -18,6 +21,20 @@ class OfferRepository extends BaseRepository {
             ...OFFER_PII_FIELDS,
         ]);
     }
+    /**
+     * Paginated, Firestore-native offer list (admin use).
+     *
+     * Mirrors `BidRepository.list`. The seller- and buyer-scoped reads have their
+     * own dedicated methods (`findByStore` / `findByBuyer`) because they carry
+     * mandatory ownership filters; this one is deliberately unscoped and is only
+     * reachable behind `admin:offers:read`.
+     */
+    async list(model) {
+        return this.sieveQuery(model, OfferRepository.SIEVE_FIELDS, {
+            defaultPageSize: 50,
+            maxPageSize: 200,
+        });
+    }
     // --- Create --------------------------------------------------------------
     async create(input) {
         const now = new Date();
@@ -33,6 +50,13 @@ class OfferRepository extends BaseRepository {
             expiresAt,
             createdAt: now,
             updatedAt: now,
+            // The root of a chain stores its OWN id. Without this, round 1 is the
+            // only document with no `chainRootOfferId`, so `findChain(root.id)`
+            // would return rounds 2..N and silently omit the round the buyer
+            // actually started with. Set here rather than at the call site because
+            // the id is generated in this method.
+            chainRootOfferId: input.chainRootOfferId ?? id,
+            counterRound: input.counterRound ?? 1,
         };
         // Encrypt PII fields before persisting
         const encrypted = encryptPiiFields({ ...data }, [...OFFER_PII_FIELDS]);
@@ -128,13 +152,35 @@ class OfferRepository extends BaseRepository {
         return snap.size;
     }
     // --- Mutations -----------------------------------------------------------
-    async updateStatus(offerId, patch) {
-        return this.update(offerId, {
-            ...patch,
-            updatedAt: new Date(),
+    /**
+     * The single write choke point for offers, so `statusHistory` is appended
+     * in ONE place rather than at every call site — the same shape
+     * `OrderRepository.updateWithHistory` uses.
+     *
+     * `prior` is the already-fetched document when the caller has one. Every
+     * real caller does (`respondToOffer`, `acceptCounterOffer`, `withdrawOffer`,
+     * `counterOfferByBuyer`, `finalizeLockedLines`, the admin PATCH, both expiry
+     * sweeps), so threading it through means history costs **zero extra reads**.
+     */
+    async updateStatus(offerId, patch, ctx, prior) {
+        const full = { ...patch, updatedAt: new Date() };
+        const current = prior !== undefined ? prior : await this.findById(offerId);
+        const withEntry = withHistory(current, full, {
+            tracked: OFFER_TRACKED_FIELDS,
+            actor: ctx?.actor ?? { role: "system" },
+            trigger: ctx?.trigger ?? "offerRepository.updateStatus",
+            reason: ctx?.reason,
+            note: ctx?.note,
+            // buyerName/buyerEmail live on this document. `encryptPiiFields` is a
+            // flat top-level loop and never descends into arrays, so without this
+            // they would persist in PLAINTEXT inside statusHistory.
+            piiFields: OFFER_PII_FIELDS,
+            historyField: OFFER_FIELDS.STATUS_HISTORY,
+            truncatedField: OFFER_FIELDS.STATUS_HISTORY_TRUNCATED,
         });
+        return this.update(offerId, (withEntry ?? full));
     }
-    async accept(offerId, lockedPrice, sellerNote, checkoutDeadline) {
+    async accept(offerId, lockedPrice, sellerNote, checkoutDeadline, ctx, prior) {
         // One write, not two. `checkoutDeadline` used to be missing from
         // OfferUpdateInput, which forced callers to follow every accept() with a
         // separate generic update() — leaving a window where an offer was
@@ -146,25 +192,28 @@ class OfferRepository extends BaseRepository {
             acceptedAt: new Date(),
             respondedAt: new Date(),
             ...(checkoutDeadline ? { checkoutDeadline } : {}),
-        });
+        }, { actor: { role: "seller" }, trigger: "respondToOffer:accept", note: sellerNote, ...ctx }, prior);
     }
-    async decline(offerId, sellerNote) {
+    async decline(offerId, sellerNote, ctx, prior) {
         return this.updateStatus(offerId, {
             status: "declined",
             sellerNote,
             respondedAt: new Date(),
-        });
+        }, { actor: { role: "seller" }, trigger: "respondToOffer:decline", note: sellerNote, ...ctx }, prior);
     }
-    async counter(offerId, counterAmount, sellerNote) {
+    async counter(offerId, counterAmount, sellerNote, ctx, prior) {
         return this.updateStatus(offerId, {
             status: "countered",
             counterAmount,
             sellerNote,
             respondedAt: new Date(),
-        });
+        }, { actor: { role: "seller" }, trigger: "respondToOffer:counter", note: sellerNote, ...ctx }, prior);
     }
-    async acceptCounter(offerId, checkoutDeadline) {
-        const offer = await this.findById(offerId);
+    async acceptCounter(offerId, checkoutDeadline, ctx, prior) {
+        // Reuse the caller's document when supplied — this method used to always
+        // re-read, so passing `prior` makes the feature land one read CHEAPER
+        // than before rather than one more expensive.
+        const offer = prior !== undefined && prior !== null ? prior : await this.findById(offerId);
         if (!offer || !offer.counterAmount)
             throw new Error("Offer or counter not found");
         return this.updateStatus(offerId, {
@@ -173,13 +222,29 @@ class OfferRepository extends BaseRepository {
             acceptedAt: new Date(),
             respondedAt: new Date(),
             ...(checkoutDeadline ? { checkoutDeadline } : {}),
-        });
+        }, { actor: { role: "buyer" }, trigger: "acceptCounterOffer", ...ctx }, offer);
     }
-    async withdraw(offerId) {
+    /**
+     * Two distinct events share this method:
+     *  - the buyer walks away        → status alone
+     *  - the buyer counters          → status + `supersededByOfferId`
+     *
+     * The second is what makes the chain walkable forward, and it is ONE write
+     * with ONE history entry. A `withdrawn` document carrying
+     * `supersededByOfferId` renders as *Superseded* (neutral) rather than
+     * *Withdrawn* (negative) — the negotiation continued, it did not end.
+     */
+    async withdraw(offerId, supersededByOfferId, ctx, prior) {
         return this.updateStatus(offerId, {
             status: "withdrawn",
             respondedAt: new Date(),
-        });
+            ...(supersededByOfferId ? { supersededByOfferId } : {}),
+        }, {
+            actor: { role: "buyer" },
+            trigger: supersededByOfferId ? "counterOfferByBuyer:supersede" : "withdrawOffer",
+            ...(supersededByOfferId ? { reason: "Superseded by the buyer's counter" } : {}),
+            ...ctx,
+        }, prior);
     }
     /**
      * Terminal transition, called once the buyer's order for this offer exists.
@@ -189,12 +254,35 @@ class OfferRepository extends BaseRepository {
      * client-side patch in UserOffersPanel, which meant a reload showed the offer
      * back at "accepted" and it could be added to the cart and ordered again.
      */
-    async markPaid(offerId, orderId) {
+    async markPaid(offerId, orderId, prior) {
         return this.updateStatus(offerId, {
             status: "paid",
             paidOrderId: orderId,
             paidAt: new Date(),
-        });
+        }, { actor: { role: "system" }, trigger: "finalizeLockedLines" }, prior);
+    }
+    /**
+     * Every round of one negotiation, oldest first.
+     *
+     * A single-field equality — served by Firestore's AUTOMATIC index, so this
+     * adds no composite index and none of the existing `offers` indexes is
+     * affected. The sort is done in memory because the result is at most 3 rows
+     * (the per-buyer offer limit), which is cheaper than the index a compound
+     * orderBy would demand.
+     *
+     * Offers written before `chainRootOfferId` existed return ZERO rows, not
+     * one — callers must fall back to `[offer]` and never read empty as
+     * "this offer is missing".
+     */
+    async findChain(chainRootOfferId) {
+        const snapshot = await this.db
+            .collection(this.collection)
+            .where(OFFER_FIELDS.CHAIN_ROOT_OFFER_ID, "==", chainRootOfferId)
+            .limit(OFFER_CHAIN_MAX)
+            .get();
+        return snapshot.docs
+            .map((doc) => this.mapDoc(doc))
+            .sort((a, b) => (a.counterRound ?? 1) - (b.counterRound ?? 1));
     }
     /**
      * Cloud Functions compatibility: pending/countered offers already expired.
@@ -223,24 +311,75 @@ class OfferRepository extends BaseRepository {
             .get();
         return snapshot.docs.map((doc) => this.mapDoc(doc));
     }
-    async expireMany(offerIds) {
+    /**
+     * Bulk-expire, taking the DOCUMENTS rather than their ids.
+     *
+     * The signature changed deliberately. `arrayUnion` would let a batch append
+     * without a read, but it **cannot enforce the FIFO cap** — so history would
+     * grow unbounded on exactly the path that touches the most documents at
+     * once. Folding entries in memory and writing whole arrays keeps the cap,
+     * and costs **zero extra reads**: `findExpiredActive`, `findExpiredAccepted`
+     * and the admin cancel route all already hold full `OfferDocument`s.
+     *
+     * Also carries the admin path: a reasoned cancel is an expiry with an actor
+     * and a reason, recorded in the offer's own history as well as in
+     * `adminAuditLog`.
+     */
+    async expireMany(offers, ctx) {
+        if (offers.length === 0)
+            return;
         const batch = this.db.batch();
         const now = new Date();
-        for (const id of offerIds) {
-            batch.update(this.db.collection(this.collection).doc(id), {
-                [OFFER_FIELDS.STATUS]: "expired",
-                [OFFER_FIELDS.UPDATED_AT]: now,
+        for (const offer of offers) {
+            const patch = {
+                status: "expired",
+                updatedAt: now,
+                ...(ctx?.cancelledByAdminUid
+                    ? { cancelledByAdminUid: ctx.cancelledByAdminUid, cancelReason: ctx.reason }
+                    : {}),
+            };
+            const withEntry = withHistory(offer, patch, {
+                tracked: OFFER_TRACKED_FIELDS,
+                actor: ctx?.actor ?? { role: "system" },
+                trigger: ctx?.trigger ?? "runOfferExpiry",
+                reason: ctx?.reason,
+                piiFields: OFFER_PII_FIELDS,
+                historyField: OFFER_FIELDS.STATUS_HISTORY,
+                truncatedField: OFFER_FIELDS.STATUS_HISTORY_TRUNCATED,
+                now,
             });
+            batch.update(this.db.collection(this.collection).doc(offer.id), (withEntry ?? patch));
         }
         await batch.commit();
     }
 }
+/**
+ * Every Timestamp field here carries `parseValue: parseSieveDateValue`.
+ *
+ * Without it a GTE/LTE on a Timestamp field silently matches ZERO documents:
+ * sievejs's default coercion leaves an ISO string as a string, and Firestore
+ * requires an inequality's value to match the stored type. That is Root Cause
+ * #47, and `createdAt` flipping from `canFilter: false` to `true` here is
+ * exactly the transition that introduces it.
+ *
+ * `checkoutDeadline` is added by hand: `audit-sieve-date-fields` recognises
+ * Timestamp fields by an `...At` / `...Date` / `...Time` suffix, which this
+ * name does not have, so the audit cannot flag it for you.
+ */
 OfferRepository.SIEVE_FIELDS = {
-    status: { canFilter: true, canSort: false },
+    id: { canFilter: true, canSort: false },
+    status: { canFilter: true, canSort: true },
     productId: { canFilter: true, canSort: false },
+    productTitle: { canFilter: true, canSort: true },
     buyerUid: { canFilter: true, canSort: false },
+    buyerName: { canFilter: true, canSort: true },
     storeId: { canFilter: true, canSort: false },
-    createdAt: { canFilter: false, canSort: true },
+    storeName: { canFilter: true, canSort: true },
+    offerAmount: { canFilter: true, canSort: true },
+    listedPrice: { canFilter: true, canSort: true },
+    createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    expiresAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
+    checkoutDeadline: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
 };
 export const offerRepository = new OfferRepository();
 export { OfferRepository };

package/dist/features/seller/schemas/coupon-form.d.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export declare const sellerCouponFormSchema: z.ZodEffects<z.ZodObject<{
+    code: z.ZodString;
+    type: z.ZodEnum<["percentage", "fixed", "free_shipping"]>;
+    value: z.ZodEffects<z.ZodString, string, string>;
+    minPurchase: z.ZodEffects<z.ZodString, string, string>;
+    maxDiscount: z.ZodEffects<z.ZodString, string, string>;
+    totalLimit: z.ZodEffects<z.ZodString, string, string>;
+    perUserLimit: z.ZodEffects<z.ZodString, string, string>;
+    startDate: z.ZodString;
+    endDate: z.ZodString;
+    isActive: z.ZodBoolean;
+    applicableProducts: z.ZodArray<z.ZodString, "many">;
+    applicableCategories: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    code: string;
+    type: "fixed" | "percentage" | "free_shipping";
+    isActive: boolean;
+    endDate: string;
+    maxDiscount: string;
+    minPurchase: string;
+    applicableProducts: string[];
+    applicableCategories: string[];
+    totalLimit: string;
+    perUserLimit: string;
+    startDate: string;
+}, {
+    value: string;
+    code: string;
+    type: "fixed" | "percentage" | "free_shipping";
+    isActive: boolean;
+    endDate: string;
+    maxDiscount: string;
+    minPurchase: string;
+    applicableProducts: string[];
+    applicableCategories: string[];
+    totalLimit: string;
+    perUserLimit: string;
+    startDate: string;
+}>, {
+    value: string;
+    code: string;
+    type: "fixed" | "percentage" | "free_shipping";
+    isActive: boolean;
+    endDate: string;
+    maxDiscount: string;
+    minPurchase: string;
+    applicableProducts: string[];
+    applicableCategories: string[];
+    totalLimit: string;
+    perUserLimit: string;
+    startDate: string;
+}, {
+    value: string;
+    code: string;
+    type: "fixed" | "percentage" | "free_shipping";
+    isActive: boolean;
+    endDate: string;
+    maxDiscount: string;
+    minPurchase: string;
+    applicableProducts: string[];
+    applicableCategories: string[];
+    totalLimit: string;
+    perUserLimit: string;
+    startDate: string;
+}>;
+export type SellerCouponFormValues = z.infer<typeof sellerCouponFormSchema>;

package/dist/features/seller/schemas/coupon-form.js

@@ -0,0 +1,116 @@
+/*
+ * WHY: `SellerCouponEditorView` rendered `<Form onSubmit noValidate>` with no
+ *      schema at all, while `AdminCouponEditorView` — the same entity, one
+ *      portal over — has a Zod schema wired through `<Form schema>`. The
+ *      seller side relied on four hand-rolled `if` checks that covered
+ *      presence and date order and nothing else, so a coupon could be saved
+ *      with a **500% discount**, a non-numeric value, a negative minimum spend
+ *      or a per-user limit above the total limit. Every failure surfaced in a
+ *      single banner rather than on the field that caused it.
+ * WHAT: The seller coupon form's schema.
+ *
+ * ## Everything is a string, on purpose
+ *
+ * `CouponEditorDraft` holds every numeric field as a string because they come
+ * from `<input>`s. Coercing inside the schema keeps that boundary in one place
+ * — the alternative is a `Number()` at each call site, which is how a `NaN`
+ * reaches Firestore the first time one is forgotten.
+ *
+ * ## Why the rules are conditional
+ *
+ * `free_shipping` has no discount value, `percentage` is bounded 1–100, and
+ * `fixed` is any positive amount. A flat per-field rule cannot say that, so
+ * the cross-field rules live in one `superRefine` keyed by type.
+ *
+ * EXPORTS:
+ *   sellerCouponFormSchema, type SellerCouponFormValues
+ *
+ * @tag domain:seller,promotions
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:SellerCouponEditorView
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+/** A blank optional numeric string — the form's "not set". */
+const numericString = (label) => z
+    .string()
+    .refine((v) => v.trim() === "" || (!Number.isNaN(Number(v)) && Number(v) >= 0), {
+    message: `${label} must be a number of zero or more.`,
+});
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export const sellerCouponFormSchema = z
+    .object({
+    code: annotate(z
+        .string()
+        .min(2, "A coupon code needs at least 2 characters.")
+        .max(40, "Keep the code under 40 characters.")
+        .regex(/^[A-Z0-9_-]+$/i, "Use letters, numbers, hyphens and underscores only."), {
+        section: "basics", sectionLabel: "Coupon", sectionRequired: true,
+        quick: true, order: 1, row: "pair",
+    }),
+    type: annotate(z.enum(["percentage", "fixed", "free_shipping"]), {
+        section: "basics", quick: true, order: 2, row: "pair",
+    }),
+    value: annotate(numericString("The discount value"), {
+        section: "basics", quick: true, order: 3, row: "pair",
+    }),
+    minPurchase: annotate(numericString("Minimum purchase"), {
+        section: "limits", sectionLabel: "Limits", order: 1, row: "pair",
+    }),
+    maxDiscount: annotate(numericString("Maximum discount"), {
+        section: "limits", order: 2, row: "pair",
+    }),
+    totalLimit: annotate(numericString("Total uses"), {
+        section: "limits", order: 3, row: "pair",
+    }),
+    perUserLimit: annotate(numericString("Uses per customer"), {
+        section: "limits", order: 4, row: "pair",
+    }),
+    startDate: annotate(z.string().min(1, "A start date is required."), {
+        section: "validity", sectionLabel: "Validity", quick: true, order: 1, row: "pair", kind: "date",
+    }),
+    endDate: annotate(z.string().min(1, "An end date is required."), {
+        section: "validity", quick: true, order: 2, row: "pair", kind: "date",
+    }),
+    isActive: annotate(z.boolean(), {
+        section: "validity", order: 3, row: "quarter",
+    }),
+    applicableProducts: annotate(z.array(z.string()), {
+        section: "scope", sectionLabel: "Applies to", order: 1, row: "full", kind: "list",
+    }),
+    applicableCategories: annotate(z.array(z.string()), {
+        section: "scope", order: 2, row: "full", kind: "list",
+    }),
+})
+    .superRefine((v, ctx) => {
+    const issue = (path, message) => ctx.addIssue({ code: z.ZodIssueCode.custom, path: [path], message });
+    // A discount value is required for everything except free shipping, and
+    // a percentage above 100 is not a discount — it is the store paying the
+    // customer. Nothing bounded this before.
+    if (v.type !== "free_shipping") {
+        const amount = Number(v.value);
+        if (v.value.trim() === "")
+            issue("value", "A discount value is required.");
+        else if (amount <= 0)
+            issue("value", "The discount must be greater than zero.");
+        else if (v.type === "percentage" && amount > 100) {
+            issue("value", "A percentage discount cannot exceed 100%.");
+        }
+    }
+    if (v.startDate && v.endDate && v.startDate > v.endDate) {
+        issue("endDate", "The end date must be after the start date.");
+    }
+    // A per-customer limit above the total makes the total unreachable — the
+    // coupon reads as more generous than it can ever be.
+    const total = Number(v.totalLimit);
+    const perUser = Number(v.perUserLimit);
+    if (v.totalLimit.trim() && v.perUserLimit.trim() && perUser > total) {
+        issue("perUserLimit", "Uses per customer cannot exceed the total uses.");
+    }
+});