@mohasinac/appkit 4.22.0 → 4.24.0

package/dist/features/auctions/repository/bid.repository.js

@@ -6,7 +6,8 @@ import { normalizeError } from "../../../errors/normalize";
  */
 import { BaseRepository, getFirestoreCount, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
 import { DatabaseError } from "../../../errors";
-import { BID_COLLECTION, createBidId } from "../schemas";
+import { BID_COLLECTION, BID_TRACKED_FIELDS, BID_HISTORY_PII_FIELDS, createBidId } from "../schemas";
+import { withHistory } from "../../../_internal/shared/history/index";
 import { encryptPiiFields, decryptPiiFields, BID_PII_FIELDS, } from "../../../security";
 import { BID_FIELDS } from "../../../constants/field-names";
 export class BidRepository extends BaseRepository {
@@ -115,12 +116,21 @@ export class BidRepository extends BaseRepository {
             data: this.mapDoc(doc),
         };
     }
-    markWon(batch, ref) {
-        batch.update(ref, {
-            status: "won",
-            isWinning: true,
-            updatedAt: new Date(),
-        });
+    /*
+     * ── Batch mutators ─────────────────────────────────────────────────────
+     *
+     * These take a `DocumentReference` because settlement writes every bid on
+     * an auction in one Firestore batch. `prior` is the document from the SAME
+     * query that produced the ref — every caller has it (`activeBids` and
+     * `losers` are both `{ ref, data }` pairs), so history costs no extra read
+     * even when an auction closes with hundreds of bids (Rule #6).
+     *
+     * Omitting `prior` is legitimate rather than broken: the entry then records
+     * `undefined → "lost"`, which is still true and still stamped with who and
+     * when. It just cannot say what the bid was before.
+     */
+    markWon(batch, ref, ctx, prior) {
+        batch.update(ref, this.withBidHistory(prior, { status: "won", isWinning: true, updatedAt: new Date() }, ctx, "markWon"));
     }
     /**
      * Link a won bid to the order it eventually became.
@@ -130,23 +140,21 @@ export class BidRepository extends BaseRepository {
      * /user/bids could not link anywhere, and nothing could tell a settled win
      * from an unpaid one.
      */
-    async attachOrder(bidId, orderId) {
-        await this.update(bidId, { orderId, updatedAt: new Date() });
+    async attachOrder(bidId, orderId, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.findById(bidId);
+        await this.update(bidId, this.withBidHistory(current, { orderId, updatedAt: new Date() }, ctx, "attachOrder"));
     }
     /**
      * The winner never paid within their checkout window. Distinct from "lost"
      * (outbid) — this bidder won and then defaulted, which a seller may want to
      * act on.
      */
-    async markForfeited(bidId) {
-        await this.update(bidId, { status: "forfeited", isWinning: false, updatedAt: new Date() });
+    async markForfeited(bidId, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.findById(bidId);
+        await this.update(bidId, this.withBidHistory(current, { status: "forfeited", isWinning: false, updatedAt: new Date() }, ctx, "markForfeited"));
     }
-    markLost(batch, ref) {
-        batch.update(ref, {
-            status: "lost",
-            isWinning: false,
-            updatedAt: new Date(),
-        });
+    markLost(batch, ref, ctx, prior) {
+        batch.update(ref, this.withBidHistory(prior, { status: "lost", isWinning: false, updatedAt: new Date() }, ctx, "markLost"));
     }
     /**
      * Batched "everyone else lost", for callers that are not already inside a
@@ -154,12 +162,20 @@ export class BidRepository extends BaseRepository {
      * settlement job, and the losing bids can be any number, so this writes them
      * in Firestore-batch chunks rather than one round-trip per bid.
      */
-    async markManyLost(refs) {
+    async markManyLost(entries, ctx) {
         const CHUNK = 400; // under Firestore's 500-write batch limit, with headroom
-        for (let i = 0; i < refs.length; i += CHUNK) {
+        for (let i = 0; i < entries.length; i += CHUNK) {
             const batch = this.db.batch();
-            for (const ref of refs.slice(i, i + CHUNK))
-                this.markLost(batch, ref);
+            for (const entry of entries.slice(i, i + CHUNK)) {
+                // Accepts a bare ref OR a {ref, data} pair, so the caller that already
+                // holds the documents gets a real before-value on the timeline and the
+                // one that does not still works. Widened rather than made required
+                // because forcing a read per losing bid would put a large auction's
+                // settlement over the Firestore read budget.
+                const isPair = typeof entry === "object" && "ref" in entry;
+                const ref = isPair ? entry.ref : entry;
+                this.markLost(batch, ref, ctx, isPair ? entry.data : undefined);
+            }
             await batch.commit();
         }
     }
@@ -168,21 +184,29 @@ export class BidRepository extends BaseRepository {
      * status means "won, then defaulted", and a lapsed claim never won anything;
      * the auction it was placed against carried on untouched.
      */
-    async markCancelled(bidId) {
-        await this.update(bidId, { status: "cancelled", isWinning: false, updatedAt: new Date() });
+    async markCancelled(bidId, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.findById(bidId);
+        await this.update(bidId, this.withBidHistory(current, { status: "cancelled", isWinning: false, updatedAt: new Date() }, ctx, "markCancelled"));
     }
-    markOutbid(batch, ref) {
-        batch.update(ref, {
-            status: "outbid",
-            isWinning: false,
-            updatedAt: new Date(),
-        });
+    markOutbid(batch, ref, ctx, prior) {
+        batch.update(ref, this.withBidHistory(prior, { status: "outbid", isWinning: false, updatedAt: new Date() }, ctx, "markOutbid"));
     }
-    markWinning(batch, ref) {
-        batch.update(ref, {
-            isWinning: true,
-            updatedAt: new Date(),
+    markWinning(batch, ref, ctx, prior) {
+        batch.update(ref, this.withBidHistory(prior, { isWinning: true, updatedAt: new Date() }, ctx, "markWinning"));
+    }
+    /** Append a timeline entry when the patch touches a tracked field. */
+    withBidHistory(current, patch, ctx, defaultTrigger) {
+        const withEntry = withHistory(current, patch, {
+            tracked: BID_TRACKED_FIELDS,
+            actor: ctx?.actor ?? { role: "system" },
+            trigger: ctx?.trigger ?? defaultTrigger,
+            reason: ctx?.reason,
+            note: ctx?.note,
+            // `userName`/`userEmail` are denormalised onto every bid, and
+            // `encryptPiiFields` never descends into arrays.
+            piiFields: BID_HISTORY_PII_FIELDS,
         });
+        return withEntry ?? patch;
     }
     /**
      * Find current winning bid for a product

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

@@ -2,6 +2,7 @@
  * Bids/Auctions Firestore Document Types & Constants
  */
 import { type GenerateBidIdInput } from "../../../utils/id-generators";
+import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 export type BidStatus = "active" | "outbid" | "won" | "lost" | "cancelled"
 /** Won, then the buyer let the 48h payment window lapse. */
@@ -52,6 +53,16 @@ export interface BidDocument extends BaseDocument {
      *     `claimAuctionForCheckout`, not by blocking the second buyer up front.
      */
     isBuyout?: boolean;
+    /**
+     * Who changed what, when, and why. See § "Status History" in CLAUDE.md.
+     *
+     * A bid moves through more states than any other record a buyer owns —
+     * active → outbid → active → won → forfeited, or cancelled for a lapsed
+     * buyout claim — and every one of those moves happened inside a batch with
+     * nothing recording it. "Why does this say forfeited" was unanswerable.
+     */
+    statusHistory?: StatusChangeEntry[];
+    statusHistoryTruncated?: number;
 }
 export declare const BID_COLLECTION: "bids";
 export declare const BID_INDEXED_FIELDS: readonly ["productId", "userId", "status", "isWinning", "bidDate", "createdAt"];
@@ -71,3 +82,19 @@ export declare const bidQueryHelpers: {
 export declare function createBidId(input: Omit<GenerateBidIdInput, "random"> & {
     random?: string;
 }): string;
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * `bidAmount` is included because a proxy bid raises it in place, so the
+ * timeline is the only record of what the bidder actually committed at each
+ * step. `previousBidAmount` is excluded — it is the same information one
+ * entry earlier.
+ */
+export declare const BID_TRACKED_FIELDS: readonly ["status", "isWinning", "bidAmount", "orderId"];
+/**
+ * PII on this document, for `withHistory`'s scrub. `userName` and `userEmail`
+ * are denormalised onto every bid, so a diff of an unrelated field would drag
+ * them into an array `encryptPiiFields` cannot descend into — the exact leak
+ * the primitive's `piiFields` exists to prevent.
+ */
+export declare const BID_HISTORY_PII_FIELDS: readonly ["userName", "userEmail"];

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

@@ -49,3 +49,24 @@ export const bidQueryHelpers = {
 export function createBidId(input) {
     return generateBidId(input);
 }
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * `bidAmount` is included because a proxy bid raises it in place, so the
+ * timeline is the only record of what the bidder actually committed at each
+ * step. `previousBidAmount` is excluded — it is the same information one
+ * entry earlier.
+ */
+export const BID_TRACKED_FIELDS = [
+    "status",
+    "isWinning",
+    "bidAmount",
+    "orderId",
+];
+/**
+ * PII on this document, for `withHistory`'s scrub. `userName` and `userEmail`
+ * are denormalised onto every bid, so a diff of an unrelated field would drag
+ * them into an array `encryptPiiFields` cannot descend into — the exact leak
+ * the primitive's `piiFields` exists to prevent.
+ */
+export const BID_HISTORY_PII_FIELDS = ["userName", "userEmail"];

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

@@ -65,14 +65,14 @@ export declare const authUserSchema: z.ZodObject<{
     isEmailVerified: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     id: string;
-    role?: "user" | "admin" | "moderator" | "seller" | "employee" | undefined;
+    role?: "user" | "seller" | "admin" | "moderator" | "employee" | undefined;
     email?: string | undefined;
     displayName?: string | undefined;
     photoURL?: string | undefined;
     isEmailVerified?: boolean | undefined;
 }, {
     id: string;
-    role?: "user" | "admin" | "moderator" | "seller" | "employee" | undefined;
+    role?: "user" | "seller" | "admin" | "moderator" | "employee" | undefined;
     email?: string | undefined;
     displayName?: string | undefined;
     photoURL?: string | undefined;

package/dist/features/cart/actions/cart-actions.d.ts

@@ -5,6 +5,22 @@
  * are handled by the calling server action in the consumer.
  */
 import type { AddToCartInput, CartDocument, UpdateCartItemInput } from "../schemas";
+/**
+ * Lane gate. While a higher-obligation lane (a won auction, then an accepted
+ * offer) is outstanding, no NEW shopping may be added — otherwise the buyer can
+ * keep deferring something they already committed to by piling more into the
+ * cart. Enforced on the server, not only in the UI: the UI hint is a courtesy,
+ * this is the rule.
+ *
+ * 🛑 Every add-to-cart entry point must call this. It lived inline inside
+ * `addItemToCart` and therefore covered exactly one of the four ways a line can
+ * be created — `addBundleToCartAction` and `POST /api/cart` both call
+ * `cartRepository.addItem` directly and so bypassed it entirely, letting a buyer
+ * with an unpaid auction win keep shopping.
+ *
+ * Returns the loaded cart so the caller doesn't pay a second read.
+ */
+export declare function assertCanAddNewItems(userId: string): Promise<CartDocument>;
 export declare function addItemToCart(userId: string, input: AddToCartInput): Promise<CartDocument>;
 /** Error code the client maps to a lane-aware message. */
 export declare const CART_LANE_BLOCKED = "CART_LANE_BLOCKED";

package/dist/features/cart/actions/cart-actions.js

@@ -27,6 +27,31 @@ async function resolveStoreName(storeId, candidate) {
     const store = await storeRepository.findById(storeId).catch(() => null);
     return store?.storeName ?? storeId;
 }
+/**
+ * Lane gate. While a higher-obligation lane (a won auction, then an accepted
+ * offer) is outstanding, no NEW shopping may be added — otherwise the buyer can
+ * keep deferring something they already committed to by piling more into the
+ * cart. Enforced on the server, not only in the UI: the UI hint is a courtesy,
+ * this is the rule.
+ *
+ * 🛑 Every add-to-cart entry point must call this. It lived inline inside
+ * `addItemToCart` and therefore covered exactly one of the four ways a line can
+ * be created — `addBundleToCartAction` and `POST /api/cart` both call
+ * `cartRepository.addItem` directly and so bypassed it entirely, letting a buyer
+ * with an unpaid auction win keep shopping.
+ *
+ * Returns the loaded cart so the caller doesn't pay a second read.
+ */
+export async function assertCanAddNewItems(userId) {
+    const cart = await cartRepository.getOrCreate(userId);
+    if (!canAddNewItems(cart.items ?? [])) {
+        const blocking = activeLane(cart.items ?? []);
+        throw new ValidationError(blocking === CART_LANE.AUCTION
+            ? "Settle your won auction first — you can add other items once it's paid for."
+            : "Complete your accepted offer first — you can add other items once it's paid for.", { code: CART_LANE_BLOCKED });
+    }
+    return cart;
+}
 export async function addItemToCart(userId, input) {
     serverLogger.debug("addItemToCart", { userId, productId: input.productId });
     // SB-UNI-F 2026-05-13 — capability gate. Classified + live listings reject
@@ -36,18 +61,7 @@ export async function addItemToCart(userId, input) {
     if (!canAddToCart(input.listingType)) {
         throw new ValidationError(`Listings of type "${input.listingType}" cannot be added to the cart.`);
     }
-    // Lane gate. While a higher-obligation lane (a won auction, then an accepted
-    // offer) is outstanding, no NEW shopping may be added — otherwise the buyer
-    // can keep deferring something they already committed to by piling more into
-    // the cart. Enforced here, on the server, not only in the UI: the UI hint is
-    // a courtesy, this is the rule.
-    const cart = await cartRepository.getOrCreate(userId);
-    if (!canAddNewItems(cart.items ?? [])) {
-        const blocking = activeLane(cart.items ?? []);
-        throw new ValidationError(blocking === CART_LANE.AUCTION
-            ? "Settle your won auction first — you can add other items once it's paid for."
-            : "Complete your accepted offer first — you can add other items once it's paid for.", { code: CART_LANE_BLOCKED });
-    }
+    await assertCanAddNewItems(userId);
     const storeName = await resolveStoreName(input.storeId, input.storeName);
     return cartRepository.addItem(userId, { ...input, storeName });
 }

package/dist/features/cart/components/CartDrawer.js

@@ -2,6 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { Aside, Button, Div, Heading, Row, Span, Stack, Text, TextLink } from "../../../ui";
 import { MediaImage } from "../../media/MediaImage";
+import { QuantityStepper } from "../../../ui/components/QuantityStepper";
 import { formatCurrency } from "../../../utils/number.formatter";
 import { ACTIONS } from "../../../_internal/shared/actions/action-registry";
 import { useHandMode } from "../../../_internal/client/hand-mode";
@@ -18,7 +19,7 @@ export function CartItemRow({ item, onQtyChange, onRemove, href, isOutOfStock =
     return (_jsxs(Div, { layout: "flex", gap: isRow ? "3" : "4", surface: isRow ? "none" : "card", padding: isRow ? "none" : "sm", className: `min-w-0 transition-opacity ${isOutOfStock ? "opacity-60" : ""}`, children: [_jsx(Div, { surface: "muted", className: `relative ${isRow ? "h-16 w-16" : "h-20 w-20"} flex-shrink-0 ${__O.hidden}`, rounded: "lg", children: item.meta.image && (_jsx(MediaImage, { src: item.meta.image, alt: item.meta.title, size: "thumbnail" })) }), _jsxs(Stack, { justify: "between", className: "flex-1 min-w-0", children: [_jsxs(Row, { gap: "xs", className: "min-w-0", align: "start", children: [href ? (_jsx(TextLink, { href: href, target: "_blank", rel: "noopener noreferrer", weight: "medium", className: "text-[var(--appkit-color-text)] hover:underline underline-offset-2 line-clamp-2", children: item.meta.title })) : (_jsx(Text, { truncate: 2, weight: "medium", color: "primary", children: item.meta.title })), isOutOfStock && (_jsx(Span, { padding: "pill-2xs", color: "error", surface: "danger-surface", weight: "semibold", className: "flex-shrink-0 text-[10px] tracking-wide", rounded: "default", transform: "uppercase", children: "Out of Stock" }))] }), item.meta.attributes &&
                         Object.keys(item.meta.attributes).length > 0 && (_jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "xs", truncate: 1, children: Object.entries(item.meta.attributes)
                             .map(([k, v]) => `${k}: ${v}`)
-                            .join(", ") })), _jsxs(Row, { justify: "between", className: "min-w-0", gap: "sm", children: [_jsx(Text, { className: "text-[var(--appkit-color-text)]", weight: "semibold", children: formatCurrency(item.meta.price * item.quantity, item.meta.currency) }), onQtyChange && !isOutOfStock && (_jsxs(Row, { gap: "sm", children: [_jsx(Button, { rounded: "full", onClick: () => onQtyChange(item.id, item.quantity - 1), disabled: item.quantity <= 1, variant: "outline", size: "sm", className: "h-7 w-7 justify-center border border-neutral-200 border-[var(--appkit-color-border)] text-[length:var(--appkit-text-sm)] disabled:opacity-40", children: "\u2212" }), _jsx(Span, { size: "sm", className: "min-w-[1.5rem]", align: "center", children: item.quantity }), _jsx(Button, { rounded: "full", onClick: () => onQtyChange(item.id, item.quantity + 1), variant: "outline", size: "sm", className: "h-7 w-7 justify-center border border-neutral-200 border-[var(--appkit-color-border)] text-[length:var(--appkit-text-sm)]", children: "+" })] })), isOutOfStock && (_jsxs(Span, { size: "xs", color: "muted", children: ["Qty: ", item.quantity] }))] })] }), onRemove && (_jsx(Button, { onClick: () => onRemove(item.id), variant: "ghost", size: "sm", "aria-label": ACTIONS.CART["remove-item"].ariaLabel, className: CLS_REMOVE_BTN, children: "\u2715" }))] }));
+                            .join(", ") })), _jsxs(Row, { justify: "between", className: "min-w-0", gap: "sm", children: [_jsx(Text, { className: "text-[var(--appkit-color-text)]", weight: "semibold", children: formatCurrency(item.meta.price * item.quantity, item.meta.currency) }), onQtyChange && !isOutOfStock && (_jsx(QuantityStepper, { value: item.quantity, onChange: (next) => onQtyChange(item.id, next), min: 1, ariaLabel: `Quantity for ${item.meta.title}`, decrementLabel: ACTIONS.CART["decrease-quantity"].ariaLabel, incrementLabel: ACTIONS.CART["increase-quantity"].ariaLabel })), isOutOfStock && (_jsxs(Span, { size: "xs", color: "muted", children: ["Qty: ", item.quantity] }))] })] }), onRemove && (_jsx(Button, { onClick: () => onRemove(item.id), variant: "ghost", size: "sm", "aria-label": ACTIONS.CART["remove-item"].ariaLabel, className: CLS_REMOVE_BTN, children: "\u2715" }))] }));
 }
 export function CartDrawer({ isOpen, onClose, items, subtotal = 0, currency, isLoading, onQtyChange, onRemove, onCheckout, labels = {}, }) {
     const { hand } = useHandMode();

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

@@ -6,6 +6,53 @@
  */
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 import type { ListingType } from "../../products/types/index";
+/**
+ * What KIND of thing one cart line represents.
+ *
+ *  - absent      — an ordinary single-product line.
+ *  - `"bundle"`  — a fixed, all-or-nothing set priced as a whole
+ *                  (`categoryType:"bundle"` row on `categories`). Members are
+ *                  not pickable; the only stepper is the line-level one and it
+ *                  means COPIES OF THE BUNDLE.
+ *  - `"group"`   — a buyer-assembled selection out of a product group
+ *                  (`product.groupId`) or a `groupedListings` doc. Members ARE
+ *                  pickable; there is no line-level stepper.
+ */
+export type CartLineKind = "bundle" | "group";
+/** Which collection a `"group"` line's members were picked from. */
+export type CartGroupSource = "product-group" | "grouped-listing";
+/**
+ * One member product inside a multi-member cart line.
+ *
+ * 🛑 THE QUANTITY INVARIANT — every reader and writer depends on it:
+ *
+ *   `CartItemDocument.quantity` = copies of the whole selection
+ *   `CartLineMember.quantity`   = units of THIS member per copy
+ *   demand for a product        = item.quantity × member.quantity
+ *
+ * A `"group"` line pins `item.quantity` to 1, which is what lets `unitPriceFor`
+ * keep returning a UNIT price that every existing call site multiplies by
+ * `item.quantity` without double-counting. A `"bundle"` line is the mirror
+ * image: `item.quantity` is the editable one and member quantities are frozen
+ * at add time.
+ *
+ * Prices/titles/images are SNAPSHOTS taken server-side at add time. They are
+ * never accepted from the client — see `POST /api/cart/group`, which takes ids
+ * and quantities only.
+ */
+export interface CartLineMember {
+    productId: string;
+    /** Units of this member per copy of the line. See the invariant above. */
+    quantity: number;
+    /** Snapshot of the member's own price at add time, in decimal rupees. */
+    unitPrice: number;
+    title: string;
+    image?: string;
+    /** Snapshot for per-member GST proration at checkout (`lineTaxComponentsFor`). */
+    gstRate?: number;
+    hsnCode?: string;
+    listingType?: ListingType;
+}
 export interface CartItemDocument {
     itemId: string;
     productId: string;
@@ -64,16 +111,47 @@ export interface CartItemDocument {
     /**
      * SB-UNI-4 2026-05-13 — bundle identifier when this cart line represents a
      * bundle (categoryType:"bundle" row on the categories collection). When set,
-     * `productId` points at the bundle category's id, `price` is the locked
-     * bundlePrice, and `bundleProductIds` snapshots the member product
-     * ids at add-to-cart time. Order-side fan-out into per-product OrderItem
-     * entries lands in S-SBUNI-5 (checkout-side stock decrement + per-store
-     * grouping); until then the foundation is here but BundleDetailView keeps
-     * the "Add to cart coming soon" notice up.
+     * `productId` points at the bundle category's id and `price` is the locked
+     * bundlePrice.
+     *
+     * This is an IDENTITY, not a mirror — it is what the order-side collapse key
+     * (`groupOrderItemsByLine`) groups on, and it keeps being written.
      */
     bundleCategorySlug?: string;
-    /** Snapshot of `bundle.bundleProductIds` at add-to-cart time. */
+    /**
+     * @deprecated Legacy carts only. Superseded by `groupMembers`, which can
+     * express per-member quantities where a bare id array cannot.
+     *
+     * Do NOT write this from new code and do NOT read it directly — a
+     * hand-maintained mirror alongside `groupMembers` is exactly the drift
+     * Recurrent Root Cause #42 describes. Read through `getCartLineMembers()`
+     * (`_internal/server/features/checkout/bundle-expansion.ts`), which falls
+     * back to these ids at quantity 1 so lines written before `groupMembers`
+     * existed keep behaving byte-identically.
+     */
     bundleProductIds?: string[];
+    /**
+     * Discriminator for a multi-member line. Absent on an ordinary
+     * single-product line. See `CartLineKind` for the two behaviours.
+     */
+    lineKind?: CartLineKind;
+    /** Which collection the members came from. `"group"` lines only. */
+    groupSource?: CartGroupSource;
+    /** `product.groupId` | `groupedListing.id` | the bundle category's id. */
+    groupId?: string;
+    /** Slug for the line's detail href. Bundles use `bundleCategorySlug` instead. */
+    groupSlug?: string;
+    /** Display snapshot of the group/bundle name. */
+    groupTitle?: string;
+    /**
+     * The members of a multi-member line, AUTHORITATIVE over `bundleProductIds`.
+     * See `CartLineMember` for the quantity invariant.
+     *
+     * `price` on this document is derived from this array by the repository
+     * (`deriveLinePrice`) at every write, never set by a caller — so no caller
+     * can forget to keep the two in step.
+     */
+    groupMembers?: CartLineMember[];
     /**
      * S-SBUNI-RULES 2026-05-13 — buyer's chosen shipping provider for this
      * item, snapshotted at cart time. Locked at checkout; the per-tab
@@ -149,10 +227,32 @@ export declare const CART_FIELDS: {
         readonly STORE_ID: "storeId";
         readonly STORE_NAME: "storeName";
         readonly LISTING_TYPE: "listingType";
+        readonly IS_OFFER: "isOffer";
+        readonly OFFER_ID: "offerId";
+        readonly IS_AUCTION_WIN: "isAuctionWin";
+        readonly AUCTION_ID: "auctionId";
+        readonly BID_ID: "bidId";
+        readonly IS_BUYOUT: "isBuyout";
+        readonly LOCKED_PRICE: "lockedPrice";
+        readonly CHECKOUT_DEADLINE: "checkoutDeadline";
+        readonly LOCKED: "locked";
+        readonly BUNDLE_CATEGORY_SLUG: "bundleCategorySlug";
+        /** @deprecated legacy read path — see CartItemDocument.bundleProductIds */
+        readonly BUNDLE_PRODUCT_IDS: "bundleProductIds";
+        readonly LINE_KIND: "lineKind";
+        readonly GROUP_SOURCE: "groupSource";
+        readonly GROUP_ID: "groupId";
+        readonly GROUP_SLUG: "groupSlug";
+        readonly GROUP_TITLE: "groupTitle";
+        readonly GROUP_MEMBERS: "groupMembers";
+        readonly CHOSEN_SHIPPING_PROVIDER_ID: "chosenShippingProviderId";
+        readonly CHOSEN_SHIPPING_FEE: "chosenShippingFee";
         readonly ADDED_AT: "addedAt";
         readonly UPDATED_AT: "updatedAt";
     };
 };
+export declare const CART_LINE_KIND_VALUES: readonly ["bundle", "group"];
+export declare const CART_GROUP_SOURCE_VALUES: readonly ["product-group", "grouped-listing"];
 export declare const DEFAULT_CART_DATA: Partial<CartDocument>;
 export type CartCreateInput = Omit<CartDocument, "id" | "createdAt" | "updatedAt">;
 export type AddToCartInput = {
@@ -178,12 +278,36 @@ export type AddToCartInput = {
     locked?: boolean;
     /** SB-UNI-4 2026-05-13 — bundle identifier when the line is a bundle. */
     bundleCategorySlug?: string;
-    /** Snapshot of bundle members at add-to-cart time. */
+    /** @deprecated Legacy only — write `groupMembers` instead. */
     bundleProductIds?: string[];
+    lineKind?: CartLineKind;
+    groupSource?: CartGroupSource;
+    groupId?: string;
+    groupSlug?: string;
+    groupTitle?: string;
+    groupMembers?: CartLineMember[];
+};
+/**
+ * Input for creating a multi-member line. `price` is deliberately absent — the
+ * repository derives it from `groupMembers` so the two can never disagree.
+ */
+export type AddGroupLineInput = Omit<AddToCartInput, "price" | "groupMembers"> & {
+    groupMembers: CartLineMember[];
 };
 export type UpdateCartItemInput = {
     quantity: number;
 };
+/**
+ * Body of a per-member edit. The WHOLE array is sent, not a delta: the cart is
+ * a single Firestore document written with `set()`, so N per-member writes
+ * would be both a Rule #6 cost and a real lost-update race on a double-click.
+ */
+export type UpdateCartGroupMembersInput = {
+    groupMembers: Array<{
+        productId: string;
+        quantity: number;
+    }>;
+};
 export declare const cartQueryHelpers: {
     readonly byUserId: (userId: string) => {
         field: "userId";

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

@@ -23,10 +23,32 @@ export const CART_FIELDS = {
         STORE_ID: "storeId",
         STORE_NAME: "storeName",
         LISTING_TYPE: "listingType",
+        IS_OFFER: "isOffer",
+        OFFER_ID: "offerId",
+        IS_AUCTION_WIN: "isAuctionWin",
+        AUCTION_ID: "auctionId",
+        BID_ID: "bidId",
+        IS_BUYOUT: "isBuyout",
+        LOCKED_PRICE: "lockedPrice",
+        CHECKOUT_DEADLINE: "checkoutDeadline",
+        LOCKED: "locked",
+        BUNDLE_CATEGORY_SLUG: "bundleCategorySlug",
+        /** @deprecated legacy read path — see CartItemDocument.bundleProductIds */
+        BUNDLE_PRODUCT_IDS: "bundleProductIds",
+        LINE_KIND: "lineKind",
+        GROUP_SOURCE: "groupSource",
+        GROUP_ID: "groupId",
+        GROUP_SLUG: "groupSlug",
+        GROUP_TITLE: "groupTitle",
+        GROUP_MEMBERS: "groupMembers",
+        CHOSEN_SHIPPING_PROVIDER_ID: "chosenShippingProviderId",
+        CHOSEN_SHIPPING_FEE: "chosenShippingFee",
         ADDED_AT: "addedAt",
         UPDATED_AT: "updatedAt",
     },
 };
+export const CART_LINE_KIND_VALUES = ["bundle", "group"];
+export const CART_GROUP_SOURCE_VALUES = ["product-group", "grouped-listing"];
 export const DEFAULT_CART_DATA = {
     items: [],
 };

package/dist/features/catalogue/actions/approve-catalogue-listing.js

@@ -23,11 +23,12 @@ export async function approveCatalogueListingAction(itemId) {
             throw new ValidationError("Only items pending approval can be approved");
         }
         const product = await createProductFromCatalogueItem(item, CONSIGNMENT_STORE_ID);
-        await catalogueRepository.update(itemId, {
+        // `item` came from the findById above, so the timeline entry is free.
+        await catalogueRepository.setListingStatus(itemId, {
             listingStatus: "listed",
             linkedProductId: product.id,
             linkedProductSlug: product.slug ?? product.id,
-        });
+        }, { actor: { role: "admin", uid: user.uid }, trigger: "approveCatalogueListing" }, item);
         return { productId: product.id, productSlug: product.slug ?? product.id };
     });
 }
@@ -42,9 +43,9 @@ export async function rejectCatalogueListingAction(itemId, reason) {
         if (item.listingStatus !== "pending_admin_approval") {
             throw new ValidationError("Only items pending approval can be rejected");
         }
-        await catalogueRepository.update(itemId, {
-            listingStatus: "rejected",
-            rejectionReason: reason,
-        });
+        await catalogueRepository.setListingStatus(itemId, { listingStatus: "rejected", rejectionReason: reason }, 
+        // The reason is the point of the entry — `rejectionReason` on the
+        // document is overwritten by the next decision.
+        { actor: { role: "admin", uid: user.uid }, trigger: "rejectCatalogueListing", reason }, item);
     });
 }

package/dist/features/catalogue/actions/list-from-catalogue.js

@@ -40,11 +40,11 @@ export async function listFromCatalogueAction(itemId) {
             storeId = store.id;
         }
         const product = await createProductFromCatalogueItem(item, storeId);
-        await catalogueRepository.update(itemId, {
+        await catalogueRepository.setListingStatus(itemId, {
             listingStatus: "listed",
             linkedProductId: product.id,
             linkedProductSlug: product.slug ?? product.id,
-        });
+        }, { actor: { role: "seller", uid: user.uid }, trigger: "listFromCatalogue" }, item);
         return { productId: product.id, productSlug: product.slug ?? product.id };
     });
 }

package/dist/features/catalogue/actions/submit-for-approval.js

@@ -22,9 +22,6 @@ export async function submitCatalogueItemForApprovalAction(itemId) {
             throw new ValidationError("Only items not yet submitted can be requested for listing");
         }
         assertCatalogueImagesFresh(item);
-        await catalogueRepository.update(itemId, {
-            listingStatus: "pending_admin_approval",
-            submittedForApprovalAt: new Date(),
-        });
+        await catalogueRepository.setListingStatus(itemId, { listingStatus: "pending_admin_approval", submittedForApprovalAt: new Date() }, { actor: { role: "buyer", uid: user.uid }, trigger: "submitCatalogueForApproval" }, item);
     });
 }

package/dist/features/catalogue/components/AdminCatalogueApprovalsView.js

@@ -10,6 +10,7 @@ import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
 import { apiClient } from "../../../http";
 import { toRecordArray, toRelativeDate, toStringValue, } from "../../admin/hooks/useAdminListingData";
 import { DataListingView } from "../../admin/components/DataListingView";
+import { RecordStatusTimeline } from "../../status-history/components/RecordStatusTimeline";
 /** The submitted item's photos — the whole point of a visual approval. */
 function toPhotoEntries(raw) {
     const images = Array.isArray(raw.images) ? raw.images : [];
@@ -71,7 +72,10 @@ export function AdminCatalogueApprovalsView() {
                     { label: "Quantity", value: String(raw.quantity ?? 1) },
                     { label: "Condition", value: toStringValue(raw.condition, "—") },
                     { label: "Submitted", value: selected?.updatedAt ?? "—" },
-                ], items: { heading: "Photos", entries: toPhotoEntries(raw) }, footer: selected ? (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "danger", onClick: () => {
+                ], items: { heading: "Photos", entries: toPhotoEntries(raw) }, extra: 
+                // "Why was mine rejected and by whom" — `rejectionReason` alone is
+                // overwritten by the next decision.
+                _jsx(RecordStatusTimeline, { entries: raw.statusHistory, truncatedCount: raw.statusHistoryTruncated }), footer: selected ? (_jsxs(_Fragment, { children: [_jsx(Button, { variant: "danger", onClick: () => {
                                 setRejectTarget(selected.id);
                                 setSelected(null);
                             }, children: "Reject" }), _jsx(Button, { isLoading: approveMutation.isPending, onClick: () => {