@mohasinac/appkit 4.22.0 → 4.24.0

package/dist/_internal/server/features/bundles/actions.js

@@ -15,6 +15,7 @@
 import { NotFoundError, ValidationError } from "../../../../errors";
 import { categoriesRepository } from "../../../../repositories";
 import { cartRepository } from "../../../../features/cart/repository/cart.repository";
+import { assertCanAddNewItems } from "../../../../features/cart/actions/cart-actions";
 import { getDefaultCurrency } from "../../../../core/baseline-resolver";
 export async function addBundleToCartAction(userId, bundleSlug) {
     if (!userId)
@@ -32,6 +33,12 @@ export async function addBundleToCartAction(userId, bundleSlug) {
     if (!bundle.bundlePrice || bundle.bundlePrice < 1) {
         throw new ValidationError("Bundle price is not configured");
     }
+    // Bundles bypass `addItemToCart`'s capability gate deliberately (a bundle's
+    // `listingType: "standard"` is a lie told to satisfy it — `bundleRule` is
+    // `cartEligible: false`). The LANE gate is not optional though, and this path
+    // silently skipped it: a buyer with an unpaid auction win could keep shopping
+    // by adding bundles.
+    await assertCanAddNewItems(userId);
     await cartRepository.addItem(userId, {
         productId: bundle.id,
         productTitle: bundle.name,

package/dist/_internal/server/features/checkout/actions.js

@@ -14,7 +14,7 @@ import { ORDER_FIELDS } from "../../../../constants/field-names";
 import { serverLogger } from "../../../../monitoring";
 import { unitOfWork, siteSettingsRepository, userRepository, storeRepository, couponsRepository, claimedCouponsRepository, addressesRepository, productRepository, } from "../../../../repositories";
 import { calculateGst } from "../../../shared/fees/calculator";
-import { computePreOrderDepositAmount, unitPriceFor } from "../../../shared/checkout/order-math";
+import { computePreOrderDepositAmount, lineTotalFor, unitPriceFor } from "../../../shared/checkout/order-math";
 import { failedCheckoutRepository } from "../../../../features/checkout/repository/failed-checkout.repository";
 import { sendOrderConfirmationEmail } from "../../../../features/contact/server";
 import { splitCartIntoOrderGroups } from "../../../../features/orders/index";
@@ -374,7 +374,7 @@ async function createOrderForGroup(group, orderType, ctx) {
     // Add-ons are this store's choice, not the cart's — see OrderGroupContext.
     const { whatsappNotifyAddon = false, giftWrapAddon = false, giftWrapMessage, shipmentProtectionAddon = false, } = storeAddons?.[firstItem.storeId] ?? {};
     const { platformFee = 0, gstOnFee: platformFeeGst = 0 } = platformFeeByStore.get(firstItem.storeId) ?? {};
-    const groupTotal = group.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0);
+    const groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
     // S-SBUNI-RULES 2026-05-13 — order-item decoration via rule registry.
     const orderItems = group.map(({ item, product }) => {
         const lt = (product.listingType ?? "standard");
@@ -415,7 +415,7 @@ async function createOrderForGroup(group, orderType, ctx) {
         let taxableAmount = 0;
         let gstAmount = 0;
         for (const { item, product } of group) {
-            const lineTotal = unitPriceFor(item, product) * item.quantity;
+            const lineTotal = lineTotalFor(item, product);
             const rate = product.gstRate ?? 0;
             if (rate > 0) {
                 taxableAmount += lineTotal;
@@ -774,8 +774,16 @@ export async function createCheckoutOrderAction(input) {
                 }
             }
             if (availableItems.length > 0) {
-                const orderedProductIds = new Set(availableItems.map((a) => a.item.productId));
-                const remainingCartItems = cart.items.filter((ci) => !orderedProductIds.has(ci.productId));
+                // Clear by LINE identity, not by productId. `itemId` is what uniquely
+                // identifies a line; `productId` is not unique across lines and is not
+                // even a product id on a bundle/group line (it points at the bundle
+                // category, or at the group parent — which is itself purchasable). So
+                // matching on it deleted every OTHER line that happened to share the
+                // value: a loose "Set" parent sitting beside a group line built from
+                // that same group, or two lines of one product, both vanished when only
+                // one was ordered.
+                const orderedItemIds = new Set(availableItems.map((a) => a.item.itemId));
+                const remainingCartItems = cart.items.filter((ci) => !orderedItemIds.has(ci.itemId));
                 const cartRef = db.collection(CART_COLLECTION).doc(uid);
                 tx.set(cartRef, {
                     items: remainingCartItems,
@@ -818,13 +826,13 @@ export async function createCheckoutOrderAction(input) {
     const orderIds = [];
     let total = 0;
     const emailsToSend = [];
-    const cartSubtotal = orderGroups.reduce((s, { items: g }) => s + g.reduce((gs, { item, product }) => gs + unitPriceFor(item, product) * item.quantity, 0), 0);
+    const cartSubtotal = orderGroups.reduce((s, { items: g }) => s + g.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0), 0);
     const couponUsageAccumulator = new Map();
     // One commission on one transaction, capped, then apportioned across the
     // orders this cart splits into — see allocateCheckoutFees.
     const platformFeeByStore = allocateCheckoutFees(orderGroups.map(({ items: g }) => [
         g[0].item.storeId,
-        g.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0),
+        g.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
     ]), computeCheckoutFees(cartSubtotal, commissions));
     const groupCtx = {
         paymentMethod,
@@ -922,7 +930,7 @@ export async function previewCheckoutPricing(input) {
     }
     const checks = cartItems.map((item) => ({ item, product: productById.get(item.productId) ?? null }));
     const orderGroups = splitCartIntoOrderGroups(checks);
-    const cartSubtotal = orderGroups.reduce((s, { items: g }) => s + g.reduce((gs, { item, product }) => gs + unitPriceFor(item, product) * item.quantity, 0), 0);
+    const cartSubtotal = orderGroups.reduce((s, { items: g }) => s + g.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0), 0);
     // Same re-validation the real order placement runs, so the preview never
     // shows a discount the order won't actually honour.
     const { coupons: appliedCoupons } = await revalidateAppliedCoupons(cart.appliedCoupons ?? [], checks, uid);
@@ -932,7 +940,7 @@ export async function previewCheckoutPricing(input) {
     const stores = [];
     for (const { items: group } of orderGroups) {
         const firstItem = group[0].item;
-        const groupTotal = group.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0);
+        const groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
         const { shippingFee: groupShippingFee, storeState } = await resolveShippingCost(firstItem.storeId);
         // Add-ons are per store, read off the cart document — the same entry
         // createOrderForGroup will read when the order is actually placed.
@@ -948,13 +956,13 @@ export async function previewCheckoutPricing(input) {
         if (siteSettings?.gst?.enabled && resolvedAddress?.state) {
             const intraState = !!storeState && storeState === resolvedAddress.state;
             for (const { item, product } of group) {
-                const lineTotal = unitPriceFor(item, product) * item.quantity;
+                const lineTotal = lineTotalFor(item, product);
                 const rate = product?.gstRate ?? 0;
                 if (rate > 0)
                     groupGstAmount += calculateGst(rate, intraState, lineTotal).gstAmount;
             }
         }
-        const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: unitPriceFor(item, product) * item.quantity }));
+        const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: lineTotalFor(item, product) }));
         const { couponDiscount: groupCouponDiscount } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
         stores.push({
             storeId: firstItem.storeId,
@@ -1131,12 +1139,12 @@ async function refundDroppedItemsForRazorpayCheckout(input) {
 async function createRazorpayGroupOrder(group, orderType, ctx) {
     const { appliedCoupons, cartSubtotal, storeAddons, platformFeeByStore, siteSettings, uid, userName, userEmail, razorpay_order_id, razorpay_payment_id, razorpay_signature, shippingAddress, notes, outOfStockPolicy, unavailablePaid, orderIds, emailsToSend, couponUsageAccumulator, } = ctx;
     const firstItem = group[0].item;
-    const groupTotal = group.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0);
+    const groupTotal = group.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0);
     // Reuses the same store/seller lookup as the COD/UPI path above instead
     // of re-implementing it inline — was two sequential findById calls per
     // seller group here, duplicated from resolveShippingCost.
     const { shippingFee, storeOwnerId } = await resolveShippingCost(firstItem.storeId);
-    const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: unitPriceFor(item, product) * item.quantity }));
+    const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: lineTotalFor(item, product) }));
     const { couponDiscount, appliedDiscounts } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
     // Mirrors createOrderForGroup — without this the online-payment path wrote
     // the discount onto the order but never incremented usage.currentUsage or
@@ -1469,7 +1477,7 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
         const expectedAddonFees = expectedShippingGroups.reduce((sum, g) => {
             const storeId = g.items[0].item.storeId;
             const addons = cart.storeAddons?.[storeId] ?? {};
-            const groupSubtotal = g.items.reduce((gs, { item, product }) => gs + unitPriceFor(item, product) * item.quantity, 0);
+            const groupSubtotal = g.items.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0);
             return (sum +
                 computeWhatsAppNotifyFee(addons.whatsappNotifyAddon ?? false, commissionRates) +
                 computeGiftWrapFee(addons.giftWrapAddon ?? false, commissionRates) +
@@ -1501,12 +1509,12 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
     let total = 0;
     const emailsToSend = [];
     const cartSubtotal = orderGroups.reduce((s, { items: g }) => s +
-        g.reduce((gs, { item, product }) => gs + unitPriceFor(item, product) * item.quantity, 0), 0);
+        g.reduce((gs, { item, product }) => gs + lineTotalFor(item, product), 0), 0);
     const couponUsageAccumulator = new Map();
     // Same single capped commission + pro-rata split as the COD/UPI path.
     const platformFeeByStore = allocateCheckoutFees(orderGroups.map(({ items: g }) => [
         g[0].item.storeId,
-        g.reduce((sum, { item, product }) => sum + unitPriceFor(item, product) * item.quantity, 0),
+        g.reduce((sum, { item, product }) => sum + lineTotalFor(item, product), 0),
     ]), computeCheckoutFees(cartSubtotal, siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS));
     for (const { items: group, orderType } of orderGroups) {
         total += await createRazorpayGroupOrder(group, orderType, {

package/dist/_internal/server/features/checkout/locked-lines.js

@@ -237,7 +237,10 @@ export async function finalizeLockedLines(items, orderId) {
         }
         if (item.bidId) {
             try {
-                await bidRepository.attachOrder(item.bidId, orderId);
+                await bidRepository.attachOrder(item.bidId, orderId, {
+                    actor: { role: "system" },
+                    trigger: "finalizeLockedLines",
+                });
             }
             catch (err) {
                 void normalizeError(err);
@@ -270,7 +273,14 @@ async function closeOutBuyoutLosers(productId, winningBidId) {
         const losers = active.filter((e) => e.id !== winningBidId);
         if (losers.length === 0)
             return;
-        await bidRepository.markManyLost(losers.map((e) => e.ref));
+        // Pass the {ref, data} pairs whole, not just the refs — `getActiveByProduct`
+        // already returned the documents, so the timeline gets a real before-value
+        // at zero read cost.
+        await bidRepository.markManyLost(losers, {
+            actor: { role: "system" },
+            trigger: "finalizeLockedLines:buyoutClosedAuction",
+            reason: "A Buy Now purchase ended this auction.",
+        });
         serverLogger.info("finalizeLockedLines: buyout closed out losing bids", {
             productId,
             winningBidId,

package/dist/_internal/server/features/stores/adapters.d.ts

@@ -27,7 +27,7 @@ import type { StoreDetail, StoreListItem } from "../../../../features/stores/typ
  */
 export declare const PUBLIC_STORE_FIELDS: readonly ["id", "storeSlug", "ownerId", "storeName", "storeDescription", "storeCategory", "storeLogoURL", "storeBannerURL", "status", "isPublic", "stats", "bio", "location", "website", "socialLinks", "returnPolicy", "shippingPolicy", "isVacationMode", "vacationMessage", "createdAt"];
 /** Everything else, with the reason it stays server-side. */
-export declare const PRIVATE_STORE_FIELDS: readonly ["updatedAt", "whatsappConfig", "adminNotes", "isVerified", "suspensionReason", "capabilities", "customCommissionRate", "googleReviews", "shippingConfig", "emiEnabled", "isFeatured", "vacationReturnDate", "isTestData", "testDataExpiresAt"];
+export declare const PRIVATE_STORE_FIELDS: readonly ["updatedAt", "whatsappConfig", "adminNotes", "statusHistory", "statusHistoryTruncated", "isVerified", "suspensionReason", "capabilities", "customCommissionRate", "googleReviews", "shippingConfig", "emiEnabled", "isFeatured", "vacationReturnDate", "isTestData", "testDataExpiresAt"];
 /**
  * Accepted input: a `StoreDocument` (the common case) or a loosely-typed
  * Firestore row. The legacy top-level counters below predate `stats` and are

package/dist/_internal/server/features/stores/adapters.js

@@ -29,6 +29,11 @@ export const PRIVATE_STORE_FIELDS = [
     "updatedAt", // bookkeeping; no public reader
     "whatsappConfig", // Meta access token + WABA/catalog ids — secret
     "adminNotes", // schema comment: never shown to the owner or the public
+    // Admin decisions with actor UIDs and suspension reasons. The store OWNER
+    // sees this on their own admin surfaces; an anonymous visitor to /stores has
+    // no business reading who suspended whom and why.
+    "statusHistory",
+    "statusHistoryTruncated",
     "isVerified", // admin moderation state; surfaced via a separate badge feed if ever needed
     "suspensionReason", // admin moderation note
     "capabilities", // internal feature gating; server-enforced, never client-read

package/dist/_internal/server/jobs/core/auctionSettlement.js

@@ -32,7 +32,11 @@ async function releasePendingBuyouts(ctx, product, holds) {
     for (const hold of holds) {
         try {
             await cartRepository.removeItemsByBidId(hold.data.userId, hold.id);
-            await bidRepository.markCancelled(hold.id);
+            await bidRepository.markCancelled(hold.id, {
+                actor: { role: "system" },
+                trigger: "auctionSettlement:lapsedBuyoutHold",
+                reason: "The auction ended before this Buy Now claim was paid for.",
+            });
             await sendNotification({
                 userId: hold.data.userId,
                 type: "auction_ended",
@@ -84,7 +88,9 @@ async function settleAuction(ctx, product) {
     const reserve = product.reservePrice;
     if (typeof reserve === "number" && reserve > 0 && winnerEntry.data.bidAmount < reserve) {
         const batch = ctx.db.batch();
-        activeBids.forEach(({ ref }) => bidRepository.markLost(batch, ref));
+        // `data` comes from the same query as `ref`, so the timeline entry is
+        // free even on an auction that closed with hundreds of bids (Rule #6).
+        activeBids.forEach(({ ref, data }) => bidRepository.markLost(batch, ref, { actor: { role: "system" }, trigger: "auctionSettlement" }, data));
         productRepository.updateStatusInBatch(batch, product.id, "archived");
         await batch.commit();
         const reserveStore = product.storeId
@@ -117,8 +123,8 @@ async function settleAuction(ctx, product) {
         return;
     }
     const batch = ctx.db.batch();
-    bidRepository.markWon(batch, winnerEntry.ref);
-    loserEntries.forEach(({ ref }) => bidRepository.markLost(batch, ref));
+    bidRepository.markWon(batch, winnerEntry.ref, { actor: { role: "system" }, trigger: "auctionSettlement" }, winnerEntry.data);
+    loserEntries.forEach(({ ref, data }) => bidRepository.markLost(batch, ref, { actor: { role: "system" }, trigger: "auctionSettlement" }, data));
     // Two-axis model: mark as sold without changing publish status.
     batch.update(ctx.db.collection("products").doc(product.id), {
         isSold: true,

package/dist/_internal/server/jobs/core/offerExpiry.js

@@ -155,7 +155,11 @@ async function lapseUnpaidAuctionWins(ctx) {
         for (const { userId, item } of buyoutHolds) {
             try {
                 await cartRepository.removeItemsByBidId(userId, item.bidId);
-                await bidRepository.markCancelled(item.bidId);
+                await bidRepository.markCancelled(item.bidId, {
+                    actor: { role: "system" },
+                    trigger: "runOfferExpiry:buyoutLapsed",
+                    reason: "The Buy Now checkout window closed without payment.",
+                });
                 await sendNotification({
                     userId,
                     type: "auction_ended",
@@ -211,7 +215,11 @@ async function lapseUnpaidAuctionWins(ctx) {
     for (const { userId, item } of auctionLines) {
         try {
             await cartRepository.removeItemsByBidId(userId, item.bidId);
-            await bidRepository.markForfeited(item.bidId);
+            await bidRepository.markForfeited(item.bidId, {
+                actor: { role: "system" },
+                trigger: "runOfferExpiry:winUnpaid",
+                reason: "The 48-hour checkout window closed without payment.",
+            });
             await sendNotification({
                 userId,
                 type: "auction_ended",

package/dist/_internal/server/jobs/core/payoutBatch.js

@@ -9,7 +9,19 @@ import { payoutRepository } from "../../../../repositories";
 const MAX_FAILURES = 3;
 async function dispatch(ctx, entry) {
     const { ref, data: payout } = entry;
-    await payoutRepository.markProcessing(ref);
+    /*
+     * The batch's running copy of the document, threaded through every write.
+     *
+     * Two reasons it is not just `payout`. (a) The snapshot came from the
+     * pending query, so history costs no extra read. (b) The sequence is
+     * pending → processing → failed; diffing the final write against the
+     * ORIGINAL snapshot would record "pending → failed" and lose the dispatch
+     * attempt that is the whole reason anyone opens the timeline.
+     */
+    let current = payout;
+    const actor = { role: "system" };
+    await payoutRepository.markProcessing(ref, { actor }, current);
+    current = { ...current, status: "processing" };
     try {
         const keyId = ctx.env("RAZORPAY_KEY_ID") ?? "";
         const keySecret = ctx.env("RAZORPAY_KEY_SECRET") ?? "";
@@ -67,7 +79,7 @@ async function dispatch(ctx, entry) {
             throw new Error(`Razorpay ${response.status}: ${errBody}`);
         }
         const result = (await response.json());
-        await payoutRepository.recordSuccess(ref, result.id, result.status);
+        await payoutRepository.recordSuccess(ref, result.id, result.status, { actor }, current);
         ctx.logger.info(`Payout ${payout.id} dispatched`, { razorpayId: result.id, razorpayStatus: result.status });
     }
     catch (error) {
@@ -75,7 +87,7 @@ async function dispatch(ctx, entry) {
         const failureCount = (payout.failureCount ?? 0) + 1;
         const isFinal = failureCount >= MAX_FAILURES;
         const reason = error instanceof Error ? error.message : String(error);
-        await payoutRepository.recordFailure(ref, failureCount, reason, isFinal);
+        await payoutRepository.recordFailure(ref, failureCount, reason, isFinal, { actor }, current);
         if (isFinal) {
             ctx.logger.error(`Payout ${payout.id} permanently failed after ${MAX_FAILURES} attempts`, error, {
                 sellerId: payout.storeId,

package/dist/_internal/shared/actions/action-registry.js

@@ -2412,6 +2412,47 @@ export const ACTIONS = {
             description: "Navigate back from the cart to the product catalogue.",
             kind: "ghost",
         },
+        "add-group-to-cart": {
+            iconKey: "cart",
+            id: "cart.add-group-to-cart",
+            label: "Add selected to cart",
+            ariaLabel: "Add the selected group items to the cart as one line",
+            description: "Add a buyer-assembled selection of group members to the cart as a SINGLE line, rather than one line per product.",
+            kind: "primary",
+        },
+        "add-bundle-to-cart": {
+            iconKey: "cart",
+            id: "cart.add-bundle-to-cart",
+            label: "Add to cart",
+            ariaLabel: "Add this bundle to the cart",
+            description: "Add a whole bundle to the cart. Bundles are all-or-nothing — the quantity is the number of COPIES of the bundle.",
+            kind: "primary",
+        },
+        "remove-group-member": {
+            iconKey: "delete",
+            id: "cart.remove-group-member",
+            label: "Remove",
+            ariaLabel: "Remove this item from the group line",
+            description: "Drop one member out of a grouped cart line. Ghost rather than danger on purpose: it reuses the cart's existing undo affordance, and Rule #7.4's mandatory-confirmation requirement applies to destructive actions.",
+            kind: "ghost",
+        },
+        // No iconKey — these two exist only to keep the stepper's accessible names
+        // in the registry rather than hard-coded in the primitive. The glyphs are
+        // the literal "+" / "−" characters.
+        "increase-quantity": {
+            id: "cart.increase-quantity",
+            label: "+",
+            ariaLabel: "Increase quantity",
+            description: "Default accessible name for QuantityStepper's increment control.",
+            kind: "ghost",
+        },
+        "decrease-quantity": {
+            id: "cart.decrease-quantity",
+            label: "−",
+            ariaLabel: "Decrease quantity",
+            description: "Default accessible name for QuantityStepper's decrement control.",
+            kind: "ghost",
+        },
     },
     CHECKOUT: {
         "place-order": {

package/dist/_internal/shared/checkout/order-math.d.ts

@@ -7,9 +7,9 @@
 import type { CartItemDocument } from "../../../features/cart/schemas/firestore";
 import type { ProductDocument } from "../../../features/products/schemas/firestore";
 /**
- * The single source of truth for "what do we charge for this line".
+ * The single source of truth for "what do we charge for ONE COPY of this line".
  *
- * Three cases, in priority order:
+ * Four cases, in priority order:
  *
  *  1. **A locked price** — an accepted offer or a won auction. `lockedPrice` is
  *     the negotiated/won amount and it OVERRIDES the current listing price, which
@@ -17,15 +17,33 @@ import type { ProductDocument } from "../../../features/products/schemas/firesto
  *     copies of this function looked at `lockedPrice`, so an accepted offer was
  *     billed at the seller's listed price while the cart UI displayed the agreed
  *     one (`item.lockedPrice ?? item.price`) — the buyer saw ₹X and paid ₹Y.
- *  2. **A bundle line** (SB-UNI-5 2026-05-13) — `item.price` is the bundle price
- *     locked at add-time.
- *  3. **Everything else** — the live Firestore price, so a stale cart-cached
+ *  2. **A multi-member line** — the sum of its members' own snapshotted prices,
+ *     weighted by each member's per-copy quantity. A `"group"` line pins
+ *     `item.quantity` to 1, so this is both the unit price and the line total;
+ *     see the invariant on `CartLineMember`.
+ *  3. **A legacy bundle line** (SB-UNI-5 2026-05-13) — written before
+ *     `groupMembers` existed. `item.price` is the bundle price locked at
+ *     add-time.
+ *  4. **Everything else** — the live Firestore price, so a stale cart-cached
  *     price is never charged on a COD/UPI order.
  *
  * `product` may be null for a locked line whose listing has since been archived;
  * the locked price is still owed, so that case must not dereference `product`.
+ *
+ * 🛑 Do not hand-roll this rule at a call site. It has been re-derived by hand
+ * six times, and the two copies that lived in the consumer repo
+ * (`src/app/api/payment/create-order/route.ts`) each reproduced the bundle
+ * branch while silently omitting case 1 — so Razorpay captured the LIST price
+ * for an accepted offer while the cart displayed the negotiated one. Call
+ * `lineTotalFor` and let this function stay the only definition.
  */
 export declare function unitPriceFor(item: CartItemDocument, product: ProductDocument | null): number;
+/**
+ * What this line contributes to a subtotal: one copy's price × the number of
+ * copies. THE call site should use this rather than multiplying `unitPriceFor`
+ * itself — that multiplication is where the six hand-rolled copies diverged.
+ */
+export declare function lineTotalFor(item: CartItemDocument, product: ProductDocument | null): number;
 /**
  * P-6 — pre-order groups charge each product's own `preOrderDepositPercent`
  * (falling back to the generic COD deposit % when a product doesn't have one

package/dist/_internal/shared/checkout/order-math.js

@@ -1,8 +1,8 @@
 import { roundRupees } from "../../../utils/number.formatter";
 /**
- * The single source of truth for "what do we charge for this line".
+ * The single source of truth for "what do we charge for ONE COPY of this line".
  *
- * Three cases, in priority order:
+ * Four cases, in priority order:
  *
  *  1. **A locked price** — an accepted offer or a won auction. `lockedPrice` is
  *     the negotiated/won amount and it OVERRIDES the current listing price, which
@@ -10,18 +10,33 @@ import { roundRupees } from "../../../utils/number.formatter";
  *     copies of this function looked at `lockedPrice`, so an accepted offer was
  *     billed at the seller's listed price while the cart UI displayed the agreed
  *     one (`item.lockedPrice ?? item.price`) — the buyer saw ₹X and paid ₹Y.
- *  2. **A bundle line** (SB-UNI-5 2026-05-13) — `item.price` is the bundle price
- *     locked at add-time.
- *  3. **Everything else** — the live Firestore price, so a stale cart-cached
+ *  2. **A multi-member line** — the sum of its members' own snapshotted prices,
+ *     weighted by each member's per-copy quantity. A `"group"` line pins
+ *     `item.quantity` to 1, so this is both the unit price and the line total;
+ *     see the invariant on `CartLineMember`.
+ *  3. **A legacy bundle line** (SB-UNI-5 2026-05-13) — written before
+ *     `groupMembers` existed. `item.price` is the bundle price locked at
+ *     add-time.
+ *  4. **Everything else** — the live Firestore price, so a stale cart-cached
  *     price is never charged on a COD/UPI order.
  *
  * `product` may be null for a locked line whose listing has since been archived;
  * the locked price is still owed, so that case must not dereference `product`.
+ *
+ * 🛑 Do not hand-roll this rule at a call site. It has been re-derived by hand
+ * six times, and the two copies that lived in the consumer repo
+ * (`src/app/api/payment/create-order/route.ts`) each reproduced the bundle
+ * branch while silently omitting case 1 — so Razorpay captured the LIST price
+ * for an accepted offer while the cart displayed the negotiated one. Call
+ * `lineTotalFor` and let this function stay the only definition.
  */
 export function unitPriceFor(item, product) {
     if (typeof item.lockedPrice === "number" && item.lockedPrice > 0) {
         return item.lockedPrice;
     }
+    if (item.groupMembers?.length) {
+        return roundRupees(item.groupMembers.reduce((sum, m) => sum + m.unitPrice * m.quantity, 0));
+    }
     if (item.bundleCategorySlug && item.bundleProductIds?.length) {
         return item.price;
     }
@@ -31,6 +46,14 @@ export function unitPriceFor(item, product) {
     // crash whenever a cart line outlives its listing.
     return product?.price ?? item.price;
 }
+/**
+ * What this line contributes to a subtotal: one copy's price × the number of
+ * copies. THE call site should use this rather than multiplying `unitPriceFor`
+ * itself — that multiplication is where the six hand-rolled copies diverged.
+ */
+export function lineTotalFor(item, product) {
+    return unitPriceFor(item, product) * item.quantity;
+}
 /**
  * P-6 — pre-order groups charge each product's own `preOrderDepositPercent`
  * (falling back to the generic COD deposit % when a product doesn't have one
@@ -41,7 +64,7 @@ export function unitPriceFor(item, product) {
  */
 export function computePreOrderDepositAmount(group, defaultDepositPercent) {
     const raw = group.reduce((sum, { item, product }) => {
-        const lineTotal = unitPriceFor(item, product) * item.quantity;
+        const lineTotal = lineTotalFor(item, product);
         const pct = product.preOrderDepositPercent ?? defaultDepositPercent;
         return sum + lineTotal * (pct / 100); // audit-money-units-ok: percentage divisor, not paise
     }, 0);

package/dist/_internal/shared/checkout/rules/_limits.d.ts

@@ -1,6 +1,16 @@
 /** Checkout window / capacity constants — single source of truth. */
-/** Maximum distinct line items in one cart (hard cap, already enforced at addToCart). */
-export declare const CART_MAX_ITEMS = 50;
+/**
+ * Maximum distinct line items in one cart (hard cap, enforced at every
+ * add-to-cart entry point).
+ *
+ * Re-exported, not re-declared. This value existed as three independent `= 50`
+ * literals — here, in `constants/limits.ts`, and in
+ * `_internal/shared/features/cart/config.ts` — with nothing tying them
+ * together, so raising the cap in one place would have left two silently
+ * disagreeing. `constants/limits.ts` is a dependency-free leaf module, so this
+ * costs no import chain.
+ */
+export { CART_MAX_ITEMS } from "../../../../constants/limits";
 /**
  * Maximum number of order documents that can be created in one checkout
  * transaction.  If the cart produces more groups than this the checkout is

package/dist/_internal/shared/checkout/rules/_limits.js

@@ -1,6 +1,16 @@
 /** Checkout window / capacity constants — single source of truth. */
-/** Maximum distinct line items in one cart (hard cap, already enforced at addToCart). */
-export const CART_MAX_ITEMS = 50;
+/**
+ * Maximum distinct line items in one cart (hard cap, enforced at every
+ * add-to-cart entry point).
+ *
+ * Re-exported, not re-declared. This value existed as three independent `= 50`
+ * literals — here, in `constants/limits.ts`, and in
+ * `_internal/shared/features/cart/config.ts` — with nothing tying them
+ * together, so raising the cap in one place would have left two silently
+ * disagreeing. `constants/limits.ts` is a dependency-free leaf module, so this
+ * costs no import chain.
+ */
+export { CART_MAX_ITEMS } from "../../../../constants/limits";
 /**
  * Maximum number of order documents that can be created in one checkout
  * transaction.  If the cart produces more groups than this the checkout is

package/dist/_internal/shared/features/cart/config.d.ts

@@ -1,3 +1,4 @@
-export declare const CART_MAX_ITEMS = 50;
+/** Re-exported from the single declaration — see `constants/limits.ts`. */
+export { CART_MAX_ITEMS } from "../../../../constants/limits";
 export declare const CART_SESSION_TTL_DAYS = 30;
 export declare const CART_GUEST_STORAGE_KEY = "appkit:cart";

package/dist/_internal/shared/features/cart/config.js

@@ -1,3 +1,4 @@
-export const CART_MAX_ITEMS = 50;
+/** Re-exported from the single declaration — see `constants/limits.ts`. */
+export { CART_MAX_ITEMS } from "../../../../constants/limits";
 export const CART_SESSION_TTL_DAYS = 30;
 export const CART_GUEST_STORAGE_KEY = "appkit:cart";

package/dist/_internal/shared/features/cart/schema.d.ts

@@ -22,9 +22,9 @@ export declare const addToCartSchema: z.ZodObject<{
     productId: string;
     productTitle: string;
     productImage: string;
+    isOffer?: boolean | undefined;
     offerId?: string | undefined;
     lockedPrice?: number | undefined;
-    isOffer?: boolean | undefined;
 }, {
     storeId: string;
     price: number;
@@ -35,9 +35,9 @@ export declare const addToCartSchema: z.ZodObject<{
     storeName?: string | undefined;
     quantity?: number | undefined;
     productImage?: string | undefined;
+    isOffer?: boolean | undefined;
     offerId?: string | undefined;
     lockedPrice?: number | undefined;
-    isOffer?: boolean | undefined;
 }>;
 export declare const updateCartItemSchema: z.ZodObject<{
     productId: z.ZodString;
@@ -80,9 +80,9 @@ export declare const mergeGuestCartSchema: z.ZodObject<{
         productId: string;
         productTitle: string;
         productImage: string;
+        isOffer?: boolean | undefined;
         offerId?: string | undefined;
         lockedPrice?: number | undefined;
-        isOffer?: boolean | undefined;
     }, {
         storeId: string;
         price: number;
@@ -93,9 +93,9 @@ export declare const mergeGuestCartSchema: z.ZodObject<{
         storeName?: string | undefined;
         quantity?: number | undefined;
         productImage?: string | undefined;
+        isOffer?: boolean | undefined;
         offerId?: string | undefined;
         lockedPrice?: number | undefined;
-        isOffer?: boolean | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     guestItems: {
@@ -108,9 +108,9 @@ export declare const mergeGuestCartSchema: z.ZodObject<{
         productId: string;
         productTitle: string;
         productImage: string;
+        isOffer?: boolean | undefined;
         offerId?: string | undefined;
         lockedPrice?: number | undefined;
-        isOffer?: boolean | undefined;
     }[];
 }, {
     guestItems: {
@@ -123,9 +123,9 @@ export declare const mergeGuestCartSchema: z.ZodObject<{
         storeName?: string | undefined;
         quantity?: number | undefined;
         productImage?: string | undefined;
+        isOffer?: boolean | undefined;
         offerId?: string | undefined;
         lockedPrice?: number | undefined;
-        isOffer?: boolean | undefined;
     }[];
 }>;
 /**