@mohasinac/appkit 4.25.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";
@@ -27,6 +26,7 @@ import { PRODUCT_COLLECTION, PRODUCT_CODES_SUBCOLLECTION } from "../../../../fea
 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, 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 }
@@ -793,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) {
@@ -806,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", {
@@ -860,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);
@@ -920,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);
@@ -956,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);
@@ -1138,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
@@ -1186,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 = [
@@ -1537,6 +1506,7 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
             orderIds,
             emailsToSend,
             couponUsageAccumulator,
+            productById: productByIdPaid,
         });
     }
     await flushCouponUsageAccumulator(couponUsageAccumulator, uid);

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/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,
+        },
+    };
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Grouped-listing OG card.
+ *
+ * Deliberately delegates to `renderBundleOgImage` rather than re-implementing
+ * the layout: the card is the same shape (title, description, cover, item
+ * count) minus the price, and `BundleOgData.priceLabel` / `.stockStatus` are
+ * already nullable for exactly that case. Forking it would give two ~150-line
+ * OG layouts to keep visually in step — the Duplication Framework's
+ * "same prop surface, same output" consolidate rule.
+ */
+import type { ReactElement } from "react";
+import type { GroupedListingDocument } from "../../../../features/grouped/schemas/firestore";
+export declare function renderGroupedListingOg(doc: Pick<GroupedListingDocument, "title" | "description" | "coverImage" | "productIds"> | null | undefined, opts: {
+    siteName: string;
+    baseUrl?: string;
+}): ReactElement;

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

@@ -0,0 +1,24 @@
+/**
+ * Grouped-listing OG card.
+ *
+ * Deliberately delegates to `renderBundleOgImage` rather than re-implementing
+ * the layout: the card is the same shape (title, description, cover, item
+ * count) minus the price, and `BundleOgData.priceLabel` / `.stockStatus` are
+ * already nullable for exactly that case. Forking it would give two ~150-line
+ * OG layouts to keep visually in step — the Duplication Framework's
+ * "same prop surface, same output" consolidate rule.
+ */
+import { renderBundleOgImage } from "../bundles/og";
+import { resolveOgImageUrl } from "../seo/og";
+export function renderGroupedListingOg(doc, opts) {
+    return renderBundleOgImage({
+        name: doc?.title ?? "Group",
+        description: doc?.description?.slice(0, 140) ??
+            `A curated group of related listings on ${opts.siteName}.`,
+        coverImageUrl: resolveOgImageUrl(doc?.coverImage ?? null, opts.baseUrl),
+        // A group has no price of its own — the buyer's selection is the price.
+        priceLabel: null,
+        itemCount: doc?.productIds?.length ?? null,
+        stockStatus: null,
+    }, opts.siteName);
+}

package/dist/_internal/server/features/seo/sitemap.js

@@ -210,6 +210,27 @@ async function fetchCategoryTypeUrls(baseUrl, categoryType, buildUrl, label) {
 const fetchCategoryUrls = (baseUrl) => fetchCategoryTypeUrls(baseUrl, "listing", (slug) => ROUTES.PUBLIC.CATEGORY_DETAIL(slug), "category");
 const fetchBrandUrls = (baseUrl) => fetchCategoryTypeUrls(baseUrl, "brand", (slug) => ROUTES.PUBLIC.BRAND_DETAIL(slug), "brand");
 const fetchBundleUrls = (baseUrl) => fetchCategoryTypeUrls(baseUrl, "bundle", (slug) => ROUTES.PUBLIC.BUNDLE_DETAIL(slug), "bundle");
+/**
+ * `groupedListings` documents. `listSitemapGroupedListings` has existed since
+ * the feature was built, but there was no public page for it to point at until
+ * `/groups/{slug}` — so it was never wired into the sitemap.
+ */
+async function fetchGroupedListingUrls(baseUrl) {
+    try {
+        const { listSitemapGroupedListings } = await import("../grouped/data");
+        const groups = await listSitemapGroupedListings();
+        return groups.map((g) => ({
+            url: `${baseUrl}${ROUTES.PUBLIC.GROUP_DETAIL(g.slug)}`,
+            lastModified: g.updatedAt,
+            changeFrequency: "weekly",
+            priority: 0.5,
+        }));
+    }
+    catch (err) {
+        void normalizeError(err);
+        return [];
+    }
+}
 async function fetchBlogPostUrls(baseUrl) {
     try {
         const db = getAdminDb();
@@ -293,11 +314,12 @@ async function fetchScammerUrls(baseUrl) {
     }
 }
 export async function buildSitemap({ baseUrl }) {
-    const [productUrls, categoryUrls, brandUrls, bundleUrls, eventUrls, blogUrls, auctionUrls, preOrderUrls, prizeDrawUrls, classifiedUrls, digitalCodeUrls, liveUrls, storeUrls, scammerUrls,] = await Promise.all([
+    const [productUrls, categoryUrls, brandUrls, bundleUrls, groupedListingUrls, eventUrls, blogUrls, auctionUrls, preOrderUrls, prizeDrawUrls, classifiedUrls, digitalCodeUrls, liveUrls, storeUrls, scammerUrls,] = await Promise.all([
         fetchProductUrls(baseUrl),
         fetchCategoryUrls(baseUrl),
         fetchBrandUrls(baseUrl),
         fetchBundleUrls(baseUrl),
+        fetchGroupedListingUrls(baseUrl),
         fetchEventUrls(baseUrl),
         fetchBlogPostUrls(baseUrl),
         fetchAuctionUrls(baseUrl),
@@ -314,6 +336,7 @@ export async function buildSitemap({ baseUrl }) {
         ...categoryUrls,
         ...brandUrls,
         ...bundleUrls,
+        ...groupedListingUrls,
         ...blogUrls,
         ...productUrls,
         ...auctionUrls,