@mohasinac/appkit 4.23.0 → 4.25.0

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

@@ -12,6 +12,8 @@ import { storeRepository } from "../../stores/repository/store.repository";
 import { normalizeListingType } from "../../products/utils/listing-type";
 import { getDefaultCurrency } from "../../../core/baseline-resolver";
 import { CART_LANE, activeLane, canAddNewItems, } from "../../../_internal/shared/checkout/lanes";
+import { CART_MAX_ITEMS } from "../../../constants/limits";
+import { getExpandedDecrements, validateCartItemStock, } from "../../../_internal/server/features/checkout/bundle-expansion";
 /**
  * Product documents don't always carry a denormalized `storeName` — the
  * create routes only set it when the caller explicitly passes one, so
@@ -27,6 +29,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,23 +63,165 @@ 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 });
 }
 /** Error code the client maps to a lane-aware message. */
 export const CART_LANE_BLOCKED = "CART_LANE_BLOCKED";
+/** Max members one grouped line may hold. Keeps the batch read bounded (Rule #6). */
+export const GROUP_LINE_MAX_MEMBERS = 20;
+/**
+ * Add a buyer-assembled selection of group members as ONE cart line.
+ *
+ * The client sends ids and quantities and nothing else. Accepting a price, a
+ * title or an image from the browser would be a ₹1-group exploit; every
+ * snapshot below is read from Firestore here.
+ *
+ * A rejected member fails the WHOLE request, naming the offender. Silently
+ * dropping it would hand the buyer a line that quietly isn't what they picked —
+ * the "wrong data, no error" failure nobody can report.
+ */
+export async function addGroupLineToCart(userId, input) {
+    const { groupId, groupSource, members } = input;
+    if (!groupId)
+        throw new ValidationError("A group id is required.");
+    if (!members.length)
+        throw new ValidationError("Select at least one item to add.");
+    if (members.length > GROUP_LINE_MAX_MEMBERS) {
+        throw new ValidationError(`A single group line can hold at most ${GROUP_LINE_MAX_MEMBERS} different items.`);
+    }
+    for (const m of members) {
+        if (!Number.isInteger(m.quantity) || m.quantity < 1) {
+            throw new ValidationError("Every selected item needs a whole quantity of at least 1.");
+        }
+    }
+    if (new Set(members.map((m) => m.productId)).size !== members.length) {
+        throw new ValidationError("The same item was selected twice.");
+    }
+    const cart = await assertCanAddNewItems(userId);
+    // One batched read for the whole selection — capped at 20 above, so well
+    // inside the per-request Firestore budget.
+    const docs = await Promise.all(members.map((m) => productRepository.findById(m.productId).catch(() => null)));
+    const productById = new Map(members.map((m, i) => [m.productId, docs[i]]));
+    const { getListingRule } = await import("../../../_internal/shared/checkout/rules");
+    const { ProductStatusValues } = await import("../../products/schemas/firestore");
+    const resolved = [];
+    for (const m of members) {
+        const product = productById.get(m.productId);
+        if (!product) {
+            throw new ValidationError(`One of the selected items no longer exists.`);
+        }
+        if (product.status !== ProductStatusValues.PUBLISHED || product.isSold) {
+            throw new ValidationError(`"${product.title}" is no longer available.`);
+        }
+        // Membership. Without this a caller could staple arbitrary products into
+        // one line and buy them under a group's identity.
+        const belongs = groupSource === "product-group"
+            ? product.groupId === groupId
+            : await isGroupedListingMember(groupId, product.id);
+        if (!belongs) {
+            throw new ValidationError(`"${product.title}" is not part of this group.`);
+        }
+        const listingType = normalizeListingType(product);
+        const rule = getListingRule(listingType);
+        if (!rule.cartEligible) {
+            throw new ValidationError(`"${product.title}" can't be added to the cart. ${rule.cartIneligibleHint ?? ""}`.trim());
+        }
+        if ((product.availableQuantity ?? 0) < m.quantity) {
+            throw new ValidationError(`Only ${product.availableQuantity ?? 0} left of "${product.title}".`);
+        }
+        resolved.push({
+            productId: product.id,
+            quantity: m.quantity,
+            unitPrice: product.price,
+            title: product.title,
+            image: product.images?.[0] ?? product.mainImage,
+            gstRate: product.gstRate,
+            hsnCode: product.hsnCode,
+            listingType,
+        });
+    }
+    // Single-store rule. `storeId` is the order-splitting key AND the key the
+    // per-store add-ons, coupons, shipping and payout all hang off, so a line
+    // spanning two stores would break five things at once. The picker hides
+    // itself for a cross-store group; this is the server-side half of that.
+    const storeIds = new Set(resolved.map((r) => productById.get(r.productId)?.storeId ?? ""));
+    if (storeIds.size > 1) {
+        throw new ValidationError("These items are sold by different sellers, so they can't be combined into one cart line.");
+    }
+    const storeId = [...storeIds][0] ?? "";
+    const first = productById.get(resolved[0].productId);
+    // A one-member selection is just an ordinary line: 1 item × qty N is exactly
+    // what a normal cart line already means, and routing it through the group
+    // path would create a second representation of the same thing.
+    if (resolved.length === 1) {
+        return addItemToCart(userId, {
+            productId: first.id,
+            productTitle: first.title,
+            productImage: first.images?.[0] ?? first.mainImage,
+            price: first.price,
+            currency: first.currency,
+            quantity: resolved[0].quantity,
+            storeId,
+            storeName: first.storeName ?? "",
+            listingType: resolved[0].listingType ?? "standard",
+        });
+    }
+    // A grouped line counts as ONE item against the distinct-items cap.
+    if (cart.items.length >= CART_MAX_ITEMS) {
+        throw new ValidationError(`Cart full (${cart.items.length}/${CART_MAX_ITEMS}). Remove items to add new ones.`);
+    }
+    // Same stock check checkout will run, so add-time and checkout-time agree by
+    // construction rather than by two similar-looking implementations.
+    const candidate = {
+        itemId: "candidate",
+        productId: groupId,
+        quantity: 1,
+        groupMembers: resolved,
+    };
+    const expansion = getExpandedDecrements([...cart.items, candidate]);
+    const shortfall = validateCartItemStock(candidate, new Map([...productById.entries()].filter(([, p]) => p !== null)), expansion.decrements);
+    if (shortfall) {
+        const short = productById.get(shortfall.productId);
+        throw new ValidationError(`Only ${shortfall.availableQty} left of "${short?.title ?? shortfall.productId}" once your cart is counted.`);
+    }
+    const groupTitle = await resolveGroupTitle(groupId, groupSource, first ?? null);
+    return cartRepository.addGroupLine(userId, {
+        productId: groupId,
+        productTitle: groupTitle,
+        productImage: resolved[0].image ?? "",
+        currency: first?.currency ?? getDefaultCurrency(),
+        // Pinned to 1: member quantities carry the whole selection, and a copies
+        // multiplier on top would double-count. See the invariant on CartLineMember.
+        quantity: 1,
+        storeId,
+        storeName: await resolveStoreName(storeId, first?.storeName),
+        listingType: "standard",
+        lineKind: "group",
+        groupSource,
+        groupId,
+        groupSlug: groupSource === "product-group" ? groupId : undefined,
+        groupTitle,
+        groupMembers: resolved,
+    });
+}
+/** Is this product listed on that `groupedListings` document? */
+async function isGroupedListingMember(groupId, productId) {
+    const { groupedListingsRepository } = await import("../../grouped/repository/grouped-listings.repository");
+    const group = await groupedListingsRepository.findById(groupId).catch(() => null);
+    return Boolean(group?.productIds?.includes(productId));
+}
+/** Display name for the line. Falls back to the parent product's group title. */
+async function resolveGroupTitle(groupId, groupSource, sample) {
+    if (groupSource === "grouped-listing") {
+        const { groupedListingsRepository } = await import("../../grouped/repository/grouped-listings.repository");
+        const group = await groupedListingsRepository.findById(groupId).catch(() => null);
+        if (group?.title)
+            return group.title;
+    }
+    return sample?.groupTitle ?? "Selected items";
+}
 /**
  * Won-auction lines are non-removable and fixed-quantity — the buyer committed
  * to the purchase by bidding, and letting them delete it would turn every
@@ -65,6 +234,14 @@ export const CART_LANE_BLOCKED = "CART_LANE_BLOCKED";
 export async function updateCartItem(userId, itemId, input) {
     return cartRepository.updateItem(userId, itemId, input);
 }
+/**
+ * Replace a grouped line's member quantities. A member set to 0 is dropped;
+ * dropping the last one removes the line (enforced in the repository so a
+ * forgetful caller can't leave an empty ghost line behind).
+ */
+export async function updateCartGroupMembers(userId, itemId, input) {
+    return cartRepository.updateGroupMembers(userId, itemId, input);
+}
 export async function removeCartItem(userId, itemId) {
     return cartRepository.removeItem(userId, itemId);
 }

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/repository/cart.repository.d.ts

@@ -1,7 +1,7 @@
 import { type DocumentReference } from "firebase-admin/firestore";
 import type { DocumentSnapshot } from "../../../providers/db-firebase";
 import { BaseRepository, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
-import { type AddToCartInput, type CartAppliedCoupon, type CartDocument, type CartStoreAddons, type CartItemDocument, type UpdateCartItemInput } from "../schemas";
+import { type AddToCartInput, type CartAppliedCoupon, type CartDocument, type CartStoreAddons, type CartItemDocument, type AddGroupLineInput, type UpdateCartItemInput, type UpdateCartGroupMembersInput } from "../schemas";
 export declare class CartRepository extends BaseRepository<CartDocument> {
     private static readonly SIEVE_FIELDS;
     constructor();
@@ -12,6 +12,38 @@ export declare class CartRepository extends BaseRepository<CartDocument> {
     getOrCreate(userId: string): Promise<CartDocument>;
     createEmpty(userId: string): Promise<CartDocument>;
     addItem(userId: string, input: AddToCartInput): Promise<CartDocument>;
+    /**
+     * Price of ONE COPY of a multi-member line.
+     *
+     * Private and called at every write of `groupMembers`, so `item.price` cannot
+     * drift from the members it is supposed to summarise — no caller sets it, so
+     * no caller can forget it. That property is load-bearing well beyond this
+     * file: `getSubtotal`, the cart page's per-seller subtotal, and both lane
+     * subtotals all compute `price × quantity`, and a grouped line pins
+     * `quantity` to 1, so all four stay correct with no changes of their own.
+     */
+    private deriveLinePrice;
+    /**
+     * Create a multi-member line. Deliberately never merges into an existing
+     * line — see the note in `addItem`.
+     */
+    addGroupLine(userId: string, input: AddGroupLineInput): Promise<CartDocument>;
+    /**
+     * Replace a grouped line's member quantities.
+     *
+     * Takes the WHOLE array rather than a per-member delta: the cart is one
+     * Firestore document written with `set()`, so N per-member writes would be
+     * both a Rule #6 cost and a genuine lost-update race on a fast double-click.
+     *
+     * A member dropped to 0 is removed, and **a line left with no members is
+     * removed entirely** — enforced here rather than in the client, so a caller
+     * that forgets cannot leave an empty ghost line in the document.
+     *
+     * Only quantities move. Prices, titles and images are the snapshots taken
+     * server-side at add time and are never re-accepted from a caller; adding a
+     * NEW member is an add-to-cart, which has its own eligibility checks.
+     */
+    updateGroupMembers(userId: string, itemId: string, input: UpdateCartGroupMembersInput): Promise<CartDocument>;
     updateItem(userId: string, itemId: string, input: UpdateCartItemInput): Promise<CartDocument>;
     removeItem(userId: string, itemId: string): Promise<CartDocument>;
     clearCart(userId: string): Promise<CartDocument>;

package/dist/features/cart/repository/cart.repository.js

@@ -72,10 +72,17 @@ export class CartRepository extends BaseRepository {
             if (input.bidId && items.some((item) => item.bidId === input.bidId)) {
                 return cart;
             }
+            // A grouped line is never merged by productId. Two "Add selected"
+            // presses are two different selections, and merging them would silently
+            // rewrite the buyer's per-member quantities into a copy count. Bundles
+            // DO still merge — the same bundle twice genuinely means two copies.
             const isLockedLine = Boolean(input.offerId || input.bidId);
-            const existingIndex = isLockedLine
+            const existingIndex = isLockedLine || input.lineKind === "group"
                 ? -1
-                : items.findIndex((item) => item.productId === input.productId && !item.offerId && !item.bidId);
+                : items.findIndex((item) => item.productId === input.productId &&
+                    !item.offerId &&
+                    !item.bidId &&
+                    item.lineKind !== "group");
             if (existingIndex >= 0) {
                 items[existingIndex] = {
                     ...items[existingIndex],
@@ -115,6 +122,12 @@ export class CartRepository extends BaseRepository {
                     ...(input.bundleProductIds !== undefined && {
                         bundleProductIds: input.bundleProductIds,
                     }),
+                    ...(input.lineKind !== undefined && { lineKind: input.lineKind }),
+                    ...(input.groupSource !== undefined && { groupSource: input.groupSource }),
+                    ...(input.groupId !== undefined && { groupId: input.groupId }),
+                    ...(input.groupSlug !== undefined && { groupSlug: input.groupSlug }),
+                    ...(input.groupTitle !== undefined && { groupTitle: input.groupTitle }),
+                    ...(input.groupMembers !== undefined && { groupMembers: input.groupMembers }),
                     addedAt: new Date(),
                     updatedAt: new Date(),
                 };
@@ -137,6 +150,137 @@ export class CartRepository extends BaseRepository {
             throw new DatabaseError("Failed to add item to cart", error);
         }
     }
+    /**
+     * Price of ONE COPY of a multi-member line.
+     *
+     * Private and called at every write of `groupMembers`, so `item.price` cannot
+     * drift from the members it is supposed to summarise — no caller sets it, so
+     * no caller can forget it. That property is load-bearing well beyond this
+     * file: `getSubtotal`, the cart page's per-seller subtotal, and both lane
+     * subtotals all compute `price × quantity`, and a grouped line pins
+     * `quantity` to 1, so all four stay correct with no changes of their own.
+     */
+    deriveLinePrice(members) {
+        const raw = members.reduce((sum, m) => sum + m.unitPrice * m.quantity, 0);
+        // audit-money-units-ok: decimal rupees throughout; rounding to 2dp, not paise conversion.
+        return Math.round(raw * 100) / 100;
+    }
+    /**
+     * Create a multi-member line. Deliberately never merges into an existing
+     * line — see the note in `addItem`.
+     */
+    async addGroupLine(userId, input) {
+        try {
+            if (!input.groupMembers.length) {
+                throw new ValidationError("A grouped cart line needs at least one member.");
+            }
+            const cart = await this.getOrCreate(userId);
+            const newItem = {
+                itemId: randomUUID(),
+                productId: input.productId,
+                productTitle: input.productTitle,
+                productImage: input.productImage,
+                price: this.deriveLinePrice(input.groupMembers),
+                currency: input.currency,
+                quantity: input.quantity,
+                storeId: input.storeId,
+                storeName: input.storeName,
+                listingType: input.listingType,
+                groupMembers: input.groupMembers,
+                ...(input.lineKind !== undefined && { lineKind: input.lineKind }),
+                ...(input.groupSource !== undefined && { groupSource: input.groupSource }),
+                ...(input.groupId !== undefined && { groupId: input.groupId }),
+                ...(input.groupSlug !== undefined && { groupSlug: input.groupSlug }),
+                ...(input.groupTitle !== undefined && { groupTitle: input.groupTitle }),
+                ...(input.bundleCategorySlug !== undefined && {
+                    bundleCategorySlug: input.bundleCategorySlug,
+                }),
+                addedAt: new Date(),
+                updatedAt: new Date(),
+            };
+            const updatedCart = {
+                ...cart,
+                items: [...cart.items, newItem],
+                updatedAt: new Date(),
+            };
+            await this.db
+                .collection(this.collection)
+                .doc(userId)
+                .set(prepareForFirestore(updatedCart));
+            return updatedCart;
+        }
+        catch (error) {
+            if (error instanceof DatabaseError || error instanceof ValidationError)
+                throw error;
+            throw new DatabaseError("Failed to add grouped line to cart", error);
+        }
+    }
+    /**
+     * Replace a grouped line's member quantities.
+     *
+     * Takes the WHOLE array rather than a per-member delta: the cart is one
+     * Firestore document written with `set()`, so N per-member writes would be
+     * both a Rule #6 cost and a genuine lost-update race on a fast double-click.
+     *
+     * A member dropped to 0 is removed, and **a line left with no members is
+     * removed entirely** — enforced here rather than in the client, so a caller
+     * that forgets cannot leave an empty ghost line in the document.
+     *
+     * Only quantities move. Prices, titles and images are the snapshots taken
+     * server-side at add time and are never re-accepted from a caller; adding a
+     * NEW member is an add-to-cart, which has its own eligibility checks.
+     */
+    async updateGroupMembers(userId, itemId, input) {
+        try {
+            const cart = await this.findByUserId(userId);
+            if (!cart)
+                throw new NotFoundError("Cart not found");
+            const itemIndex = cart.items.findIndex((item) => item.itemId === itemId);
+            if (itemIndex < 0)
+                throw new NotFoundError(ERR_CART_ITEM_NOT_FOUND);
+            const target = cart.items[itemIndex];
+            if (target.locked)
+                throw new ValidationError(ERR_CART_ITEM_LOCKED);
+            if (!target.groupMembers?.length) {
+                throw new ValidationError("This cart line has no members to update.");
+            }
+            const requested = new Map(input.groupMembers.map((m) => [m.productId, m.quantity]));
+            for (const productId of requested.keys()) {
+                if (!target.groupMembers.some((m) => m.productId === productId)) {
+                    throw new ValidationError("That item is not part of this cart line. Add it from the group page instead.");
+                }
+            }
+            const nextMembers = target.groupMembers
+                .map((m) => (requested.has(m.productId)
+                ? { ...m, quantity: requested.get(m.productId) }
+                : m))
+                .filter((m) => m.quantity > 0);
+            if (nextMembers.length === 0) {
+                return this.removeItem(userId, itemId);
+            }
+            const items = [...cart.items];
+            items[itemIndex] = {
+                ...target,
+                groupMembers: nextMembers,
+                price: this.deriveLinePrice(nextMembers),
+                updatedAt: new Date(),
+            };
+            const updatedCart = { ...cart, items, updatedAt: new Date() };
+            await this.db
+                .collection(this.collection)
+                .doc(userId)
+                .set(prepareForFirestore(updatedCart));
+            return updatedCart;
+        }
+        catch (error) {
+            if (error instanceof DatabaseError ||
+                error instanceof NotFoundError ||
+                error instanceof ValidationError) {
+                throw error;
+            }
+            throw new DatabaseError("Failed to update grouped cart line", error);
+        }
+    }
     async updateItem(userId, itemId, input) {
         try {
             const cart = await this.findByUserId(userId);

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";