@mohasinac/appkit 4.24.0 → 4.26.0

package/dist/_internal/server/features/bundles/actions.d.ts

@@ -12,4 +12,7 @@
  * bundleCategorySlug + bundleProductIds so checkout's bundle-expansion
  * helpers can fan out stock decrements to member products.
  */
-export declare function addBundleToCartAction(userId: string, bundleSlug: string): Promise<void>;
+export declare function addBundleToCartAction(userId: string, bundleSlug: string, 
+/** Number of COPIES of the whole bundle. Bundles are all-or-nothing, so this
+ *  is the only quantity a buyer can change — member quantities are fixed. */
+quantity?: number): Promise<void>;

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

@@ -16,12 +16,20 @@ 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 { productRepository } from "../../../../features/products/repository/products.repository";
+import { normalizeListingType } from "../../../../features/products/utils/listing-type";
 import { getDefaultCurrency } from "../../../../core/baseline-resolver";
-export async function addBundleToCartAction(userId, bundleSlug) {
+export async function addBundleToCartAction(userId, bundleSlug, 
+/** Number of COPIES of the whole bundle. Bundles are all-or-nothing, so this
+ *  is the only quantity a buyer can change — member quantities are fixed. */
+quantity = 1) {
     if (!userId)
         throw new ValidationError("User id is required");
     if (!bundleSlug)
         throw new ValidationError("Bundle slug is required");
+    if (!Number.isInteger(quantity) || quantity < 1 || quantity > 99) {
+        throw new ValidationError("Choose between 1 and 99 copies of this bundle.");
+    }
     const bundle = await categoriesRepository.findBySlugAndType(bundleSlug, "bundle");
     if (!bundle)
         throw new NotFoundError("Bundle not found");
@@ -39,17 +47,58 @@ export async function addBundleToCartAction(userId, bundleSlug) {
     // silently skipped it: a buyer with an unpaid auction win could keep shopping
     // by adding bundles.
     await assertCanAddNewItems(userId);
+    // Members, so the cart can show WHAT is in the bundle and checkout can
+    // prorate GST across them.
+    //
+    // Every member is ONE unit per copy. `BundleItemDetail` has no quantity field
+    // — its only per-member number is `drawCount` (prize-draw entries), and
+    // treating that as a stock quantity would silently change how much a
+    // prize-draw member decrements, which the stock fan-out has never done.
+    const memberIds = bundle.bundleProductIds ?? [];
+    const memberDocs = await Promise.all(memberIds.map((id) => productRepository.findById(id).catch(() => null)));
+    const groupMembers = memberDocs
+        .filter((p) => p !== null)
+        .map((p) => ({
+        productId: p.id,
+        quantity: 1,
+        unitPrice: p.price,
+        title: p.title,
+        image: p.images?.[0] ?? p.mainImage,
+        gstRate: p.gstRate,
+        hsnCode: p.hsnCode,
+        listingType: normalizeListingType(p),
+    }));
+    // `createdByStoreId` is optional on a bundle category and the tester fixture
+    // has none, so this used to write `storeId: ""` — which produces an order
+    // group keyed `standard:` with `storeId: undefined`: no seller notification,
+    // no shipping resolution, no payout. Fall back to a member's store.
+    const storeId = bundle.createdByStoreId ||
+        memberDocs.find((p) => p?.storeId)?.storeId ||
+        "";
+    const storeName = bundle.createdByStoreName ||
+        memberDocs.find((p) => p?.storeId === storeId)?.storeName ||
+        "";
     await cartRepository.addItem(userId, {
         productId: bundle.id,
         productTitle: bundle.name,
         productImage: bundle.display?.coverImage ?? "",
+        // The bundle's own locked price — NOT the sum of its members. That is the
+        // whole point of a bundle, and `unitPriceFor` honours it.
         price: bundle.bundlePrice,
         currency: getDefaultCurrency(),
-        quantity: 1,
-        storeId: bundle.createdByStoreId ?? "",
-        storeName: bundle.createdByStoreName ?? "",
+        quantity,
+        storeId,
+        storeName,
         listingType: "standard",
+        lineKind: "bundle",
+        groupId: bundle.id,
+        groupSlug: bundle.slug,
+        groupTitle: bundle.name,
         bundleCategorySlug: bundle.slug,
-        bundleProductIds: bundle.bundleProductIds ?? [],
+        ...(groupMembers.length > 0 && { groupMembers }),
+        // `bundleProductIds` stays written ONLY when we could not resolve members
+        // — it is the legacy read path (see CartItemDocument), and writing both
+        // would be exactly the mirror-drift Root Cause #42 warns about.
+        ...(groupMembers.length === 0 && { bundleProductIds: memberIds }),
     });
 }

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

@@ -13,8 +13,7 @@ import { ApiError, ValidationError, NotFoundError, ERROR_MESSAGES } from "../../
 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, lineTotalFor, unitPriceFor } from "../../../shared/checkout/order-math";
+import { computePreOrderDepositAmount, lineTotalFor, sumGroupGst, 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";
@@ -26,7 +25,8 @@ import { getAdminDb, getAdminRealtimeDb, RTDB_PATHS, } from "../../../../provide
 import { PRODUCT_COLLECTION, PRODUCT_CODES_SUBCOLLECTION } from "../../../../features/products/schemas/firestore";
 import { CART_COLLECTION } from "../../../../features/cart/schemas/index";
 // S-SBUNI-RULES 2026-05-13 — bundle cart-line stock fan-out helpers.
-import { getCartItemMemberIds, getExpandedDecrements, bucketCartItemsByStock, } from "./bundle-expansion";
+import { getCartItemMemberIds, getExpandedDecrements, bucketCartItemsByStock, isMultiMemberLine, } from "./bundle-expansion";
+import { expandCartLineToOrderRows } from "./expand-order-items";
 import { OrderStatusValues, PaymentStatusValues, PaymentMethodValues, OutOfStockPolicyValues, } from "../../../../features/orders/schemas/index";
 import { getDefaultCurrency } from "../../../../core/index";
 import { verifyPaymentSignatureWithKeys, fetchRazorpayOrder, paiseToRupees, } from "../../../../providers/payment-razorpay/index";
@@ -376,32 +376,13 @@ async function createOrderForGroup(group, orderType, ctx) {
     const { platformFee = 0, gstOnFee: platformFeeGst = 0 } = platformFeeByStore.get(firstItem.storeId) ?? {};
     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 }) => {
+    // A multi-member line expands into one row PER MEMBER sharing a groupSlug, so
+    // each row carries its own HSN/GST and can be cancelled independently; the
+    // receipt still collapses them under one header.
+    const orderItems = group.flatMap(({ item, product }) => {
         const lt = (product.listingType ?? "standard");
         const itemRule = getListingRule(lt);
-        // SB-UNI-5 2026-05-13 — forward bundle identifiers so the order-detail
-        // UI can collapse expanded lines back under a "Bundle: <name>" header.
-        const bundleFields = item.bundleCategorySlug && item.bundleProductIds
-            ? {
-                bundleCategorySlug: item.bundleCategorySlug,
-                bundleProductIds: item.bundleProductIds,
-            }
-            : {};
-        const unitPrice = unitPriceFor(item, product);
-        const gstFields = product.gstRate != null
-            ? { gstRate: product.gstRate, ...(product.hsnCode ? { hsnCode: product.hsnCode } : {}) }
-            : {};
-        const baseLine = {
-            productId: item.productId,
-            productTitle: item.productTitle,
-            image: item.productImage,
-            quantity: item.quantity,
-            unitPrice,
-            totalPrice: unitPrice * item.quantity,
-            ...bundleFields,
-            ...gstFields,
-        };
-        return itemRule.decorateOrderItem(baseLine, product);
+        return expandCartLineToOrderRows(item, product, ctx.productById).map((baseLine) => itemRule.decorateOrderItem(baseLine, product));
     });
     const totalQuantity = group.reduce((sum, { item }) => sum + item.quantity, 0);
     const { shippingFee, storeOwnerId, storeEmiEnabled, storeState } = await resolveShippingCost(firstItem.storeId);
@@ -412,16 +393,11 @@ async function createOrderForGroup(group, orderType, ctx) {
     let gstBreakdown;
     if (gstSettings?.enabled && buyerState) {
         const intraState = !!storeState && storeState === buyerState;
-        let taxableAmount = 0;
-        let gstAmount = 0;
-        for (const { item, product } of group) {
-            const lineTotal = lineTotalFor(item, product);
-            const rate = product.gstRate ?? 0;
-            if (rate > 0) {
-                taxableAmount += lineTotal;
-                gstAmount += calculateGst(rate, intraState, lineTotal).gstAmount;
-            }
-        }
+        // Per-member, not per-line: a bundle or grouped line spans several products
+        // with several different rates, and taxing the whole line at one product's
+        // rate is wrong in both directions. Shared with previewCheckoutPricing so
+        // the figure shown and the figure charged cannot drift.
+        const { taxableAmount, gstAmount } = sumGroupGst(group.map(({ item }) => item), ctx.productById, intraState);
         if (taxableAmount > 0) {
             gstBreakdown = intraState
                 ? { taxableAmount, cgst: Math.round(gstAmount / 2), sgst: gstAmount - Math.round(gstAmount / 2), igst: 0, gstAmount }
@@ -756,8 +732,9 @@ export async function createCheckoutOrderAction(input) {
             const availableItems = [];
             for (const { item, product } of bucketed.available) {
                 // S-SBUNI-RULES 2026-05-13 — sync preflight (prize-pool cap, pre-order
-                // quota) via rule registry. Bundles skip — they bypass the cart path.
-                if (!item.bundleProductIds?.length) {
+                // quota) via rule registry. Multi-member lines skip: their listingType
+                // describes the wrapper, not the members.
+                if (!isMultiMemberLine(item)) {
                     runSyncPreflight([{ item, product }], paymentMethod);
                 }
                 availableItems.push({ item, product });
@@ -792,7 +769,7 @@ export async function createCheckoutOrderAction(input) {
                     updatedAt: new Date(),
                 }, { merge: true });
             }
-            return { available: availableItems, unavailable: unavailableItems };
+            return { available: availableItems, unavailable: unavailableItems, productById };
         });
     }
     catch (err) {
@@ -805,7 +782,7 @@ export async function createCheckoutOrderAction(input) {
             .catch((logErr) => { void normalizeError(logErr); serverLogger.warn(AUDIT_LOG_FAIL_MSG, { error: logErr instanceof Error ? logErr.message : String(logErr) }); });
         throw err;
     }
-    const { available, unavailable } = stockResult;
+    const { available, unavailable, productById: checkoutProductById } = stockResult;
     if (available.length === 0) {
         failedCheckoutRepository
             .logCheckout(uid, "stock_failed", "All items out of stock", {
@@ -859,6 +836,7 @@ export async function createCheckoutOrderAction(input) {
         siteContactUpiVpa: siteSettings?.contact?.upiVpa,
         storeAddons: cart.storeAddons,
         platformFeeByStore,
+        productById: checkoutProductById,
     };
     for (const { items: group, orderType } of orderGroups) {
         total += await createOrderForGroup(group, orderType, groupCtx);
@@ -919,9 +897,18 @@ export async function previewCheckoutPricing(input) {
     // Best-effort product lookup — a preview never throws on a since-unpublished
     // product, it just falls back to the item's cart-snapshot price for that
     // line (same fallback cartRepository.getSubtotal() implicitly relies on).
-    const uniqueProductIds = [...new Set(cartItems.map((item) => item.productId))];
+    //
+    // Fetch by the EXPANDED member set, not by `item.productId`. On a bundle line
+    // `productId` is a CATEGORY id, so it resolved to null and the GST loop below
+    // read `product?.gstRate ?? 0` — which is precisely why a bundle has paid no
+    // GST since bundles reached the cart. The expansion is the same fan-out the
+    // stock decrement uses, so preview and placement agree by construction.
+    const expandedIds = getExpandedDecrements(cartItems).productIds;
+    const uniqueProductIds = [...new Set([...expandedIds, ...cartItems.map((i) => i.productId)])];
     const productDocs = await Promise.all(uniqueProductIds.map((pid) => productRepository.findById(pid)));
     const productById = new Map(uniqueProductIds.map((pid, i) => [pid, productDocs[i]]));
+    /** Non-null view, for helpers that need a definite product map. */
+    const resolvedProductById = new Map([...productById.entries()].filter(([, p]) => p != null));
     let resolvedAddress = null;
     if (addressId) {
         const addressDoc = await unitOfWork.addresses.findById(addressId);
@@ -955,12 +942,10 @@ export async function previewCheckoutPricing(input) {
         let groupGstAmount = 0;
         if (siteSettings?.gst?.enabled && resolvedAddress?.state) {
             const intraState = !!storeState && storeState === resolvedAddress.state;
-            for (const { item, product } of group) {
-                const lineTotal = lineTotalFor(item, product);
-                const rate = product?.gstRate ?? 0;
-                if (rate > 0)
-                    groupGstAmount += calculateGst(rate, intraState, lineTotal).gstAmount;
-            }
+            // Same helper createOrderForGroup uses — the two disagreeing is the
+            // recurring defect here (Root Cause #59), and it is the buyer seeing one
+            // tax figure and being charged another.
+            groupGstAmount = sumGroupGst(group.map(({ item }) => item), resolvedProductById, intraState).gstAmount;
         }
         const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: lineTotalFor(item, product) }));
         const { couponDiscount: groupCouponDiscount } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
@@ -1137,7 +1122,7 @@ async function refundDroppedItemsForRazorpayCheckout(input) {
  * from the inline version this replaced.
  */
 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 { appliedCoupons, cartSubtotal, storeAddons, platformFeeByStore, siteSettings, uid, userName, userEmail, razorpay_order_id, razorpay_payment_id, razorpay_signature, shippingAddress, notes, outOfStockPolicy, unavailablePaid, orderIds, emailsToSend, couponUsageAccumulator, productById: razorpayProductById, } = ctx;
     const firstItem = group[0].item;
     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
@@ -1185,30 +1170,15 @@ async function createRazorpayGroupOrder(group, orderType, ctx) {
     // alongside P-13 (Razorpay is disabled by default today, so this order
     // type doesn't currently carry a GST breakdown).
     // S-SBUNI-RULES 2026-05-13 — order-item decoration via rule registry.
-    const orderItems = group.map(({ item, product }) => {
+    // Same expansion as the COD/UPI path. This was a THIRD hand-rolled copy of
+    // the price rule (`isBundle ? item.price : product.price`) that — like the
+    // two in the consumer's Razorpay route — silently omitted `lockedPrice`, so
+    // an accepted offer paid through Razorpay was RECORDED at the seller's list
+    // price. `lineTotalFor` inside the expansion is the single definition.
+    const orderItems = group.flatMap(({ item, product }) => {
         const lt = (product?.listingType ?? "standard");
         const itemRule = getListingRule(lt);
-        // SB-UNI-5 2026-05-13 — bundle cart-lines surface the locked
-        // bundlePrice (item.price), not the representative member's
-        // product.price. Stock decrement still runs per member elsewhere.
-        const isBundle = Boolean(item.bundleCategorySlug && item.bundleProductIds?.length);
-        const unitPrice = isBundle ? item.price : product.price;
-        const bundleFields = isBundle
-            ? {
-                bundleCategorySlug: item.bundleCategorySlug,
-                bundleProductIds: item.bundleProductIds,
-            }
-            : {};
-        const baseLine = {
-            productId: item.productId,
-            productTitle: item.productTitle,
-            image: item.productImage,
-            quantity: item.quantity,
-            unitPrice,
-            totalPrice: unitPrice * item.quantity,
-            ...bundleFields,
-        };
-        return itemRule.decorateOrderItem(baseLine, product);
+        return expandCartLineToOrderRows(item, product, razorpayProductById).map((baseLine) => itemRule.decorateOrderItem(baseLine, product));
     });
     const totalQuantity = group.reduce((sum, { item }) => sum + item.quantity, 0);
     const imageUrls = [
@@ -1406,8 +1376,8 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
             .map(({ item, product }) => ({ item, product })),
     });
     // S-SBUNI-RULES 2026-05-13 — sync preflight via rule registry.
-    // Bundle items bypass the cart flow so skip the prize-pool cap.
-    const preflightPairs = productChecks.filter((p) => p.product !== null && p.product !== undefined && !p.item.bundleProductIds?.length);
+    // Multi-member lines skip the prize-pool cap, same reasoning as the COD path.
+    const preflightPairs = productChecks.filter((p) => p.product !== null && p.product !== undefined && !isMultiMemberLine(p.item));
     // This whole action is the Razorpay path — paymentMethod is always "online".
     runSyncPreflight(preflightPairs, "online");
     // SB-UNI-O 2026-05-15 — Live-item jurisdiction guard.
@@ -1536,6 +1506,7 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
             orderIds,
             emailsToSend,
             couponUsageAccumulator,
+            productById: productByIdPaid,
         });
     }
     await flushCouponUsageAccumulator(couponUsageAccumulator, uid);

package/dist/_internal/server/features/checkout/bundle-expansion.d.ts

@@ -22,19 +22,17 @@
  */
 import type { CartItemDocument } from "../../../../features/cart/schemas";
 import type { ProductDocument } from "../../../../features/products/schemas/firestore";
+export { getCartLineMembers, getCartItemMemberIds, isMultiMemberLine, type CartLineMemberRef, } from "../../../shared/checkout/line-members";
 export interface BundleExpansion {
     /** Unique product ids referenced by any cart item (regular or bundle member). */
     productIds: string[];
     /**
-     * Sum of requested quantities per product id. Bundle members get
-     * `item.quantity` per occurrence (so 2x of a bundle with member X
-     * decrements X by 2, not 1).
+     * Sum of requested quantities per product id, weighted by BOTH the number of
+     * copies of the line and each member's per-copy quantity — so 2 copies of a
+     * selection containing 3× member X decrement X by 6.
      */
     decrements: Map<string, number>;
 }
-/** Resolve the member-product ids for a cart item. Bundle items expand to
- *  `bundleProductIds[]`; regular items collapse to `[productId]`. */
-export declare function getCartItemMemberIds(item: CartItemDocument): string[];
 /** Build the unique-product-id + per-product decrement map for a cart. */
 export declare function getExpandedDecrements(cartItems: CartItemDocument[]): BundleExpansion;
 export interface StockShortfall {

package/dist/_internal/server/features/checkout/bundle-expansion.js

@@ -21,21 +21,21 @@
  * the first's decrement before re-running its own validation.
  */
 import { ProductStatusValues } from "../../../../features/products/schemas/firestore";
-/** Resolve the member-product ids for a cart item. Bundle items expand to
- *  `bundleProductIds[]`; regular items collapse to `[productId]`. */
-export function getCartItemMemberIds(item) {
-    if (item.bundleProductIds && item.bundleProductIds.length > 0) {
-        return item.bundleProductIds;
-    }
-    return [item.productId];
-}
+import { getCartLineMembers } from "../../../shared/checkout/line-members";
+// Re-exported here so the many existing importers of this module keep working;
+// the definitions live in shared/ because `rules/_registry.ts` and
+// `order-math.ts` need them too and cannot import from server/.
+export { getCartLineMembers, getCartItemMemberIds, isMultiMemberLine, } from "../../../shared/checkout/line-members";
 /** Build the unique-product-id + per-product decrement map for a cart. */
 export function getExpandedDecrements(cartItems) {
     const decrements = new Map();
     for (const item of cartItems) {
-        const memberIds = getCartItemMemberIds(item);
-        for (const pid of memberIds) {
-            decrements.set(pid, (decrements.get(pid) ?? 0) + item.quantity);
+        for (const member of getCartLineMembers(item)) {
+            // item.quantity = copies of the line, member.quantity = units per copy.
+            // Multiplying is the whole point: this used to add `item.quantity` alone,
+            // which silently assumed exactly one of each member.
+            const needed = item.quantity * member.quantity;
+            decrements.set(member.productId, (decrements.get(member.productId) ?? 0) + needed);
         }
     }
     return {
@@ -55,15 +55,17 @@ export function getExpandedDecrements(cartItems) {
  * that product, not just this item's slice.
  */
 export function validateCartItemStock(item, productById, decrements) {
-    const memberIds = getCartItemMemberIds(item);
-    for (const pid of memberIds) {
-        const product = productById.get(pid);
+    for (const member of getCartLineMembers(item)) {
+        const product = productById.get(member.productId);
         if (!product || product.status !== ProductStatusValues.PUBLISHED) {
-            return { productId: pid, availableQty: product?.availableQuantity ?? 0 };
+            return { productId: member.productId, availableQty: product?.availableQuantity ?? 0 };
         }
-        const totalNeeded = decrements.get(pid) ?? item.quantity;
+        // The fallback must be member-weighted too. Left as a bare `item.quantity`
+        // it would validate a line needing 3× of a member against demand for 1
+        // whenever the cumulative map didn't happen to carry that product.
+        const totalNeeded = decrements.get(member.productId) ?? item.quantity * member.quantity;
         if (product.availableQuantity < totalNeeded) {
-            return { productId: pid, availableQty: product.availableQuantity };
+            return { productId: member.productId, availableQty: product.availableQuantity };
         }
     }
     return null;

package/dist/_internal/server/features/checkout/expand-order-items.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Cart line → order rows.
+ *
+ * A multi-member line (a bundle, or a buyer-assembled group selection) becomes
+ * **N rows, one per member**, all sharing a `groupSlug`. Not one collapsed row.
+ *
+ * Why expand:
+ *  - `hsnCode` and `gstRate` are per-PRODUCT, and a GST invoice legally needs
+ *    HSN per line. A collapsed row can carry exactly one — which is why the
+ *    collapsed bundle row has always carried none.
+ *  - `cancelledQuantity` is per-product; partially cancelling one member of a
+ *    three-item group is impossible on a collapsed row.
+ *  - After per-member GST landed, `order.taxableAmount` is a sum over members.
+ *    With one collapsed row it would not equal the sum of the order's own
+ *    lines, and the invoice would visibly fail to add up.
+ *
+ * The buyer's receipt is unaffected: `groupOrderItemsByLine` collapses these
+ * rows back under one header, which it was already written to do.
+ */
+import type { CartItemDocument } from "../../../../features/cart/schemas/firestore";
+import type { ProductDocument } from "../../../../features/products/schemas/firestore";
+import type { OrderDocumentItem } from "../../../../features/orders/schemas/firestore";
+/** A row before rule decoration — the shape `decorateOrderItem` receives. */
+export type BaseOrderLine = Omit<OrderDocumentItem, "listingType">;
+/**
+ * Expand one cart line into the order rows it should produce.
+ *
+ * A single-product line yields exactly one row, identical to before.
+ *
+ * For a BUNDLE the per-row `totalPrice` is a prorated share of the bundle's
+ * locked price — never the member's list price — so the rows sum to what the
+ * buyer actually pays. For a GROUP the member prices already are the price, so
+ * the shares are exact.
+ */
+export declare function expandCartLineToOrderRows(item: CartItemDocument, representative: ProductDocument, productById: Map<string, ProductDocument>): BaseOrderLine[];

package/dist/_internal/server/features/checkout/expand-order-items.js

@@ -0,0 +1,85 @@
+/**
+ * Cart line → order rows.
+ *
+ * A multi-member line (a bundle, or a buyer-assembled group selection) becomes
+ * **N rows, one per member**, all sharing a `groupSlug`. Not one collapsed row.
+ *
+ * Why expand:
+ *  - `hsnCode` and `gstRate` are per-PRODUCT, and a GST invoice legally needs
+ *    HSN per line. A collapsed row can carry exactly one — which is why the
+ *    collapsed bundle row has always carried none.
+ *  - `cancelledQuantity` is per-product; partially cancelling one member of a
+ *    three-item group is impossible on a collapsed row.
+ *  - After per-member GST landed, `order.taxableAmount` is a sum over members.
+ *    With one collapsed row it would not equal the sum of the order's own
+ *    lines, and the invoice would visibly fail to add up.
+ *
+ * The buyer's receipt is unaffected: `groupOrderItemsByLine` collapses these
+ * rows back under one header, which it was already written to do.
+ */
+import { lineTotalFor, allocateAcrossMembers } from "../../../shared/checkout/order-math";
+/**
+ * Expand one cart line into the order rows it should produce.
+ *
+ * A single-product line yields exactly one row, identical to before.
+ *
+ * For a BUNDLE the per-row `totalPrice` is a prorated share of the bundle's
+ * locked price — never the member's list price — so the rows sum to what the
+ * buyer actually pays. For a GROUP the member prices already are the price, so
+ * the shares are exact.
+ */
+export function expandCartLineToOrderRows(item, representative, productById) {
+    const members = item.groupMembers;
+    const lineTotal = lineTotalFor(item, representative);
+    if (!members?.length) {
+        const gstFields = representative.gstRate != null
+            ? {
+                gstRate: representative.gstRate,
+                ...(representative.hsnCode ? { hsnCode: representative.hsnCode } : {}),
+            }
+            : {};
+        return [{
+                productId: item.productId,
+                productTitle: item.productTitle,
+                image: item.productImage,
+                quantity: item.quantity,
+                unitPrice: lineTotal / (item.quantity || 1),
+                totalPrice: lineTotal,
+                // Legacy collapsed bundle rows (no groupMembers) keep their old shape so
+                // orders already in flight and their UI stay untouched.
+                ...(item.bundleCategorySlug && item.bundleProductIds
+                    ? {
+                        bundleCategorySlug: item.bundleCategorySlug,
+                        bundleProductIds: item.bundleProductIds,
+                    }
+                    : {}),
+                ...gstFields,
+            }];
+    }
+    const groupSlug = item.groupSlug ?? item.bundleCategorySlug ?? item.groupId ?? item.itemId;
+    const groupSource = item.lineKind === "bundle" ? "bundle" : item.groupSource ?? "product-group";
+    const shares = allocateAcrossMembers(lineTotal, members.map((m) => m.unitPrice * m.quantity));
+    return members.map((m, i) => {
+        const product = productById.get(m.productId);
+        const gstRate = product?.gstRate ?? m.gstRate;
+        const hsnCode = product?.hsnCode ?? m.hsnCode;
+        // Units of this member across all copies of the line.
+        const quantity = m.quantity * item.quantity;
+        const totalPrice = shares[i];
+        return {
+            productId: m.productId,
+            productTitle: m.title,
+            image: m.image ?? "",
+            quantity,
+            unitPrice: quantity > 0 ? totalPrice / quantity : totalPrice,
+            totalPrice,
+            groupSlug,
+            groupTitle: item.groupTitle ?? item.productTitle,
+            groupSource,
+            // Kept on bundle rows so the pre-existing receipt grouping (which keys on
+            // this) keeps working for bundles without any UI change.
+            ...(item.bundleCategorySlug ? { bundleCategorySlug: item.bundleCategorySlug } : {}),
+            ...(gstRate != null ? { gstRate, ...(hsnCode ? { hsnCode } : {}) } : {}),
+        };
+    });
+}

package/dist/_internal/server/features/checkout/stock-restore.js

@@ -1,6 +1,7 @@
 import { ORDER_COLLECTION } from "../../../../features/orders/schemas/firestore";
 import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore";
 import { getListingRule } from "../../../shared/checkout/rules";
+import { getOrderItemMemberRefs } from "../../../shared/checkout/line-members";
 /**
  * Per-product quantity to restore for one order — the inverse of
  * `getExpandedDecrements` (bundle-expansion.ts), but reads from
@@ -15,11 +16,11 @@ function getOrderRestoreMap(order) {
         const remainingQty = item.quantity - (item.cancelledQuantity ?? 0);
         if (remainingQty <= 0)
             continue;
-        const memberIds = item.bundleProductIds && item.bundleProductIds.length > 0
-            ? item.bundleProductIds
-            : [item.productId];
-        for (const pid of memberIds) {
-            map.set(pid, (map.get(pid) ?? 0) + remainingQty);
+        // Must mirror `getExpandedDecrements` exactly, including the per-member
+        // weighting — restoring fewer units than were taken silently leaks stock.
+        for (const member of getOrderItemMemberRefs(item)) {
+            const pid = member.productId;
+            map.set(pid, (map.get(pid) ?? 0) + remainingQty * member.quantity);
         }
     }
     return map;

package/dist/_internal/server/features/grouped/index.d.ts

@@ -1,2 +1,4 @@
 export { getGroupedListingForDetail, getGroupedListingWithItems, listGroupedListings, listFeaturedGroupedListings, listSitemapGroupedListings, getGroupsForProduct, getGroupsWithItemsForProduct, getGroupsForCategory, getGroupsForBrand, type GroupedListingWithItems, type ListGroupedListingsParams, type SitemapGroupedListing, } from "./data";
+export { buildGroupedListingMetadata, type GroupedListingMetadataOptions, } from "./metadata";
+export { renderGroupedListingOg } from "./og";
 export { GROUPED_LISTINGS_PAGE_SIZE, GROUPED_LISTINGS_FEATURED_LIMIT, GROUPED_LISTINGS_SITEMAP_LIMIT, } from "../../../shared/features/grouped/config";

package/dist/_internal/server/features/grouped/index.js

@@ -1,2 +1,4 @@
 export { getGroupedListingForDetail, getGroupedListingWithItems, listGroupedListings, listFeaturedGroupedListings, listSitemapGroupedListings, getGroupsForProduct, getGroupsWithItemsForProduct, getGroupsForCategory, getGroupsForBrand, } from "./data";
+export { buildGroupedListingMetadata, } from "./metadata";
+export { renderGroupedListingOg } from "./og";
 export { GROUPED_LISTINGS_PAGE_SIZE, GROUPED_LISTINGS_FEATURED_LIMIT, GROUPED_LISTINGS_SITEMAP_LIMIT, } from "../../../shared/features/grouped/config";

package/dist/_internal/server/features/grouped/metadata.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Grouped-listing metadata helper.
+ *
+ * Maps a `GroupedListingDocument` to a Next.js Metadata object. Does NOT fetch
+ * — the page already did, and both share one `React.cache`d call. Site branding
+ * flows through opts so this file stays appkit-internal and
+ * consumer-configurable (§ "SSR Architecture").
+ */
+import type { Metadata } from "next";
+import type { GroupedListingDocument } from "../../../../features/grouped/schemas/firestore";
+export interface GroupedListingMetadataOptions {
+    siteName?: string;
+    siteUrl?: string;
+    /** Override the OG image — defaults to the group's coverImage. */
+    ogImageUrl?: string;
+}
+export declare function buildGroupedListingMetadata(group: GroupedListingDocument | null, opts?: GroupedListingMetadataOptions): Metadata;

package/dist/_internal/server/features/grouped/metadata.js

@@ -0,0 +1,48 @@
+/**
+ * Grouped-listing metadata helper.
+ *
+ * Maps a `GroupedListingDocument` to a Next.js Metadata object. Does NOT fetch
+ * — the page already did, and both share one `React.cache`d call. Site branding
+ * flows through opts so this file stays appkit-internal and
+ * consumer-configurable (§ "SSR Architecture").
+ */
+const FALLBACK_DESCRIPTION = "A curated group of related listings — pick the pieces you want and add them together.";
+export function buildGroupedListingMetadata(group, opts) {
+    const siteName = opts?.siteName?.trim() || "";
+    const suffix = siteName ? ` — ${siteName}` : "";
+    if (!group) {
+        return {
+            title: `Group not found${suffix}`,
+            description: "This group is unavailable or has been removed.",
+            robots: { index: false },
+        };
+    }
+    const title = `${group.title}${suffix}`;
+    const description = group.description?.trim() || FALLBACK_DESCRIPTION;
+    const siteUrl = opts?.siteUrl?.replace(/\/+$/, "");
+    const canonical = siteUrl ? `${siteUrl}/groups/${group.slug}` : undefined;
+    const cover = opts?.ogImageUrl ?? group.coverImage;
+    // A group below its `minActiveMembers` floor is hidden from every carousel;
+    // letting a search engine index it would surface a page the site itself has
+    // decided not to show.
+    const isPublic = group.isActive && group.visibilityStatus === "visible";
+    return {
+        title,
+        description,
+        robots: isPublic ? undefined : { index: false },
+        alternates: canonical ? { canonical } : undefined,
+        openGraph: {
+            title,
+            description,
+            url: canonical,
+            type: "website",
+            images: cover ? [{ url: cover }] : undefined,
+        },
+        twitter: {
+            card: cover ? "summary_large_image" : "summary",
+            title,
+            description,
+            images: cover ? [cover] : undefined,
+        },
+    };
+}