@mohasinac/appkit 4.9.4 → 4.10.0

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

@@ -11,7 +11,7 @@ import { roundRupees } from "../../../../utils/number.formatter";
 import { ApiError, ValidationError, NotFoundError, ERROR_MESSAGES } from "../../../../errors";
 import { ORDER_FIELDS } from "../../../../constants/field-names";
 import { serverLogger } from "../../../../monitoring";
-import { unitOfWork, siteSettingsRepository, userRepository, storeRepository, couponsRepository, claimedCouponsRepository, addressesRepository, } from "../../../../repositories";
+import { unitOfWork, siteSettingsRepository, userRepository, storeRepository, couponsRepository, claimedCouponsRepository, addressesRepository, productRepository, } from "../../../../repositories";
 import { calculateGst } from "../../../shared/fees/calculator";
 import { computePreOrderDepositAmount } from "../../../shared/checkout/order-math";
 import { failedCheckoutRepository } from "../../../../features/checkout/repository/failed-checkout.repository";
@@ -151,7 +151,13 @@ function accumulateCouponUsage(accumulator, couponCode, couponId, discountAmount
     entry.totalDiscount += discountAmount;
     accumulator.set(couponCode, entry);
 }
-async function resolveShippingCost(storeId) {
+/**
+ * Exported so `/api/payment/create-order` (pre-charge amount) and the
+ * read-only `previewCheckoutPricing` (Order Summary display) can compute the
+ * exact same per-seller shipping fee that order creation charges/records —
+ * a single source of truth instead of a third re-implementation.
+ */
+export async function resolveShippingCost(storeId) {
     if (!storeId)
         return { shippingFee: 0, storeOwnerId: undefined, storeEmiEnabled: false, storeState: undefined };
     const store = await storeRepository.findById(storeId);
@@ -172,6 +178,55 @@ async function resolveStoreState(storeId) {
     const pickup = addresses.find((a) => a.isDefault) ?? addresses[0];
     return pickup?.state;
 }
+/**
+ * Prorates every buyer-applied coupon against one seller-group's total. Pure
+ * — no side effects (usage-accumulator bookkeeping is layered on by callers
+ * that actually place an order). Shared by createOrderForGroup,
+ * createRazorpayGroupOrder, and the read-only previewCheckoutPricing so the
+ * three can never drift on how a coupon splits across sellers (was three
+ * near-identical copies before this extraction — Duplication Decision
+ * Framework's Rule of Three).
+ */
+function computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, storeId) {
+    let couponDiscount = 0;
+    const appliedDiscounts = [];
+    for (const coupon of appliedCoupons) {
+        let couponGroupDiscount = 0;
+        const isSellerScoped = coupon.scope === "seller" && coupon.storeId;
+        if (isSellerScoped) {
+            if (coupon.storeId !== storeId)
+                continue;
+            if (coupon.applicableItemIds?.length) {
+                const eligibleTotal = groupLines
+                    .filter((l) => coupon.applicableItemIds.includes(l.itemId))
+                    .reduce((s, l) => s + l.lineTotal, 0);
+                couponGroupDiscount =
+                    eligibleTotal > 0
+                        ? Math.min(roundRupees((eligibleTotal / groupTotal) * coupon.discountAmount), eligibleTotal)
+                        : 0;
+            }
+            else {
+                couponGroupDiscount = Math.min(coupon.discountAmount, groupTotal);
+            }
+        }
+        else if (cartSubtotal > 0) {
+            couponGroupDiscount = Math.min(roundRupees((groupTotal / cartSubtotal) * coupon.discountAmount), groupTotal);
+        }
+        if (couponGroupDiscount > 0) {
+            couponDiscount += couponGroupDiscount;
+            appliedDiscounts.push({
+                code: coupon.code,
+                couponId: coupon.couponId,
+                type: "coupon",
+                discountAmount: couponGroupDiscount,
+                scope: coupon.scope,
+                storeId: coupon.storeId,
+            });
+        }
+    }
+    couponDiscount = Math.min(couponDiscount, groupTotal);
+    return { couponDiscount, appliedDiscounts };
+}
 function buildStockUpdatePayload(product, qtyDelta) {
     const lt = (product.listingType ?? "standard");
     const rule = getListingRule(lt);
@@ -313,50 +368,15 @@ async function createOrderForGroup(group, orderType, ctx) {
     const whatsappNotifyFee = computeWhatsAppNotifyFee(whatsappNotifyAddon, commissions);
     const giftWrapFee = computeGiftWrapFee(giftWrapAddon, commissions);
     const shipmentProtectionFee = computeShipmentProtectionFee(groupTotal, shipmentProtectionAddon, commissions);
-    let couponDiscount = 0;
-    const appliedDiscounts = [];
     const groupCouponCodes = new Set();
-    for (const coupon of appliedCoupons) {
-        let couponGroupDiscount = 0;
-        const isSellerScoped = coupon.scope === "seller" && coupon.storeId;
-        if (isSellerScoped) {
-            if (coupon.storeId !== firstItem.storeId)
-                continue;
-            if (coupon.applicableItemIds?.length) {
-                const eligibleTotal = group
-                    .filter(({ item }) => coupon.applicableItemIds.includes(item.itemId))
-                    .reduce((s, { item }) => s + item.price * item.quantity, 0);
-                couponGroupDiscount =
-                    eligibleTotal > 0
-                        ? Math.min(roundRupees((eligibleTotal / groupTotal) * coupon.discountAmount), eligibleTotal)
-                        : 0;
-            }
-            else {
-                couponGroupDiscount = Math.min(coupon.discountAmount, groupTotal);
-            }
-        }
-        else {
-            if (cartSubtotal > 0) {
-                couponGroupDiscount = Math.min(roundRupees((groupTotal / cartSubtotal) * coupon.discountAmount), groupTotal);
-            }
-        }
-        if (couponGroupDiscount > 0) {
-            couponDiscount += couponGroupDiscount;
-            appliedDiscounts.push({
-                code: coupon.code,
-                couponId: coupon.couponId,
-                type: "coupon",
-                discountAmount: couponGroupDiscount,
-                scope: coupon.scope,
-                storeId: coupon.storeId,
-            });
-            if (coupon.couponId) {
-                accumulateCouponUsage(couponUsageAccumulator, coupon.code, coupon.couponId, couponGroupDiscount);
-                groupCouponCodes.add(coupon.code);
-            }
+    const groupLines = group.map(({ item }) => ({ itemId: item.itemId, lineTotal: item.price * item.quantity }));
+    const { couponDiscount, appliedDiscounts } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
+    for (const discount of appliedDiscounts) {
+        if (discount.couponId) {
+            accumulateCouponUsage(couponUsageAccumulator, discount.code, discount.couponId, discount.discountAmount);
+            groupCouponCodes.add(discount.code);
         }
     }
-    couponDiscount = Math.min(couponDiscount, groupTotal);
     const orderTotal = Math.max(0, groupTotal - couponDiscount) + shippingFee + codHandlingFee + whatsappNotifyFee + giftWrapFee + shipmentProtectionFee + (emiSchedule?.surchargeAmount ?? 0) + (gstBreakdown?.gstAmount ?? 0);
     const imageUrls = [
         ...new Set(group
@@ -733,6 +753,105 @@ export async function createCheckoutOrderAction(input) {
         ...(unavailable.length > 0 ? { unavailableItems: unavailable } : {}),
     };
 }
+const EMPTY_PRICING_PREVIEW = {
+    subtotal: 0,
+    shippingFee: 0,
+    codHandlingFee: 0,
+    whatsappNotifyFee: 0,
+    giftWrapFee: 0,
+    shipmentProtectionFee: 0,
+    gstAmount: 0,
+    couponDiscount: 0,
+    total: 0,
+};
+/**
+ * Read-only "what will I actually be charged" preview for the checkout
+ * Order Summary. Reuses the exact same building blocks
+ * createCheckoutOrderAction / verifyAndPlaceRazorpayOrderAction use when an
+ * order is actually placed — resolveShippingCost, the compute*Fee helpers,
+ * computeGroupCouponDiscount, and the GST calc — so the number shown to the
+ * buyer can never diverge from what gets charged/recorded. Never decrements
+ * stock, creates an order, or writes coupon usage.
+ */
+export async function previewCheckoutPricing(input) {
+    const { userId: uid, addressId, paymentMethod, excludedProductIds = [], whatsappNotifyAddon = false, giftWrapAddon = false, shipmentProtectionAddon = false, } = input;
+    const siteSettings = await siteSettingsRepository.getSingleton();
+    const commissions = siteSettings?.commissions ?? CHECKOUT_DEFAULT_COMMISSIONS;
+    const cart = await unitOfWork.carts.getOrCreate(uid);
+    const excludedSet = new Set(excludedProductIds);
+    const selectedSet = cart.selectedItemIds?.length ? new Set(cart.selectedItemIds) : null;
+    const cartItems = (cart.items ?? []).filter((item) => !excludedSet.has(item.productId) && (!selectedSet || selectedSet.has(item.itemId)));
+    if (cartItems.length === 0)
+        return EMPTY_PRICING_PREVIEW;
+    // 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))];
+    const productDocs = await Promise.all(uniqueProductIds.map((pid) => productRepository.findById(pid)));
+    const productById = new Map(uniqueProductIds.map((pid, i) => [pid, productDocs[i]]));
+    let resolvedAddress = null;
+    if (addressId) {
+        const addressDoc = await unitOfWork.addresses.findById(addressId);
+        resolvedAddress =
+            addressDoc && addressDoc.ownerType === "user" && addressDoc.ownerId === uid ? addressDoc : null;
+    }
+    const unitPriceFor = (item, product) => item.bundleCategorySlug && item.bundleProductIds?.length ? item.price : (product?.price ?? item.price);
+    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 appliedCoupons = cart.appliedCoupons ?? [];
+    let shippingFee = 0;
+    let codHandlingFee = 0;
+    let whatsappNotifyFeeTotal = 0;
+    let giftWrapFeeTotal = 0;
+    let shipmentProtectionFeeTotal = 0;
+    let gstAmount = 0;
+    let couponDiscount = 0;
+    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 { shippingFee: groupShippingFee, storeState } = await resolveShippingCost(firstItem.storeId);
+        shippingFee += groupShippingFee;
+        // Mirrors createOrderForGroup exactly — the COD handling fee is only
+        // ever charged for literal "cod" (pay the courier), never upi_manual or
+        // cash (both pre-paid via UPI/bank transfer before dispatch).
+        if (paymentMethod === "cod")
+            codHandlingFee += computeCodHandlingFee(groupTotal, commissions);
+        whatsappNotifyFeeTotal += computeWhatsAppNotifyFee(whatsappNotifyAddon, commissions);
+        giftWrapFeeTotal += computeGiftWrapFee(giftWrapAddon, commissions);
+        shipmentProtectionFeeTotal += computeShipmentProtectionFee(groupTotal, shipmentProtectionAddon, commissions);
+        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 rate = product?.gstRate ?? 0;
+                if (rate > 0)
+                    gstAmount += calculateGst(rate, intraState, lineTotal).gstAmount;
+            }
+        }
+        const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: unitPriceFor(item, product) * item.quantity }));
+        const { couponDiscount: groupCouponDiscount } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
+        couponDiscount += groupCouponDiscount;
+    }
+    const total = Math.max(0, cartSubtotal - couponDiscount) +
+        shippingFee +
+        codHandlingFee +
+        whatsappNotifyFeeTotal +
+        giftWrapFeeTotal +
+        shipmentProtectionFeeTotal +
+        gstAmount;
+    return {
+        subtotal: cartSubtotal,
+        shippingFee,
+        codHandlingFee,
+        whatsappNotifyFee: whatsappNotifyFeeTotal,
+        giftWrapFee: giftWrapFeeTotal,
+        shipmentProtectionFee: shipmentProtectionFeeTotal,
+        gstAmount,
+        couponDiscount,
+        total,
+    };
+}
 /**
  * Mark an order as paid after a payment provider verifies the transaction.
  * Consumers call this from /api/payment/verify or a payment webhook.
@@ -864,43 +983,8 @@ async function createRazorpayGroupOrder(group, orderType, ctx) {
     // of re-implementing it inline — was two sequential findById calls per
     // seller group here, duplicated from resolveShippingCost.
     const { shippingFee, storeOwnerId } = await resolveShippingCost(firstItem.storeId);
-    let couponDiscount = 0;
-    const appliedDiscounts = [];
-    for (const coupon of appliedCoupons) {
-        let couponGroupDiscount = 0;
-        const isSellerScoped = coupon.scope === "seller" && coupon.storeId;
-        if (isSellerScoped) {
-            if (coupon.storeId !== firstItem.storeId)
-                continue;
-            if (coupon.applicableItemIds?.length) {
-                const eligibleTotal = group
-                    .filter(({ item }) => coupon.applicableItemIds.includes(item.itemId))
-                    .reduce((s, { item, product }) => s + unitPriceFor(item, product) * item.quantity, 0);
-                couponGroupDiscount =
-                    eligibleTotal > 0
-                        ? Math.min(roundRupees((eligibleTotal / groupTotal) * coupon.discountAmount), eligibleTotal)
-                        : 0;
-            }
-            else {
-                couponGroupDiscount = Math.min(coupon.discountAmount, groupTotal);
-            }
-        }
-        else if (cartSubtotal > 0) {
-            couponGroupDiscount = Math.min(roundRupees((groupTotal / cartSubtotal) * coupon.discountAmount), groupTotal);
-        }
-        if (couponGroupDiscount > 0) {
-            couponDiscount += couponGroupDiscount;
-            appliedDiscounts.push({
-                code: coupon.code,
-                couponId: coupon.couponId,
-                type: "coupon",
-                discountAmount: couponGroupDiscount,
-                scope: coupon.scope,
-                storeId: coupon.storeId,
-            });
-        }
-    }
-    couponDiscount = Math.min(couponDiscount, groupTotal);
+    const groupLines = group.map(({ item, product }) => ({ itemId: item.itemId, lineTotal: unitPriceFor(item, product) * item.quantity }));
+    const { couponDiscount, appliedDiscounts } = computeGroupCouponDiscount(appliedCoupons, groupLines, groupTotal, cartSubtotal, firstItem.storeId);
     const rawPlatformFee = roundRupees(groupTotal * (platformFeePercent / 100));
     const gstOnFee = roundRupees(rawPlatformFee * (gstPercent / 100));
     const platformFee = rawPlatformFee + gstOnFee;
@@ -1165,7 +1249,14 @@ export async function verifyAndPlaceRazorpayOrderAction(input) {
         }, 0);
         const expectedPlatformFee = roundRupees(cartSubtotalRs * (platformFeePercent / 100));
         const expectedGstOnFee = roundRupees(expectedPlatformFee * (gstPercent / 100));
-        const expectedPaymentAmountRs = cartSubtotalRs + expectedPlatformFee + expectedGstOnFee;
+        // Same per-seller-group shipping sum /api/payment/create-order charged
+        // upfront (and the same resolveShippingCost createRazorpayGroupOrder
+        // below will use to build each order's recorded totalPrice) — keeps this
+        // floor check from passing an amount that's short by the shipping fee.
+        const expectedShippingGroups = splitCartIntoOrderGroups(bucketedPaid.available);
+        const expectedShippingFees = await Promise.all(expectedShippingGroups.map((g) => resolveShippingCost(g.items[0].item.storeId)));
+        const expectedShippingFee = expectedShippingFees.reduce((sum, r) => sum + r.shippingFee, 0);
+        const expectedPaymentAmountRs = cartSubtotalRs + expectedPlatformFee + expectedGstOnFee + expectedShippingFee;
         const rzpOrderRecord = await fetchRazorpayOrder(razorpay_order_id);
         const paidAmountRs = paiseToRupees(rzpOrderRecord.amount);
         if (paidAmountRs < expectedPaymentAmountRs - 1) {

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

@@ -1,3 +1,3 @@
-export { createCheckoutOrderAction, attachPaymentAction, verifyAndPlaceRazorpayOrderAction, type CreateCheckoutOrderInput, type VerifyAndPlaceRazorpayOrderInput, } from "./actions";
+export { createCheckoutOrderAction, attachPaymentAction, verifyAndPlaceRazorpayOrderAction, previewCheckoutPricing, resolveShippingCost, type CreateCheckoutOrderInput, type VerifyAndPlaceRazorpayOrderInput, type CheckoutPricingPreviewInput, type CheckoutPricingPreview, } from "./actions";
 export { formatShippingAddress, type CheckoutOrderResult, } from "./data";
 export { CHECKOUT_DEFAULT_COMMISSIONS, CHECKOUT_PAYMENT_METHODS, type CheckoutPaymentMethod, } from "../../../shared/features/checkout/config";

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

@@ -1,3 +1,3 @@
-export { createCheckoutOrderAction, attachPaymentAction, verifyAndPlaceRazorpayOrderAction, } from "./actions";
+export { createCheckoutOrderAction, attachPaymentAction, verifyAndPlaceRazorpayOrderAction, previewCheckoutPricing, resolveShippingCost, } from "./actions";
 export { formatShippingAddress, } from "./data";
 export { CHECKOUT_DEFAULT_COMMISSIONS, CHECKOUT_PAYMENT_METHODS, } from "../../../shared/features/checkout/config";

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

@@ -18,6 +18,18 @@ export interface ListGroupedListingsParams {
 export declare function listGroupedListings(params?: ListGroupedListingsParams): Promise<GroupedListingDocument[]>;
 /** Featured grouped listings for homepage strips. */
 export declare const listFeaturedGroupedListings: (limit?: number) => Promise<GroupedListingDocument[]>;
+/**
+ * Groups a product belongs to that are eligible to render publicly —
+ * powers the "You might also like" / "Same character" / etc. carousel
+ * on product-based listing detail pages. Deduped per request.
+ */
+export declare const getGroupsForProduct: (productId: string) => Promise<GroupedListingDocument[]>;
+/**
+ * Groups a product belongs to, each hydrated with its OTHER member products
+ * (the current product is excluded from its own group's item list) — ready
+ * to render directly as a public GroupedListingsCarousel section.
+ */
+export declare const getGroupsWithItemsForProduct: (productId: string) => Promise<GroupedListingWithItems[]>;
 export interface SitemapGroupedListing {
     slug: string;
     updatedAt: Date;

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

@@ -3,7 +3,7 @@ import { getAdminDb } from "../../../../providers/db-firebase";
 import { normalizeError } from "../../../../errors/normalize";
 import { serverLogger } from "../../../../monitoring/server-logger";
 import { GROUPED_LISTINGS_COLLECTION, } from "../../../../features/grouped/schemas/firestore";
-import { productRepository } from "../../../../repositories";
+import { productRepository, groupedListingsRepository } from "../../../../repositories";
 import { PRODUCT_FIELDS, CATEGORY_FIELDS } from "../../../../constants/field-names";
 import { GROUPED_LISTINGS_FEATURED_LIMIT, GROUPED_LISTINGS_PAGE_SIZE, GROUPED_LISTINGS_SITEMAP_LIMIT, } from "../../../shared/features/grouped/config";
 function mapDoc(doc) {
@@ -107,6 +107,31 @@ export async function listGroupedListings(params = {}) {
 export const listFeaturedGroupedListings = cache(async (limit = GROUPED_LISTINGS_FEATURED_LIMIT) => {
     return listGroupedListings({ featuredOnly: true, limit });
 });
+/**
+ * Groups a product belongs to that are eligible to render publicly —
+ * powers the "You might also like" / "Same character" / etc. carousel
+ * on product-based listing detail pages. Deduped per request.
+ */
+export const getGroupsForProduct = cache(async (productId) => {
+    return groupedListingsRepository.findByProductId(productId).catch((err) => {
+        void normalizeError(err);
+        serverLogger.warn("grouped-data: getGroupsForProduct failed — returning empty", { productId, error: err instanceof Error ? err.message : String(err) });
+        return [];
+    });
+});
+/**
+ * Groups a product belongs to, each hydrated with its OTHER member products
+ * (the current product is excluded from its own group's item list) — ready
+ * to render directly as a public GroupedListingsCarousel section.
+ */
+export const getGroupsWithItemsForProduct = cache(async (productId) => {
+    const groups = await getGroupsForProduct(productId);
+    return Promise.all(groups.map(async (group) => {
+        const otherIds = group.productIds.filter((id) => id !== productId);
+        const items = await Promise.all(otherIds.map((id) => productRepository.findByIdOrSlug(id).catch(() => null)));
+        return { ...group, items: items.filter((p) => p !== null) };
+    }));
+});
 export async function listSitemapGroupedListings() {
     try {
         const db = getAdminDb();

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

@@ -1,2 +1,2 @@
-export { getGroupedListingForDetail, getGroupedListingWithItems, listGroupedListings, listFeaturedGroupedListings, listSitemapGroupedListings, type GroupedListingWithItems, type ListGroupedListingsParams, type SitemapGroupedListing, } from "./data";
+export { getGroupedListingForDetail, getGroupedListingWithItems, listGroupedListings, listFeaturedGroupedListings, listSitemapGroupedListings, getGroupsForProduct, getGroupsWithItemsForProduct, type GroupedListingWithItems, type ListGroupedListingsParams, type SitemapGroupedListing, } from "./data";
 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,2 @@
-export { getGroupedListingForDetail, getGroupedListingWithItems, listGroupedListings, listFeaturedGroupedListings, listSitemapGroupedListings, } from "./data";
+export { getGroupedListingForDetail, getGroupedListingWithItems, listGroupedListings, listFeaturedGroupedListings, listSitemapGroupedListings, getGroupsForProduct, getGroupsWithItemsForProduct, } from "./data";
 export { GROUPED_LISTINGS_PAGE_SIZE, GROUPED_LISTINGS_FEATURED_LIMIT, GROUPED_LISTINGS_SITEMAP_LIMIT, } from "../../../shared/features/grouped/config";

package/dist/_internal/server/features/products/data.d.ts

@@ -1,9 +1,16 @@
 import type { ProductDocument } from "../../../../features/products/schemas/firestore";
 import type { ListingType } from "../../../../features/products/types";
+import type { ProductItem } from "../../../../features/products/types";
+import type { FirestoreDocument } from "../../../../schemas/types";
+import type { Review } from "../../../../features/reviews/types";
 /** Fetch a single product by slug or id, deduped per request. */
 export declare const getProductForDetail: (slugOrId: string) => Promise<ProductDocument | null>;
 /** Fetch the first page of approved reviews for a product, deduped per request. */
 export declare const getReviewsForProduct: (productId: string) => Promise<unknown[]>;
+/** Firestore review doc → client Review shape. Shared by every listing-type detail page's reviews tab. */
+export declare function toReview(doc: FirestoreDocument): Review;
+/** Fetch + map approved reviews for a product straight to the client Review shape, deduped per request. */
+export declare const getReviewItemsForProduct: (productId: string) => Promise<Review[]>;
 /** Minimal product fields needed for sitemap generation. */
 export interface SitemapProduct {
     slugOrId: string;
@@ -13,3 +20,19 @@ export interface SitemapProduct {
 }
 /** List all published products for sitemap generation. */
 export declare function listSitemapProducts(): Promise<SitemapProduct[]>;
+export interface RelatedItemsResult {
+    relatedItems: ProductItem[];
+    relatedByBrand: ProductItem[];
+    relatedByTags: ProductItem[];
+    relatedByStore: ProductItem[];
+}
+/** Firestore doc → card-grid shape. Shared by every related/similar-items carousel. */
+export declare function toProductItem(doc: FirestoreDocument): ProductItem;
+/**
+ * Same 4-signal related-items computation used across every listing-type
+ * detail page (category / brand / tag-overlap / same-store), each excluding
+ * invalid states for that item's own listing type. Extracted from
+ * ProductDetailPageView so pre-order/prize-draw/classified/digital-code/live
+ * pages can reuse it instead of having no related section at all.
+ */
+export declare const computeRelatedItems: (product: ProductDocument) => Promise<RelatedItemsResult>;

package/dist/_internal/server/features/products/data.js

@@ -7,6 +7,7 @@ import { serverLogger } from "../../../../monitoring/server-logger";
 import { PRODUCT_COLLECTION } from "../../../../features/products/schemas/firestore";
 import { PRODUCTS_SITEMAP_LIMIT } from "../../../shared/features/products/config";
 import { PRODUCT_FIELDS } from "../../../../constants/field-names";
+import { SIEVE_OP, sieveAnd, sieveFilter, sortBy } from "../../../../utils/sieve-builder";
 // ---------------------------------------------------------------------------
 // Request-scoped cache — each function is deduplicated per RSC render tree.
 // Both generateMetadata() and the page component get the same promise.
@@ -23,6 +24,38 @@ export const getProductForDetail = cache(async (slugOrId) => {
 export const getReviewsForProduct = cache(async (productId) => {
     return reviewRepository.findApprovedByProduct(productId).catch(() => []);
 });
+/** Firestore review doc → client Review shape. Shared by every listing-type detail page's reviews tab. */
+export function toReview(doc) {
+    const images = Array.isArray(doc.images) ? doc.images : undefined;
+    const createdAt = doc.createdAt instanceof Date
+        ? doc.createdAt.toISOString()
+        : typeof doc.createdAt === "string"
+            ? doc.createdAt
+            : undefined;
+    const rawRating = typeof doc.rating === "number" ? doc.rating : 3;
+    const rating = Math.min(5, Math.max(1, Math.round(rawRating)));
+    return {
+        id: String(doc.id ?? ""),
+        productId: String(doc.productId ?? ""),
+        userId: String(doc.userId ?? ""),
+        userName: String(doc.userName ?? "Anonymous"),
+        userAvatar: typeof doc.userAvatar === "string" ? doc.userAvatar : undefined,
+        rating,
+        title: typeof doc.title === "string" ? doc.title : undefined,
+        comment: typeof doc.comment === "string" ? doc.comment : undefined,
+        images,
+        status: doc.status ?? "approved",
+        helpfulCount: typeof doc.helpfulCount === "number" ? doc.helpfulCount : undefined,
+        verified: doc.verified === true,
+        featured: doc.featured === true,
+        createdAt,
+    };
+}
+/** Fetch + map approved reviews for a product straight to the client Review shape, deduped per request. */
+export const getReviewItemsForProduct = cache(async (productId) => {
+    const docs = await reviewRepository.findApprovedByProduct(productId).catch(() => []);
+    return docs.map(toReview);
+});
 /** List all published products for sitemap generation. */
 export async function listSitemapProducts() {
     try {
@@ -54,3 +87,129 @@ export async function listSitemapProducts() {
         return [];
     }
 }
+// ---------------------------------------------------------------------------
+// Related items — same 4-signal computation shared by every listing-type
+// detail page (category / brand / tag-overlap / same-store).
+// ---------------------------------------------------------------------------
+const RELATED_QUERY_PAGE_SIZE = 9;
+const RELATED_DISPLAY_LIMIT = 8;
+/** Firestore doc → card-grid shape. Shared by every related/similar-items carousel. */
+export function toProductItem(doc) {
+    return {
+        id: String(doc.id ?? ""),
+        title: String(doc.title ?? doc.name ?? ""),
+        price: typeof doc.price === "number" ? doc.price : 0,
+        originalPrice: typeof doc.originalPrice === "number" ? doc.originalPrice : undefined,
+        mainImage: Array.isArray(doc.images)
+            ? doc.images[0]
+            : typeof doc.mainImage === "string"
+                ? doc.mainImage
+                : undefined,
+        status: doc.status ?? "published",
+        slug: typeof doc.slug === "string" ? doc.slug : undefined,
+        storeName: typeof doc.storeName === "string" ? doc.storeName : undefined,
+        rating: typeof doc.rating === "number" ? doc.rating : undefined,
+        reviewCount: typeof doc.reviewCount === "number" ? doc.reviewCount : undefined,
+        // Without this, every related-item card silently linked to the standard
+        // PDP regardless of its real type (pluginFor() defaults to "standard"
+        // when listingType is missing) — same bug class as the Phase 1 routing
+        // fix, one hop further downstream in the related-items card link path.
+        listingType: doc.listingType ?? undefined,
+    };
+}
+/**
+ * Excludes the current product plus any listing-type-specific "invalid to
+ * surface as related" state: sold/archived/out-of-stock/draft, ended
+ * auctions, closed prize-draws, sold-out pre-orders, depleted digital-code
+ * pools.
+ */
+function isValidRelatedItem(r, currentProductId, now) {
+    if (r.id === currentProductId)
+        return false;
+    const s = r.status;
+    if (s && ["sold", "out_of_stock", "archived", "discontinued", "draft"].includes(s))
+        return false;
+    if (r.isSold === true)
+        return false;
+    if (r.availableQuantity === 0)
+        return false;
+    if (r.listingType === "auction" && r.auctionEndDate) {
+        const end = r.auctionEndDate;
+        const endDate = typeof end.toDate === "function"
+            ? end.toDate()
+            : end instanceof Date
+                ? end
+                : new Date(String(end));
+        if (endDate <= now)
+            return false;
+    }
+    if (r.listingType === "prize-draw" && r.prizeRevealStatus === "closed")
+        return false;
+    if (r.listingType === "pre-order" &&
+        typeof r.preOrderMaxQuantity === "number" &&
+        typeof r.preOrderCurrentCount === "number" &&
+        r.preOrderCurrentCount >= r.preOrderMaxQuantity) {
+        return false;
+    }
+    if (r.listingType === "digital-code" && r.codesAvailable === 0)
+        return false;
+    return true;
+}
+function toRelatedItems(docs, currentProductId) {
+    const now = new Date();
+    return docs
+        .filter((r) => isValidRelatedItem(r, currentProductId, now))
+        .slice(0, RELATED_DISPLAY_LIMIT)
+        .map(toProductItem);
+}
+/**
+ * Same 4-signal related-items computation used across every listing-type
+ * detail page (category / brand / tag-overlap / same-store), each excluding
+ * invalid states for that item's own listing type. Extracted from
+ * ProductDetailPageView so pre-order/prize-draw/classified/digital-code/live
+ * pages can reuse it instead of having no related section at all.
+ */
+export const computeRelatedItems = cache(async (product) => {
+    const p = product;
+    const primaryCategorySlug = Array.isArray(p.categorySlugs) ? p.categorySlugs[0] : undefined;
+    const brand = typeof p.brand === "string" ? p.brand : undefined;
+    const tags = Array.isArray(p.tags) ? p.tags : [];
+    const storeId = typeof p.storeId === "string" ? p.storeId : undefined;
+    const currentProductId = product.id;
+    const [sameCategoryDocs, sameBrandDocs, tagOverlapDocs, sameStoreDocs] = await Promise.all([
+        primaryCategorySlug
+            ? productRepository.findByCategory(primaryCategorySlug).catch(() => [])
+            : Promise.resolve([]),
+        brand
+            ? productRepository
+                .list({
+                filters: sieveAnd(sieveFilter("status", SIEVE_OP.EQ, "published"), sieveFilter("brand", SIEVE_OP.EQ, brand)),
+                sorts: sortBy("createdAt", "DESC"),
+                page: 1,
+                pageSize: RELATED_QUERY_PAGE_SIZE,
+            })
+                .then((r) => r.items)
+                .catch(() => [])
+            : Promise.resolve([]),
+        tags.length > 0
+            ? productRepository.findByTagsOverlap(tags, RELATED_QUERY_PAGE_SIZE).catch(() => [])
+            : Promise.resolve([]),
+        storeId
+            ? productRepository
+                .list({
+                filters: sieveAnd(sieveFilter("status", SIEVE_OP.EQ, "published"), sieveFilter("storeId", SIEVE_OP.EQ, storeId)),
+                sorts: sortBy("createdAt", "DESC"),
+                page: 1,
+                pageSize: RELATED_QUERY_PAGE_SIZE,
+            })
+                .then((r) => r.items)
+                .catch(() => [])
+            : Promise.resolve([]),
+    ]);
+    return {
+        relatedItems: toRelatedItems(sameCategoryDocs, currentProductId),
+        relatedByBrand: toRelatedItems(sameBrandDocs, currentProductId),
+        relatedByTags: toRelatedItems(tagOverlapDocs, currentProductId),
+        relatedByStore: toRelatedItems(sameStoreDocs, currentProductId),
+    };
+});

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

@@ -1,4 +1,4 @@
-export { getProductForDetail, getReviewsForProduct, listSitemapProducts, type SitemapProduct, } from "./data";
+export { getProductForDetail, getReviewsForProduct, listSitemapProducts, type SitemapProduct, computeRelatedItems, toProductItem, toReview, getReviewItemsForProduct, type RelatedItemsResult, } from "./data";
 export { assertProductOwnership, assertStatusTransition, assertInStock, effectivePrice, isAvailableForPurchase, } from "./service";
 export { createProductAction, createAuctionAction, createPreOrderAction, updateProductAction, deleteProductAction, setProductStatusAction, setProductFeaturedAction, } from "./actions";
 export { PRODUCTS_PAGE_SIZE, PRODUCTS_FEATURED_LIMIT, PRODUCTS_RELATED_LIMIT, PRODUCTS_SITEMAP_LIMIT } from "../../../shared/features/products/config";

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

@@ -1,4 +1,4 @@
-export { getProductForDetail, getReviewsForProduct, listSitemapProducts, } from "./data";
+export { getProductForDetail, getReviewsForProduct, listSitemapProducts, computeRelatedItems, toProductItem, toReview, getReviewItemsForProduct, } from "./data";
 export { assertProductOwnership, assertStatusTransition, assertInStock, effectivePrice, isAvailableForPurchase, } from "./service";
 export { createProductAction, createAuctionAction, createPreOrderAction, updateProductAction, deleteProductAction, setProductStatusAction, setProductFeaturedAction, } from "./actions";
 export { PRODUCTS_PAGE_SIZE, PRODUCTS_FEATURED_LIMIT, PRODUCTS_RELATED_LIMIT, PRODUCTS_SITEMAP_LIMIT } from "../../../shared/features/products/config";

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

@@ -7,12 +7,13 @@ export function buildRobots({ siteUrl }) {
                 disallow: [
                     "/admin/",
                     "/api/", // audit-hardcoded-api-routes-ok: robots.txt disallow prefix, not an endpoint reference
-                    "/seller/",
+                    "/store/",
                     "/user/",
                     "/auth/",
                     "/checkout/",
                     "/cart/",
-                    "/demo/",
+                    "/wishlist",
+                    "/preview/",
                     "/track/",
                     "/unauthorized/",
                     "/_next/",