@mohasinac/appkit 4.14.0 → 4.16.0

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

@@ -7,6 +7,17 @@
 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 */
@@ -107,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.
      *
@@ -121,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.
      */
@@ -133,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

@@ -5,8 +5,11 @@
  * Handles buyer make-an-offer, seller counter/accept/decline lifecycle.
  */
 import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
-import { OFFER_COLLECTION, OFFER_FIELDS, createOfferId } from "../schemas";
+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);
@@ -47,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]);
@@ -142,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
@@ -160,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, {
@@ -187,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.
@@ -203,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.
@@ -237,14 +311,44 @@ 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();
     }

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.");
+    }
+});

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

@@ -3,6 +3,7 @@
  */
 import { type GenerateOfferIdInput } from "../../../utils/id-generators";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+import type { StatusChangeEntry } from "../../../_internal/shared/history/index";
 export type OfferStatus = "pending" | "accepted" | "declined" | "countered" | "expired" | "withdrawn" | "paid";
 /** Runtime-accessible offer status values — use instead of bare string literals. */
 export declare const OfferStatusValues: {
@@ -39,7 +40,52 @@ export interface OfferDocument extends BaseDocument {
     /** Set by `markPaid` once the buyer's order exists — makes "paid" auditable. */
     paidOrderId?: string;
     paidAt?: Date;
+    /**
+     * Append-only delta log — the canonical record of when things happened to
+     * this offer. Shares `StatusChangeEntry` with `OrderDocument`; an offer is
+     * an order with more phases in front of it.
+     *
+     * `respondedAt` is deliberately kept but NOT extended: it means four
+     * different events (seller-accept, seller-decline, seller-counter,
+     * buyer-withdraw) and survives only as the legacy fallback for offers
+     * written before this field existed.
+     */
+    statusHistory?: StatusChangeEntry[];
+    /** Entries dropped off the front — so the UI never implies "this is all of it". */
+    statusHistoryTruncated?: number;
+    /**
+     * The multi-round chain. A counter-offer is a NEW document, so without
+     * these three a three-round negotiation is three unrelated records —
+     * which is what it is today: `previousOfferId` currently exists only
+     * inside a `serverLogger.info` call and never reaches Firestore.
+     */
+    previousOfferId?: string;
+    supersededByOfferId?: string;
+    /**
+     * Denormalised root of the chain (the root stores its own id) so a list row
+     * renders "Round 2" with ZERO extra reads, and `findChain` is a single-field
+     * equality served by the automatic index — no composite index needed.
+     */
+    chainRootOfferId?: string;
+    /** 1-based. Absent means round 1. */
+    counterRound?: number;
+    /**
+     * Admin escalation. The store keeps sole authority to accept/counter/
+     * decline; an admin may only cancel, with a reason, and it is recorded
+     * here as well as in `adminAuditLog`.
+     */
+    cancelledByAdminUid?: string;
+    cancelReason?: string;
 }
+/**
+ * Fields whose changes are recorded in an offer's `statusHistory`.
+ *
+ * Excludes `buyerName`/`buyerEmail` (PII — `encryptPiiFields` never descends
+ * into arrays, so they would persist in plaintext inside the history),
+ * `buyerNote`/`sellerNote` (they ride in the entry's `note`), and
+ * `updatedAt`/`respondedAt` (noise that would burn the FIFO cap).
+ */
+export declare const OFFER_TRACKED_FIELDS: readonly ["status", "offerAmount", "counterAmount", "lockedPrice", "checkoutDeadline", "paidOrderId", "supersededByOfferId", "previousOfferId"];
 export declare const OFFER_COLLECTION: "offers";
 export declare const OFFER_INDEXED_FIELDS: readonly ["buyerUid", "storeId", "productId", "status", "createdAt", "expiresAt", "checkoutDeadline"];
 export declare const OFFER_FIELDS: {
@@ -67,9 +113,17 @@ export declare const OFFER_FIELDS: {
     readonly PAID_AT: "paidAt";
     readonly CREATED_AT: "createdAt";
     readonly UPDATED_AT: "updatedAt";
+    readonly STATUS_HISTORY: "statusHistory";
+    readonly STATUS_HISTORY_TRUNCATED: "statusHistoryTruncated";
+    readonly PREVIOUS_OFFER_ID: "previousOfferId";
+    readonly SUPERSEDED_BY_OFFER_ID: "supersededByOfferId";
+    readonly CHAIN_ROOT_OFFER_ID: "chainRootOfferId";
+    readonly COUNTER_ROUND: "counterRound";
+    readonly CANCELLED_BY_ADMIN_UID: "cancelledByAdminUid";
+    readonly CANCEL_REASON: "cancelReason";
 };
-export type OfferCreateInput = Pick<OfferDocument, "productId" | "productTitle" | "productSlug" | "productImageUrl" | "buyerUid" | "buyerName" | "buyerEmail" | "storeId" | "storeName" | "offerAmount" | "listedPrice" | "currency" | "buyerNote">;
-export type OfferUpdateInput = Partial<Pick<OfferDocument, "status" | "counterAmount" | "lockedPrice" | "sellerNote" | "acceptedAt" | "checkoutDeadline" | "respondedAt" | "paidOrderId" | "paidAt" | "updatedAt">>;
+export type OfferCreateInput = Pick<OfferDocument, "productId" | "productTitle" | "productSlug" | "productImageUrl" | "buyerUid" | "buyerName" | "buyerEmail" | "storeId" | "storeName" | "offerAmount" | "listedPrice" | "currency" | "buyerNote" | "previousOfferId" | "chainRootOfferId" | "counterRound">;
+export type OfferUpdateInput = Partial<Pick<OfferDocument, "status" | "counterAmount" | "lockedPrice" | "sellerNote" | "acceptedAt" | "checkoutDeadline" | "respondedAt" | "paidOrderId" | "paidAt" | "updatedAt" | "statusHistory" | "statusHistoryTruncated" | "supersededByOfferId" | "cancelledByAdminUid" | "cancelReason">>;
 export declare const offerQueryHelpers: {
     readonly byBuyer: (buyerUid: string) => readonly ["buyerUid", "==", string];
     readonly byStore: (storeId: string) => readonly ["storeId", "==", string];

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

@@ -12,6 +12,24 @@ export const OfferStatusValues = {
     WITHDRAWN: "withdrawn",
     PAID: "paid",
 };
+/**
+ * Fields whose changes are recorded in an offer's `statusHistory`.
+ *
+ * Excludes `buyerName`/`buyerEmail` (PII — `encryptPiiFields` never descends
+ * into arrays, so they would persist in plaintext inside the history),
+ * `buyerNote`/`sellerNote` (they ride in the entry's `note`), and
+ * `updatedAt`/`respondedAt` (noise that would burn the FIFO cap).
+ */
+export const OFFER_TRACKED_FIELDS = [
+    "status",
+    "offerAmount",
+    "counterAmount",
+    "lockedPrice",
+    "checkoutDeadline",
+    "paidOrderId",
+    "supersededByOfferId",
+    "previousOfferId",
+];
 export const OFFER_COLLECTION = "offers";
 export const OFFER_INDEXED_FIELDS = [
     "buyerUid",
@@ -47,6 +65,15 @@ export const OFFER_FIELDS = {
     PAID_AT: "paidAt",
     CREATED_AT: "createdAt",
     UPDATED_AT: "updatedAt",
+    // Negotiation history + chain (W2)
+    STATUS_HISTORY: "statusHistory",
+    STATUS_HISTORY_TRUNCATED: "statusHistoryTruncated",
+    PREVIOUS_OFFER_ID: "previousOfferId",
+    SUPERSEDED_BY_OFFER_ID: "supersededByOfferId",
+    CHAIN_ROOT_OFFER_ID: "chainRootOfferId",
+    COUNTER_ROUND: "counterRound",
+    CANCELLED_BY_ADMIN_UID: "cancelledByAdminUid",
+    CANCEL_REASON: "cancelReason",
 };
 export const offerQueryHelpers = {
     byBuyer: (buyerUid) => ["buyerUid", "==", buyerUid],

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

@@ -89,8 +89,8 @@ export declare const sellerStoreSchema: z.ZodObject<{
     id: string;
     createdAt: string;
     updatedAt: string;
-    ownerId: string;
     storeName: string;
+    ownerId: string;
     storeSlug: string;
     isPublic: boolean;
     location?: string | undefined;
@@ -121,8 +121,8 @@ export declare const sellerStoreSchema: z.ZodObject<{
     id: string;
     createdAt: string;
     updatedAt: string;
-    ownerId: string;
     storeName: string;
+    ownerId: string;
     storeSlug: string;
     isPublic: boolean;
     location?: string | undefined;